Track ads on Roku track-ads-on-roku

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

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

Ad tracking constants

Constant name
Constant for tracking AdBreak Start event
Constant for tracking AdBreak Complete event
Constant for tracking Ad Start event
Constant for tracking Ad Complete event
Constant for tracking Ad Skip event

Implementation steps

  1. 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 starting with 1. Yes
    startTime Playhead value at the start of the ad break. Yes
    code language-none
    ‘ Create an adbreak info object
    adBreakInfo = adb_media_init_adbreakinfo() = <ADBREAK_NAME>
    adBreakInfo.startTime = <START_TIME>
    adBreakInfo.position = <POSITION>
  2. Call trackEvent() with AdBreakStart in the MediaHeartbeat instance to begin tracking the ad break:

    code language-none
    contextData = {}
    ADBMobile().mediaTrackEvent(MEDIA_AD_BREAK_START, adBreakInfo, contextData)
  3. Identify when the ad asset starts and create an AdObject instance using the ad information.

    code language-none
    adInfo =
  4. Optionally attach standard and/or ad metadata to the media tracking session through context data variables.

    • Implement standard ad metadata on Roku

    • Custom ad metadata - For custom metadata, create a variable object for the custom data variables and populate with the data for the current ad asset:

      code language-none
      contextData = {}
      contextData["adinfo1"] = "adinfo2"
      contextData["adinfo2"] = "adinfo2"
  5. Call trackEvent() with the AdStart event in the MediaHeartbeat instance to begin tracking the ad playback:

    code language-none
    ADBMobile().mediaTrackEvent(ADBMobile().MEDIA_AD_START, adInfo, contextData)
  6. When the ad asset playback reaches the end of the ad, call trackEvent() with the AdComplete event.

    code language-none
    standardAdMetadata = {}
    contextData = {}
    ADBMobile().mediaTrackEvent(ADBMobile().MEDIA_AD_COMPLETE, adInfo, contextData)
  7. If ad playback did not complete because the user chose to skip the ad, track the AdSkip event:

    code language-none
    contextData = {}
    ADBMobile().mediaTrackEvent(ADBMobile().MEDIA_AD_SKIP, adInfo, contextData
  8. If there are any additional ads within the same AdBreak, repeat steps 3 through 7 again.

  9. When the ad break is complete, use the AdBreakComplete event to track:

    code language-none
    contextData = {}
    ADBMobile().mediaTrackEvent(MEDIA_AD_BREAK_COMPLETE, adBreakInfo, contextData)

See the tracking scenario VOD playback with pre-roll ads for more information.