# Media tracking with the Flutter tracker
> Track media playback events in Flutter applications using the built-in media tracking capabilities available since version 0.7.0.
> Source: https://docs.snowplow.io/docs/sources/flutter-tracker/tracking-events/media-tracking/
> Documentation index: https://docs.snowplow.io/llms.txt

> **Note: Introduced in version 0.7 of the tracker**
>
> Media tracking is available in the Flutter tracker since version 0.7.0.

The Snowplow media tracking APIs enable you to track events from media playback on the web and in mobile apps. Track changes in playback state (play, pause, seek), playback position (ping and percentage progress events), and ad playback (ad breaks, ad progress, ad clicks).

For details on the events and entities tracked, see the [media tracking overview](/docs/events/ootb-data/media-events/).

> **Info: Example app**
>
> See the tracked media events and entities live as you watch a video in our [React example app](https://snowplow-industry-solutions.github.io/snowplow-javascript-tracker-examples/media). [View the source code](https://github.com/snowplow-industry-solutions/snowplow-javascript-tracker-examples/tree/master/react).

## Quick start

A media tracking session follows this lifecycle:

1. **Start tracking** when the player loads (before playback begins)
2. **Update player state** every second during playback
3. **Track events** as they occur (play, pause, seek, etc.)
4. **End tracking** when the user leaves

```dart
// 1. Start tracking when player loads
final id = const Uuid().v4();
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: MediaTrackingConfiguration(
      id: id,
      player: const MediaPlayerEntity(
          duration: 300,
          label: 'My Video Title',
          mediaType: MediaType.video,
      )
  )
);

// 2. Update player state every second
await mediaTracking.update(
  player: MediaPlayerEntity(currentTime: currentTime)
);

// 3. Track events as they occur
await mediaTracking.track(MediaPlayEvent());
await mediaTracking.track(MediaPauseEvent());
await mediaTracking.track(MediaSeekStartEvent());
await mediaTracking.track(MediaSeekEndEvent());
await mediaTracking.track(MediaEndEvent());

// 4. End tracking when done
await tracker.endMediaTracking(id: id);
```

> **Info: Flutter web configuration**
>
> To track media events on web with the Flutter tracker, configure the JavaScript plugin URL:
>
> ```dart
> SnowplowTracker tracker = await Snowplow.createTracker(
>   namespace: namespace,
>   endpoint: endpoint,
>   trackerConfig: const TrackerConfiguration(
>       jsMediaPluginURL: "https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-media@4.10.2/dist/index.umd.min.js"
>   )
> );
> ```

## Configuration

Configure media tracking when you call `startMediaTracking`. All configuration is optional.

### Player properties

Set initial player properties to populate the [media player entity](/docs/events/ootb-data/media-events/#media-player). The `label` property is recommended as it helps identify content during analysis.

```dart
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(
      id: id,
      player: MediaPlayerEntity(
          currentTime: 0,          // Current playback position in seconds
          duration: 300,           // Total duration in seconds
          ended: false,            // Whether playback has ended
          livestream: false,       // Whether this is a live stream
          label: 'My Video',       // Human-readable title (recommended)
          loop: false,             // Whether to restart after ending
          mediaType: MediaType.video, // MediaType.video or MediaType.audio
          muted: false,            // Whether audio is muted
          paused: true,            // Whether playback is paused
          pictureInPicture: false, // Whether in picture-in-picture mode
          playerType: 'html5',     // Player type identifier
          playbackRate: 1.0,       // Playback speed (1 = normal)
          quality: '1080p',        // Quality level
          volume: 100              // Volume percentage (0-100)
      )
  )
);
```

### Ping events

Media ping events are sent at regular intervals (default: 30 seconds) to report playback position. You can configure ping behavior in the starting configuration.

```dart
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(
      id: id,
      pingInterval: 30,   // Seconds between pings (default: 30)
      maxPausedPings: 1   // Max pings while paused (default: 1)
  )
);

// Or turn off pings entirely
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(id: id, pings: false)
);
```

### Percentage progress

Track events when playback reaches specified percentage boundaries.

```dart
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(
      id: id,
      boundaries: [10, 25, 50, 75, 90]  // Fire events at these percentages
  )
);
```

### Session tracking

The [media session entity](/docs/events/ootb-data/media-events/#media-session) is attached to all media events by default. It's optional for the [Media Player](/docs/modeling-your-data/modeling-your-data-with-dbt/dbt-models/dbt-media-player-data-model/) data model, so you could choose not to include it.

We recommend tracking this entity.

```dart
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(id: id, session: true)
);
```

### Custom entities

You can attach custom entities to all events for this media tracking instance.

```dart
MediaTracking mediaTracking = await tracker.startMediaTracking(
  configuration: const MediaTrackingConfiguration(
      id: id,
      contexts: [
          SelfDescribing(
              schema: "iglu:com.example/video_metadata/jsonschema/1-0-0",
              data: {"contentId": "abc123", "category": "tutorial"}
          )
      ]
  )
);
```

### Filter events

Media event filtering isn't available for the Flutter tracker.

## Tracking events

Track events by calling the appropriate function when player events occur. For a complete list of available events and their properties, see the [media events reference](/docs/events/ootb-data/media-events/#playback-lifecycle-events).

### Playback events

```dart
await mediaTracking.track(MediaReadyEvent());        // Player is ready
await mediaTracking.track(MediaPlayEvent());         // Playback started
await mediaTracking.track(MediaPauseEvent());        // Playback paused
await mediaTracking.track(MediaEndEvent());          // Playback ended
await mediaTracking.track(MediaSeekStartEvent());    // Seek operation started
await mediaTracking.track(MediaSeekEndEvent());      // Seek operation ended
await mediaTracking.track(MediaBufferStartEvent());  // Buffering started
await mediaTracking.track(MediaBufferEndEvent());    // Buffering ended
```

### Player state events

```dart
await mediaTracking.track(const MediaPlaybackRateChangeEvent(newRate: 1.5));
await mediaTracking.track(const MediaVolumeChangeEvent(newVolume: 80));
await mediaTracking.track(const MediaFullscreenChangeEvent(fullscreen: true));
await mediaTracking.track(const MediaPictureInPictureChangeEvent(pictureInPicture: true));
await mediaTracking.track(const MediaQualityChangeEvent(
  newQuality: '1080p',
  bitrate: 5000,
  framesPerSecond: 30,
  automatic: true
));
await mediaTracking.track(const MediaErrorEvent(
  errorCode: '500',
  errorName: 'NetworkError',
  errorDescription: 'Failed to load media'
));
```

### Ad events

Track advertising events with ad and ad break information. See the [media ad](/docs/events/ootb-data/media-events/#media-ad) and [media ad break](/docs/events/ootb-data/media-events/#media-ad-break) entity schemas for property details.

```dart
// Ad break events
await mediaTracking.track(
  MediaAdBreakStartEvent(),
  adBreak: const MediaAdBreakEntity(
      breakId: 'break-1',
      name: 'pre-roll',
      breakType: MediaAdBreakType.linear,
      podSize: 3
  )
);
await mediaTracking.track(MediaAdBreakEndEvent());

// Ad events
await mediaTracking.track(
  MediaAdStartEvent(),
  ad: const MediaAdEntity(
      adId: 'ad-1',
      name: 'Product Ad',
      creativeId: 'creative-1',
      duration: 30,
      skippable: true
  )
);
await mediaTracking.track(MediaAdFirstQuartileEvent());
await mediaTracking.track(MediaAdMidpointEvent());
await mediaTracking.track(MediaAdThirdQuartileEvent());
await mediaTracking.track(MediaAdCompleteEvent());
await mediaTracking.track(MediaAdSkipEvent());
await mediaTracking.track(MediaAdClickEvent());
await mediaTracking.track(MediaAdPauseEvent());
await mediaTracking.track(MediaAdResumeEvent());
```

### Custom events

Track custom self-describing events within the media session. The tracker automatically attaches media entities.

```dart
await mediaTracking.track(
  const SelfDescribing(
      schema: "iglu:com.example/video_interaction/jsonschema/1-0-0",
      data: {"action": "share", "platform": "twitter"}
  )
);
```

## Update player state

Update the player state every second during playback. This ensures accurate metrics in ping events and the session entity. This function does not send any events.

```dart
await mediaTracking.update(
  player: MediaPlayerEntity(currentTime: currentTime)
);
```
