Implementing Client-Side Ads with the Native SDKs

In this topic, you will learn how to play client-side ads with the Brightcove Native SDKs.

Overview

Client-side ads involve making a request to the ad server from the client device. This may cause some buffering time while the ad video is retrieved. For a more tv-like experience, you can use server-side ad insertion.

With client-side ads, the content video plays until either an ad cue point is detected, or an ad timing from the VMAP response is reached. A request is made to the configured ad server, which responds with ad details. The player then starts playback of the requested ad.

The Brightcove Native SDKs provide plugins for the following technologies:

The Native SDKs support the VMAP generated when using Google's Ad Manager and DoubleClick for Publishers (DFP), the Google AdSense network.

PAL SDK

The PAL SDK is not needed for CSAI (client-side advertising insertion). Programmatic advertising identifiers are handled automatically by the IMA3 SDK used by the IMA3 plugin.

Types of ads

There are three main types of ads you can use with videos:

Linear ads - Ads that pause the main content video and are displayed in the full frame of the player

Non-linear ads - Overlay ads displayed over the main content video. These can be text, graphical images or even video overlays.

Companion ads - Ads displayed outside of the video player

Ad standards

Standard XML files can be used to tell the player when to play your ads and which ads to play. The Interactive Advertising Bureau (IAB) has come up with the following common interfaces between video players and ad units:

Video Ad Serving Template (VAST) - A universal XML schema for serving ads to digital video players. This file specifies what ads to display.

Video Multiple Ad Playlist (VMAP) - This file describes a playlist of VAST ads, including pre-roll, mid-roll, post-roll and non-linear ads. Here, you can specify when ad breaks occur, and what ads that will play during each break.

Video Player Ad-Serving Interface Definition (VPAID) - Establishes a common interface for providing interactive ad experiences.

If you are new to advertising terms, start by reviewing the Learning Guide for Video Advertising.

Play ads from your app

To play client-side ads, follow these steps:

  1. Define ad tags
  2. Verify ad tags
  3. Create cue points

  4. Build your app

Define ad tags

The ad tag defines the ad that will be retrieved and played. You can use one of the following formats:

Verify ad tags

It is good practice to verify that your ad tags are valid and work as expected. This will help with debugging other issues during the implementation process.

Google provides a Video Suite Inspector for you to check your ad tags.

FreeWheel provides an Ad Previewer to check the ad server response.

Create cue points

If you are using a VMAP ad tag, you can skip this step. The VMAP defines a playlist for your ads and specifies when they will play. Note that Google's IMA Ad Rules uses VMAP.

If you are using VAST ad tags, then you need to create cue points to tell the player when to insert ads. You must create these in your app. Here are some examples for how to do that:

Android

iOS

Android Implementation

The Native SDK for Android supports VMAP, VAST, server-side ad rules and companion ads with the following technologies:

Google IMA

Follow these steps to use Google IMA Ad Rules:

  1. Locate and review the Ad Rules IMA sample app.
  2. Open the MainActivity.java file.

  3. Customize the project with your values. The following values are needed to retrieve content from your Video Cloud library:

    • Playback API Policy Key
    • Account ID
    • Video ID

  4. Include values to access your IMA ads:

    • Ad Rules URL
  5. The setupGoogleIMA() method establishes a connection with the Brightcove IMA plugin.
  6. Listen for the GoogleIMAEventType.ADS_REQUEST_FOR_VIDEO event. Here, you will build an ads request object and point to your Ad Tag URL. In this case, it is an Ad Rules VMAP file.
  7. The setupAdMarkers() method is optional. This method calls the IMA AdManager and creates ad markers on the seek bar, so that users can visually see when ads will play.

Seek without ads

When you want to disable ad playback while the user is seeking through the video, refer to the Seek without ads code snippet.

Code samples

Here are complete code samples:

  • Basic IMA Vast player: To use VAST tags, your app should create a set of cue points from the Video object metadata returned from the Playback API call. The metadata will include the ad cue points that you created in Video Cloud Studio.

  • IMA Ad Rules IMA player: Alternatively, your app can create a set of cue point objects in the player Activity class.

  • Ad Rules IMA Widevine Modular: Combine client-side ads with content protection.

FreeWheel

These ads require that you purchase the FreeWheel AdManager library.

Follow these steps to use FreeWheel ads:

  1. Contact FreeWheel to purchase their AdManager.aar library archive and install it into your libs/ directory, which is typically located at the root of your /home/ directory. The Native SDK for Android and the FreeWheel sample apps require the FreeWheel AdManager library version 6.28.0.
  2. Locate and review the FreeWheel sample app.
  3. Open the MainActivity.java file.
  4. Customize the project with your values. This sample uses a remote video asset.

  5. Include values to access your FreeWheel ads:

    • Ad URL
    • Ad Network ID
    • Ad Profile
  6. The setupFreeWheel() method establishes a connection with the Brightcove FreeWheel plugin.
  7. Configure the FreeWheel controller to point to your Ad URL. freeWheelController.setAdURL("http://demo.v.fwmrm.net/");
  8. This will be used later to instantiate the FreeWheel AdRequestConfiguration class.
  9. Listen for the FreeWheelEventType.WILL_SUBMIT_AD_REQUEST event. Here, you will get the FreeWheel controller and setup the pre-roll, mid-roll, post-roll and overlay ad slots.

Seek without ads

When you want to disable ad playback while the user is seeking through the video, refer to the Seek without ads code snippet.

Code samples

Here are complete code samples:

iOS Implementation

The Native SDK for iOS supports VMAP, VAST, server-side ad rules and companion ads with the following technologies:

Google IMA

For details about installation, quick start and use, see the IMA Plugin for Brightcove Player SDK for iOS reference.

Follow these steps to use Google IMA Ads:

  1. Locate and review the Basic IMA Player sample app.
  2. Open the ViewController file.

  3. Customize the project with your values. The following values are needed to retrieve content from your Video Cloud library:

    • Playback API Policy Key
    • Account ID
    • Video ID

  4. Include values to access your IMA ads:

    • Publisher ID
    • Language
    • Ad Tag URL
  5. Create the playbackController with the appropriate IMA settings, including the ad request policy (VAST, VMAP or server-side ad rules).
  6. Ad events are emitted by the BCOVIMA plugin through lifecycle events. These events are defined in BCOVIMAComponent.h file.
  7. The sample app includes functions to hide the player controls while ads are playing and show them when ads are finished.

Seek without ads

When you want to disable ad playback while the user is seeking through the video, refer to the Seek without ads section of the plugin reference.

Code samples

Here are complete code samples:

FreeWheel

The Freewheel AdManager SDK is not installed by using CocoaPods. Instead, you must manually add it to the application target of your project.

Follow these steps to use FreeWheel ads:

  1. Manually add the FreeWheel AdMananger SDK to your project. For detailed steps, see the Basic Freewheel Player's README file.
  2. Locate and review the Basic FreeWheel Player sample app.
  3. Open the ViewController file.

  4. Customize the project with your values. The following values are needed to retrieve content from your Video Cloud library:

    • Playback API Policy Key
    • Account ID
    • Video ID
  5. Create the FreeWheel AdManager. This will be responsible for all of the ad contexts.
  6. Create the session provider and the playback controller with the ad context policy.
  7. Customize the project with your own FreeWheel configuration values. Refer to FreeWheel documentation or contact your FreeWheel account manager.
  8. Configure the ad view, ad controls and companion slot.

Seek without ads

When you want to disable ad playback while the user is seeking through the video, refer to the Seek without ads section of the plugin reference.

Code sample

Here is a complete code sample: