How to subscribe to ad events

When building a custom UI, or when logging events to an analytics service, app developers often need to be able to listen (and react) to ad events. For example, if an ad break starts, they want to draw a countdown on top of their UI. Alternatively, when an ad error occurs, they want to log this to an analytics server.

This article explains how you can programmatically subscribe to ad-related events across different SDKs.

SDKs

Web SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK
Yes	Yes	Yes	Yes	Yes	No

Subscribing to an event

This subsection explains how you detect ad-related events. The other subsections zoom in on particular use-cases, such as detecting the beginning and end of an ad.

Client-side ads

If you are scheduling client-side advertisements, then you use the Ads interface to detect ad events throughout the Web, Android and iOS SDK.

Web SDK

The Player API exposes an ads property which belongs to the Ads interface. Because this Ads interface inherits from EventDispatcher<AdsEventMap>, you can leverage event listeners in this interface.

The ad-related events are documented in AdsEventMap. To subscribe to an event, you select an event from this page, use the Ads interface, call the addEventListener method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});

The following snippet should log most events to the console.

player.ads.addEventListener(
  [
    'adbegin',
    'adbreakbegin',
    'adbreakchange',
    'adbreakend',
    'adbuffering',
    'addad',
    'addadbreak',
    'adend',
    'aderror',
    'adfirstquartile',
    'adimpression',
    'adloaded',
    'admetadata',
    'admidpoint',
    'adskip',
    'adthirdquartile',
    'removeadbreak',
    'updatead',
    'updateadbreak',
  ],
  console.log
);

Note that when dealing with client-side advertisements, you have different types of integrations, as explained at How to setup VAST and VMAP. The impact of this is that some events are not available throughout all integrations.

For example, if you schedule https://cdn.theoplayer.com/demos/preroll.xml, which is a single linear VAST ad, through the "Google IMA integration" at https://demo.theoplayer.com/advertisement-tester, the above snippet will trigger the following events:

addad, updateadbreak, updatead, adloaded, adbreakbegin, adbegin, adimpression, adfirstquartile, admidpoint, adthirdquartile, adend, adbreakend, removeadbreak

When you do the same for the "default THEOplayer integration", you get the following events:

adloaded,adbreakchange,adbreakbegin,adbegin,adend,adbreakend

Android SDK

The Player API exposes an getAds() method which belongs to the Ads interface. Because this Ads interface inherits from EventDispatcher<AdEvent>, you can leverage event listeners in this interface.

The available ad events are different between the Android SDK and the Legacy Android SDK (4.12.x):

1. The Android SDK (currently) only allows ad playback through Google IMA. The available events are documented in GoogleImaAdEventType.
2. The Legacy Android SDK (4.12.x) events are documented in AdEvent and AdsEventTypes.

To subscribe to an event, you select an appropriate GoogleImaAdEventType or AdsEventType, use the Ads interface, call the addEventListener method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break with the Android SDK, you could use the following snippet:

theoPlayer.getAds().addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED, googleImaAdEvent -> Log.d("ADS", "AD_BREAK_STARTED"));

On the other hand, if you want to track the start of an ad break with the Legacy Android SDK (4.12.x), you could use the following snippet:

player.getAds().addEventListener(AdsEventTypes.AD_BREAK_BEGIN, event -> Log.i(TAG, "Event: AD_BEGIN, ad=" + event.getAdBreak()));

Note: code samples are available on our samples-android-sdk Github repository.

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

The Player API exposes an ads property which belongs to the Ads interface. Because this Ads interface inherits from EventDispatcher, you can leverage event listeners in this interface.

The ad-related events are documented in Ads Events. To subscribe to an event, you select an event from this page, use the Ads interface, call the addEventListener method, and set the event as the first parameter, and the callback as the second parameter.

For example, if you want to track the start of an ad break, you could use the following snippet:

player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}

Note: code samples are available on our samples-ios-sdk Github repository.

Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the Ads interface which you use when scheduling client-side ads.

• Google DAI: if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
• Yospace: if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our Yospace documentation.
• Verizon Media: if you're using Verizon Media, you must use the Verizon interface. You can read more about detecting ad-related events with Verizon Media at our Verizon Media documentation.

If you're building a custom server-side ad insertion solution, you might be interested in using our TextTrack API to detect id3/emsg/EventStream/EXT-X-DATERANGE cues, and the timeupdate event in the Player interface to determine the current playhead position.

Ad begin and end

Detecting the start and stop of ad breaks and individual ad pods is a common requirement. The THEOplayer API expose event listeners which allow applications to hook into these events.

Client-side ads

If you are scheduling client-side advertisements, then you use the Ads interface to detect the start and stop of ads.

Web SDK

This use-case is an application of Subscribing to an event, and relates to the following events:

• adbegin
• adbreakbegin
• adbreakend
• adend

For example, the following snippet would trigger the callback when an ad break begins:

player.ads.addEventListener('adbreakbegin', function (event) {
  console.log(event);
});

You can swap adbreakbegin for the other events, or supply an array instead:

player.ads.addEventListener(['adbegin', 'adbreakbegin', 'adbreakend', 'adend'], function (event) {
  console.log(event);
});

Android SDK

This use-case is an application of Subscribing to an event, and relates to the following events:

• adbegin
• adbreakbegin
• adbreakend
• adend

player.getAds().addEventListener(AdsEventTypes.AD_BREAK_BEGIN, event -> Log.i(TAG, "Event: AD_BREAK_BEGIN, ad=" + event.getAdBreak()));

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

This use-case is an application of Subscribing to an event, and relates to the following events:

• adbegin
• adbreakbegin
• adbreakend
• adend

player.ads.addEventListener(type: AdsEventTypes.AD_BREAK_BEGIN) { (event) in
    print(event)
}

Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the Ads interface which you use when scheduling client-side ads.

• Google DAI: if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
• Yospace: if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our Yospace documentation.
• Verizon Media: if you're using Verizon Media, you must use the Verizon interface. You can read more about detecting ad-related events with Verizon Media at our Verizon Media documentation.

If you're building a custom server-side ad insertion solution, you might be interested in using our TextTrack API to detect id3/emsg/EventStream/EXT-X-DATERANGE cues, and the timeupdate event in the Player interface to determine the current playhead position.

Ad error

Ad error events might be triggered when an ad blocker is active, or when an "empty" ad is returned. As an app developer, you might want to detect this, and possibly react to it.

Client-side ads

If you are scheduling client-side advertisements, then you use the Ads interface to detect the ad errors.

Web SDK

This use-case is an application of Subscribing to an event, specifically the aderror event.

The following snippet would trigger the callback when an ad error occurs:

player.ads.addEventListener('aderror', function (event) {
  console.log(event);
});

Android SDK

This use-case is an application of Subscribing to an event, specifically the aderror event.

The following snippet would trigger the callback when an ad error occurs:

player.getAds().addEventListener(AdsEventTypes.AD_ERROR, event -> Log.i(TAG, "Event: AD_ERROR, ad=" + event.getError()));

iOS/tvOS SDK and Legacy iOS/tvOS SDK (4.12.x)

This use-case is an application of Subscribing to an event, specifically the aderror event.

The following snippet would trigger the callback when an ad error occurs:

player.ads.addEventListener(type: AdsEventTypes.AD_ERROR) { (event) in
    print(event)
}

Server-side ads

If you're scheduling server-side ads, you might need to use a different interface than the Ads interface which you use when scheduling client-side ads.

• Google DAI: if you're using Google DAI, you can use the same API as the one for client-side ads, as described in the sections above.
• Yospace: if you're using Yospace, you must use the Yospace interface. You can read more about detecting ad-related events with Yospace at our Yospace documentation.
• Verizon Media: if you're using Verizon Media, you must use the Verizon interface. You can read more about detecting ad-related events with Verizon Media at our Verizon Media documentation.

If you're building a custom server-side ad insertion solution, you might be interested in using our TextTrack API to detect id3/emsg/EventStream/EXT-X-DATERANGE cues, and the timeupdate event in the Player interface to determine the current playhead position.

Ad block detection

Refer to the article on ad block detection for more information on detecting (and responding) to ad blockers.