DocumentationAnalyticsMedia Analytics Guide

Track ads on iOS track-ads-on-ios

Last update: Fri Nov 11 2022 00:00:00 GMT+0000 (Coordinated Universal Time)

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 tracking constants

Constant name
Description
ADBMediaHeartbeatEventAdBreakStart
Constant for tracking AdBreak Start event
ADBMediaHeartbeatEventAdBreakComplete
Constant for tracking AdBreak Complete event
ADBMediaHeartbeatEventAdStart
Constant for tracking Ad Start event
ADBMediaHeartbeatEventAdComplete
Constant for tracking Ad Complete event
ADBMediaHeartbeatEventAdSkip
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 within the content, starting with 1. Yes
    startTime Playhead value at the start of the ad break. Yes

    Ad break object creation:

    code language-none 
    id adBreakObject = [ADBMediaHeartbeat createAdBreakObjectWithName:[ADBREAK_NAME]
                            position:[POSITION]
                            startTime:[START_TIME]];

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

    code language-none 
    - (void)onAdBreakStart:(NSNotification *)notification {
    [_mediaHeartbeat trackEvent:ADBMediaHeartbeatEventAdBreakStart
                     mediaObject:adBreakObject
                     data:nil];
}

  3. 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

    Ad object creation:

    code language-none 
    id adObject = [ADBMediaHeartbeat createAdObjectWithName:[AD_NAME]
                                 adId:[AD_ID]
                                 position:[POSITION]
                                 length:[LENGTH]];

  4. Optionally attach standard and/or ad metadata to the media tracking session through context data variables.

    • Implement standard ad metadata on iOS

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

      code language-none 
      NSMutableDictionary *adDictionary = [[NSMutableDictionary alloc] init];
[adDictionary setObject:@"Sample affiliate" forKey:@"affiliate"];
[adDictionary setObject:@"Sample campaign" forKey:@"campaign"];
[adDictionary setObject:@"Sample creative" forKey:@"creative"];

  5. 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:

    code language-none 
    - (void)onAdStart:(NSNotification *)notification {
    [_mediaHeartbeat trackEvent:ADBMediaHeartbeatEventAdStart
                     mediaObject:adObject
                     data:adDictionary];
}

  6. When the ad playback reaches the end of the ad, call trackEvent() with the AdComplete event.

    code language-none 
    - (void)onAdComplete:(NSNotification *)notification {
    [_mediaHeartbeat trackEvent:ADBMediaHeartbeatEventAdComplete
                     mediaObject:nil
                     data:nil];
}

  7. If ad playback did not complete because the user chose to skip the ad, track the AdSkip event.

    code language-none 
    - (void)onAdSkip:(NSNotification *)notification {
    [_mediaHeartbeat trackEvent:ADBMediaHeartbeatEventAdSkip
                     mediaObject:nil
                     data:nil];
}

  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 
    - (void)onAdBreakComplete:(NSNotification *)notification {
    [_mediaHeartbeat trackEvent:ADBMediaHeartbeatEventAdBreakComplete
                     mediaObject:nil
                     data:nil];
}

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

recommendation-more-help
c8eee520-cef5-4f8c-a38a-d4952cfae4eb