Track ads
Ad playback tracking covers ad breaks, ad starts, ad completes, and ad skips. Use the media player’s API to identify key player events and populate the required ad variables.
Player events
Implementation steps
- Identify when the ad break boundary begins, including pre-roll, and create an ad break object. See Ad break name and Ad break start time for field definitions.
- Call Ad break start to begin tracking the ad break.
- Identify when the ad starts and create an ad object. See Ad name, Ad ID, Ad length, Ad in pod position, and Ad player name for field definitions.
- Optionally attach standard ad metadata. See Advertiser, Campaign ID, Creative ID, Creative URL, Placement ID, and Site ID for available keys.
- Call Ad start to begin tracking the ad.
- When the ad plays to completion, call Ad complete.
- If the viewer skipped the ad, call Ad skip instead of Ad complete.
- For additional ads in the same ad break, repeat steps 3 through 7.
- When the ad break is complete, call Ad break complete.
trackPlay before AdBreakStart and AdStart. The first play ping on main content increments Content starts. If trackPlay is called before the pre-roll ad events fire and the viewer drops out during the ad, Content starts is incremented even though no main content was ever played. For pre-roll scenarios, delay trackPlay until after AdBreakStart and AdStart have been sent.0 throughout the entire ad. For a mid-roll ad that starts at the 5-minute mark, the playhead remains at 300 (seconds) for the duration of the ad.Common issues
Unexpected main:play calls between ads
If you see main:play calls occurring between consecutive ads, a gap of more than 250 milliseconds exists between the AdComplete call and the next AdStart call. When this gap occurs the Media SDK falls back to sending main content pings, which can set the Content starts metric early for pre-roll scenarios.
Cause: The Media SDK has no ad information set and the player is in a playing state, so it credits the gap duration to main content.
Resolution: Delay the AdComplete call for each ad (except the last) rather than calling it immediately when the ad ends. Batch the calls as follows:
- On every ad start: If a previous ad exists and was not yet marked complete, call AdComplete before calling AdStart for the new ad.
- On every ad asset end: Do not call AdComplete immediately; defer it.
- On ad break complete: Call AdComplete for the last ad (if not already called), then call AdBreakComplete.
This pattern ensures that AdComplete and the next AdStart fire back-to-back, eliminating any gap.