When should I start a media session?
You should call startMediaTracking as soon as the player has loaded, not when playback begins. This ensures that session tracking begins immediately and allows for accurate measurement of metrics such as buffering time or time to first frame.
A media sessions should correspond to a single media playback including any ads that play before, during, or after the media. Metrics are collected against a media session so it is important to ensure it is set correctly.
What should I set as the Media Session ID?
It is recommended that the Media Session ID is set to be a random string, in the browser you can use a function such as crypto.randomUUID().
A media session ID should be unique to a play of content and a player.
Do I need to set a media label and how should I set it?
When calling startMediaTracking or updateMediaTracking it is recommended you also set the label with a human readable name of the media content so you can quickly identify which media content this media session relates to.
The label is used in combination with the media type, player type and player ID to create the media stats table with the dbt Media Player model.
When should I call trackMediaPlay?
You should call trackMediaPlay when the main media content starts playing—even if there are pre-roll ads. The media session model accounts for both total play time and play time excluding ads.
What’s the difference between trackMediaEnd and endMediaTracking?
trackMediaEnd: Fires when the media reaches 100% progress (i.e., fully watched).
endMediaTracking: Used to end the session. This cleans up event listeners and stops background pings. Call this when you want to reset session stats, even if the media wasn’t fully watched. It does not trigger or fire any events.
Note: It’s common to see sessions without a trackMediaEnd event if the user didn’t finish the video.
What if the user rewatches a video or scrubs back?
If the content finishes and the user rewinds, the same session should continue. You can utilise the time played and content watched metrics within the media session entity to understand rewatches compared to how much a user has watched of the entire media content.
How is play time calculated?
When the media session entity is tracked with media events, play time is derived from the session object in the tracker. This method provides the most accurate measurement and is updated by calling updateMediaTracking or automatically when using the HTML5, YouTube or Vimeo media trackers.
How frequently should updateMediaTracking be called?
It’s recommended to call updateMediaTracking every 1 second. This function does not send events to the collector but updates internal attributes to ensure accurate metrics for the next event.
What happens if the browser is closed or the user navigates away (SPA)?
If the user closes the browser/tab, you don’t need to call endMediaTracking—background pings stop automatically. In SPAs, if endMediaTracking is missed, you may see 1–2 additional ping events, but the number of pings is capped (using the maxPausedPings config) after the media is paused.
How should I handle livestreams?
It depends on if you want to analyze the media based on the entire livestream session or split out based on the content shown within the livestream:
If you want to analyze the livestream as a single session:
- Update the player label using updateMediaTracking when the content changes. However, this won’t split the session in the data model.
If you want to analyze the livestream as unique sections of content (if it changes):
- End and restart the media session each time the content changes. Customize media_session_id to include segments (e.g., livestream-1, livestream-2) and aggregate later using a shared prefix or livestream_id.
Do I need to track all ad-related events?
No. Tracking only trackMediaAdStart and trackMediaAdComplete is sufficient if you don’t need to attribute ads to specific ad breaks.
Note: Skipping trackMediaAdBreakStart and trackMediaAdBreakEnd means you lose details like pod size and break ID to be able to analyze all the ads within a break.
Do I need to send Media Ping events?
Yes, media ping events are used to keep the media session alive.
However, these events to do not need to be sent to the data warehouse. You can stop them being sent to the Snowplow collector using a custom plugin with the filter method or dropped within the pipeline within a custom JavaScript enrichment using event.drop().