Skip to main content
Version: 11.7.0

How to subscribe to ad events on Android

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.

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.

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

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 Android SDK currently only allows client-side ad playback through Google IMA. The available events are documented in GoogleImaAdEventType.

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, you could use the following snippet:

theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}

Ad begin and end​

Detecting the start and stop of ad breaks and individual ad pods is a common requirement.

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

  • STARTED
  • AD_BREAK_STARTED
  • AD_PERIOD_STARTED
  • AD_BREAK_ENDED
  • AD_PERIOD_ENDED
  • COMPLETED
  • ALL_ADS_COMPLETED
theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_BREAK_STARTED) {
    Log.d("ADS", "AD_BREAK_STARTED")
}

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 and possibly react to this.

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

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

theoPlayer.ads.addEventListener(GoogleImaAdEventType.AD_ERROR) {
    Log.d("ADS", "AD_ERROR")
}

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.

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.

Resources​