Track content playback
Core playback tracking covers media load, start, pause, resume, complete, and session end. Although not mandatory, buffering and seeking tracking are also core components of a complete playback implementation.
Player events
Implementation steps
- Identify when the user triggers playback (user clicks play or autoplay fires). Create a media object with content name, ID, length, stream type, and media type. See Content name, Content ID, Content length, Stream type, and Content type for field definitions.
- Optionally attach metadata: standard metadata (show, season, episode, etc.) and custom context data variables. See Show, Season, Episode, Genre, and Network for standard metadata key references.
- Call Session start to begin tracking the session. This loads the data and metadata and starts the time-to-start QoS measurement. SessionStart tracks the intent to play, not the first frame.
- Call Play when the first frame of content renders on screen.
- Call Pause start when the player pauses. Call Play again when playback resumes. There is no separate resume event.
- Call Session complete when the viewer reaches the end of content.
- Call Session end when the player is unloaded or the viewer abandons content without reaching the end. SessionEnd immediately closes the session; no further events can be tracked after it.
SessionEnd marks the end of a tracking session. If the session was successfully watched to completion, call SessionComplete before SessionEnd. Any other tracking call is ignored after SessionEnd, except for SessionStart for a new session.Core playback
The following examples show a complete session flow from session start through to content complete and session end.
For implementation details by platform, see Session start, Play, Pause start, Session complete, and Session end.
Buffering
Buffer start signals that the player is waiting for data. Buffer end is inferred when you send a Play event after BufferStart (XDM-based APIs). On Mobile SDK, also call BufferComplete explicitly.
For implementation details, see Buffer start.
Seeking
Seek start signals that the viewer is scrubbing. Seek end is followed by Play to resume content playback.
For implementation details, see Pause start (seek start) and Play (seek end).
Handling app interrupts
Playback in a media application can be interrupted in a variety of ways. Examples include when the user presses pause, the app goes to the background, or a phone call arrives. Regardless of the cause, the tracking instructions are the same:
- Call PauseStart when the application is interrupted (goes to background, media pauses, etc.).
- Call Play when the application returns to the foreground and/or the media resumes playing.
When should a paused session end? If the application does not allow background playback, call PauseStart immediately and then call SessionEnd after approximately one minute in the background. The application cannot continue sending pause pings from the background, and holding the session open indefinitely provides a poor experience. If the application does support background playback (audio apps, video podcast apps), continue sending pings while in the background.
Restarting after a long background period: If the app was backgrounded long enough that the session expired (30-minute inactivity), call SessionEnd to cleanly close any lingering session, then call SessionStart to begin a new one when the viewer returns.
Resuming inactive sessions
A session expires automatically if no events are received for 10 minutes or if there is no playhead movement for 30 minutes. If the user returns after a session has expired, call SessionStart again to open a new session.
Resuming across devices (cross-device handoff): When a viewer transfers playback between devices (for example, casting from a phone to a TV), use the resume flag to stitch the sessions together in Analytics reporting:
- On the source device, call SessionEnd when the viewer initiates the cast. Do not call SessionComplete — the content is not finished.
- On the destination device, call SessionStart with the resume flag set to
trueand pass the same content metadata and the playhead position from the source device.
Setting the resume flag causes Analytics to increment Content resumes rather than Media starts for the second leg of the handoff.
Manually resuming a previously closed session: If the application stores user data and can resume a previously closed session, set the resume flag at session start. See Session start for implementation details across all platforms.