Documentation Analytics Streaming media services guide

Overview overview

Last update: May 15, 2026

Topics:
Streaming Media

CREATED FOR:

User
Admin
Developer

The following instructions provide guidance for implementation using the 2.x SDKs.

IMPORTANT

If you are implementing a 1.x version of the SDK, you can download 1.x Developers Guides here: Download SDKs.

Ad playback includes tracking ad breaks, ad starts, ad completes, and ad skips. Use the media player’s API to identify key player events and to populate the required and optional ad variables.

Player events player-events

On ad break start

NOTE

Including pre-roll

Create an adBreak object instance for the ad break. For example, adBreakObject.
Call trackEvent for the ad break start with your adBreakObject.

On every ad asset start

Create an ad object instance for the ad asset. For example, adObject.
Populate the ad metadata, adCustomMetadata.
Call trackEvent for the ad start.

On every ad complete

Call trackEvent for the ad complete.

On ad skip

Call trackEvent for the ad skip.

On ad break complete

Call trackEvent for the ad break complete.

Implement ad tracking implement-ad-tracking

Ad tracking constants

Constant name

Description

AdBreakStart

Constant for tracking AdBreak Start event

AdBreakComplete

Constant for tracking AdBreak Complete event

AdStart

Constant for tracking Ad Start event

AdComplete

Constant for tracking Ad Complete event

AdSkip

Constant for tracking Ad Skip event

Implementation steps

Identify when the ad break boundary begins, including pre-roll, and create an AdBreakObject by using the ad break information.

AdBreakObject reference:

table 0-row-3 1-row-3 2-row-3 3-row-3 3-align-center 7-align-center 11-align-center 15-align-center
Variable Name	Description	Required
`name`	Ad break name such as pre-roll, mid-roll, and post-roll.	Yes
`position`	The number position of the ad break within the content, starting with 1.	Yes
`startTime`	Playhead value at the start of the ad break.	Yes

Call trackEvent() with AdBreakStart in the MediaHeartbeat instance to begin tracking the ad break.

Identify when the ad starts and create an AdObject instance using the ad information.

AdObject reference:

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 3-align-center 7-align-center 11-align-center 15-align-center 19-align-center
Variable Name	Description	Required
`name`	Friendly name of the ad.	Yes
`adId`	Unique identifier for the ad.	Yes
`position`	The number position of the ad within the ad break, starting with 1.	Yes
`length`	Ad length	Yes

Optionally attach standard and/or ad metadata to the tracking session through context data variables.
- Standard ad metadata - For standard ad metadata, create a dictionary of standard ad metadata key value pairs using the keys for your platform.
- Custom ad metadata - For custom metadata, create a variable object for the custom data variables and populate with the data for the current ad.
Call trackEvent() with the AdStart event in the MediaHeartbeat instance to begin tracking the ad playback.

Include a reference to your custom metadata variable (or an empty object) as the third parameter in the event call. While the ad is playing, keep the content playhead (l:event:playhead) fixed at the position where the ad break began; advancing it during ad playback overstates Content time spent.
When the ad playback reaches the end of the ad, call trackEvent() with the AdComplete event.
If ad playback did not complete because the user chose to skip the ad, track the AdSkip event.
If there are any additional ads within the same AdBreak, repeat steps 3 through 7 again.
When the ad break is complete, use the AdBreakComplete event to track it.

IMPORTANT

Pre-roll ads: do not call 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.

NOTE

The playhead value reported during ad playback represents the viewer’s position within the main content, not within the ad. For a pre-roll ad preceding a 10-minute video, the playhead is 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.

The following sample code utilizes the JavaScript 2.x SDK for an HTML5 media player.

/* Call on ad break start */

if (e.type == "ad break start") {
    var adBreakObject = MediaHeartbeat.createAdBreakObject("mid-roll", 2, 500);
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakObject);
};

/* Call on ad start */
if (e.type == "ad start") {
    var adObject = MediaHeartbeat.createAdObject("PepsiOne", "123456ab", 1, 30);
    /* Set custom context data */
    var adCustomMetadata = {
        affiliate:"Sample affiliate",
        campaign:"Sample ad campaign",
        creative:"Sample creative"
    }
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adObject, adCustomMetadata);
};

/* Call on ad complete */
if (e.type == "ad complete") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
};

/* Call on ad skip */
if (e.type == "ad skip") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdSkip);
};

/* Call on ad break complete */
if (e.type == "ad break complete") {
    this.mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
};

recommendation-more-help

media-analytics-help