Introducing the adPostrollsComplete event and getAdEnabled() APIs

Submitted by Oscar Cortes on October 7, 2010
Technology
Player API, Ad SDK
Edition
All

This article introduces two additions to Brightcove's Advertising APIs:

Using the AD_POSTROLLS_COMPLETE event

One of the features that developers have requested the most is a way to detect when all post-roll ads have completed, either when the ad completes or even when no ad is returned. Until now, there was not an easy way to detect when the process of requesting and playing post-rolls was done. If you know this, you can know precisely when you can continue with a new action after all advertising activity is complete for a video.

For example, let's say that you have built a custom playlist external to the Brightcove Player and you want to add auto-advance in that playlist using the Brightcove Player APIs. You would probably add a listener to the AD_COMPLETE event, and check the current ad insertion point to detect if the ad that just completed was a post-roll ad, and then call the VideoPlayer.loadMedia() API to load the next video on the list. However, what happens when the post-roll requests do not return an ad (which could happen if there was no more ad inventory, etc.)? Since no ad is rendered,  the AD_COMPLETE event does not fire, and your auto-advance would stop working. 

To handle this situation, we have added a new event to the Advertising API module that will allow developers to detect when all post-roll activity is complete. The new event is named AD_POSTROLLS_COMPLETE and it is part of the Advertising API. 

You use this event just like other existing ad events. First, get a reference to the Ad Module API and then add an event listener to the AD_POSTROLLS_COMPLETE event. For example: 

function onTemplateLoaded(pExperience) {
  player= brightcove.getExperience(pExperience);
  adModule = player.getModule(APIModules.ADVERTISING);
  adModule.addEventListener(BCAdvertisingEvent.AD_POSTROLLS_COMPLETE, onPostRollsComplete);
}

function onPostRollsComplete(evt){
  // Do something, like load a new video
} 

When is the AD_POSTROLLS_COMPLETE event fired?

To use this event effectively, you need to understand when this event is fired. Here is a list of scenarios and sequences where this event is fired:

  1. A single post-roll ad is requested and an ad was returned: Note that since an ad was rendered, the AD_COMPLETE event stills fires. However, if you are interested on knowing about when post-rolls complete, use AD_POSTROLLS_COMPLETE instead.
    • an ad is returned,
    • the ad is rendered,
    • the ad completes,
    • then AD_POSTROLLS_COMPLETE is fired.
  2. A single post-roll ad is requested and no ad was returned: In this case, AD_COMPLETE would not fire because no ad was rendered. But the AD_POSTROLLS_COMPLETE event fires and allows you to continue with some action even if no ad was played. AD_POSTROLLS_COMPLETE is fired when the Brightcove player has evaluated that no ad will be played. 
    • but no ad is returned,
    • then AD_POSTROLLS_COMPLETE is fired.
  3. Multiple post-roll ads are requested. A player requests multiple post-roll ads if its ad policy is set in the Brightcove Studio Advertising module to play some number of ads greater than one. For this example, let's say that this has been set up to request two post-roll ads: Note that the AD_POSTROLLS_COMPLETE event does not fire until the last of the post-roll requests have been processed and it fires just before AD_COMPLETE, either by playing the ad or after evaluating that a post-roll ad won't be played after the ad request. The AD_POSTROLLS_COMPLETE event is designed to help developers identify the right moment when all post-roll activity has completed on a video.
    • All post-roll ads are requested.
    • The first post-roll is rendered.
    • The first post-roll completes.
    • AD_COMPLETE is fired.
    • The second post-roll is rendered.
    • The second post-roll completes.
    • AD_POSTROLLS_COMPLETE is fired, and
    • AD_COMPLETE is fired.
  4. The player's ad policy is set for no post-rolls. For example, a player may have only pre-roll ad requests.  In this case, the AD_POSTROLLS_COMPLETE event can be really handy if you want to use the same API implementation across multiple Brightcove players with different ad policies. Since AD_POSTROLLS_COMPLETE is fired even when no post-rolls are requested, it would be easy to use this same code with players with and without post-rolls.
    • A pre-roll ad is requested.
    • A pre-roll is returned, rendered and completes.
    • AD_COMPLETE is fired.
    • At the end of the video, the player evaluates if post-rolls should be requested.
    • No post-rolls are requested.
    • AD_POSTROLLS_COMPLETE is fired.

Does AD_POSTROLLS_COMPLETE work with the Brightcove Ad Rules and Ad SWFs components?

Yes. The AD_POSTROLLS_COMPLETE event will fire after the adComplete() method is called on an Ad Display SWF or, in the case of Ad Rules, also after the postrollCheckComplete() method is called and no ad is being played. These two scenarios would be similar to cases 1 and 2 above, respectively.

Using the getAdEnabled() API

Another popular request, one which correlates with the use cases in this article, is for an API that would reliably tell if a player is enabled for ads or not. An existing method, getAdPolicy(), can be used to check for the ad policy and then evaluate if ads were on or off in a player. However, the new getAdEnabled() API is more straightforward. You can use it together with AD_POSTROLLS_COMPLETE when you need to detect when all activity after a video completes is done; it works both for players that are ad enabled and also for players that are not ad enabled.

For example, suppose you want to create code that you can re-use no matter what ad settings are set for a player and you want to detect when the video is complete (including advertising when the ads are enabled). In other words, when ads are enabled you want to continue with your video-complete logic after post-roll activity is complete and when ads are off you want to continue when the video completes, since you know that no ads will be requested. This is where getAdEnabled() helps the most. The solution would be something like this:

  1. Use getAdEnabled() to check if ads are enabled for the player.
  2. If they are, add a listener to the AD_POSTROLLS_COMPLETE event.
  3. If they are not enabled, instead add a listener to the MEDIA_COMPLETE event. 

For example:

function onTemplateLoaded(pExperience) {

    player= brightcove.getExperience(pExperience);
    modExp = player.getModule(APIModules.EXPERIENCE);
    modVP = player.getModule(APIModules.VIDEO_PLAYER);
    adModule = player.getModule(APIModules.ADVERTISING);
    var isAdEnabled = modExp.getAdEnabled();

    if (isAdEnabled) {
      adModule.addEventListener(BCAdvertisingEvent.AD_POSTROLLS_COMPLETE,
                                onVideoEventsComplete);
    } else {
      modVP.addEventListener(BCMediaEvent.COMPLETE, onVideoEventsComplete);
    }
}

function onVideoEventsComplete(evt){
    // Do something, like loading a new video.
}

We look forward to your implementations using these two new additions to Brightcove's advertising related APIs. Please do not hesitate to follow up with any questions in our Ad API forum.