Schedule Google IMA ads

Add advertising breaks to your content when using the Google IMA ad client in an Android app.


After adding the Google IMA SDK to your app and acquiring the required items listed in the Requirements section, you can schedule Google IMA ads in your Android app.



Requirements



Scheduling Ad Breaks

Add a pre-roll ad to a playlist

👍

IMPORTANT

If you use the IAB Open Measurement Interface Definition (OMID) and run Google IMA ads, all custom video controls that overlay the media element must be registered as friendly obstructions.

Use the following steps to add a pre-roll ad to the player you added to your activity:

  1. In the Activity, create a List<AdBreak> object and name it, for example, adSchedule.
  2. Use AdBreak.Builder() to create an AdBreak object. At the minimum, you must pass an ad tag to the tag property. The ad tag can have custom parameters appended. We strongly recommend using a secure ad tag URL.
  3. Add the AdBreak object to adSchedule.
  4. Use ImaAdvertisingConfig.Builder() to create an ImaAdvertisingConfig object. Use adSchedule -- which defines the ad schedule to use -- as the argument.
  5. Use PlayerConfig.Builder() to add the ImaAdvertisingConfig object to the PlayerConfig object of the player. This adds the ad schedule to the player.
mPlayerView.getPlayerAsync(this, getLifecycle(), (JWPlayer player) -> {
   mPlayer = player;
   List<AdBreak> adSchedule = new ArrayList<>();

   AdBreak adBreak = new AdBreak.Builder()
           .tag("https://www.domain.com/adtag.xml")
           .offset("pre")
           .build();
        
   adSchedule.add(adBreak);

   ImaAdvertisingConfig imaAdvertising = new ImaAdvertisingConfig.Builder()
           .schedule(adSchedule)
           .build();

   PlaylistItem playlistItem = new PlaylistItem.Builder()
           .file("https://cdn.jwplayer.com/manifests/{MEDIA_ID}.m3u8")
           .build();

   List<PlaylistItem> playlist = new ArrayList<>();
   playlist.add(playlistItem);

   PlayerConfig config = new PlayerConfig.Builder()
           .playlist(playlist)
           .advertisingConfig(imaAdvertising)
           .build();
   mPlayer.setup(config);
});

You can build upon this basic implementation by adding multiple ad breaks.



Add multiple ad breaks to a player

👍

IMPORTANT

If you use the IAB Open Measurement Interface Definition (OMID) and run Google IMA ads, all custom video controls that overlay the media element must be registered as friendly obstructions.

Use the following steps to add multiple ad breaks to the previous VAST pre-roll example:

  1. Define an additional AdBreak object.
  2. Pass an ad tag to the tag property. The ad tag can have custom parameters appended.
  3. When defining the offset property, choose one of the following values to schedule a mid-roll or post-roll ad.

    Mid-roll
    {number}: (String) Ad plays after the specified number of seconds.
    {timecode}: (String) Ad plays at a specific time, in hh:mm:ss:mmm format.

    Post-roll
    post: (String) Ad plays after the content.

  4. Add the additional AdBreak object to adSchedule.
mPlayerView.getPlayerAsync(this, getLifecycle(), (JWPlayer player) -> {

   List<AdBreak> adSchedule = new ArrayList<>();

   AdBreak adBreak = new AdBreak.Builder()
           .tag("https://www.domain.com/adtag.xml")
           .offset("pre")
           .build();

   AdBreak adBreak2 = new AdBreak.Builder()
                 .tag("https://www.domain.com/adtag-mid-roll1.xml")
           .offset("10")
           .build();

   AdBreak adBreak3 = new AdBreak.Builder()
           .tag("https://www.domain.com/adtag-mid-roll2.xml")
           .offset("00:00:15:000")
           .build();

   AdBreak adBreak4 = new AdBreak.Builder()
           .tag("https://www.domain.com/adtag-mid-roll3.xml")
           .offset("25%")
           .build();

   AdBreak adBreak5 = new AdBreak.Builder()
           .tag("https://www.domain.com/adtag-post-roll.xml")
           .offset("post")
           .build();
        
   adSchedule.add(adBreak);
   adSchedule.add(adBreak2);
   adSchedule.add(adBreak3);
   adSchedule.add(adBreak4);
   adSchedule.add(adBreak5);

   ImaAdvertisingConfig imaAdvertising = new ImaAdvertisingConfig.Builder()
           .schedule(adSchedule)
           .build();

   PlaylistItem playlistItem = new PlaylistItem.Builder()
           .file("https://cdn.jwplayer.com/manifests/{MEDIA_ID}.m3u8")
           .build();

   List<PlaylistItem> playlist = new ArrayList<>();
   playlist.add(playlistItem);

   PlayerConfig config = new PlayerConfig.Builder()
           .playlist(playlist)
           .advertisingConfig(imaAdvertising)
           .build();
   player.setup(config);

});


Add a VMAP ad schedule

According to the IAB, "VMAP enables the content owner to define the ad breaks within their content, including the timing for each break, how many breaks are available, what type of ads and how many are allowed in each break".

Currently, VMAP advertising schedules can only be assigned to the entire playlist by using our ImaVmapAdvertisingConfig object.

Use the following steps to add a VMAP ad schedule to a player:

  1. Use ImaVmapAdvertisingConfig.Builder() to create an ImaVmapAdvertisingConfig object.
  2. Use PlayerConfig.Builder() to add the ImaVmapAdvertisingConfig to the advertising property of the PlayerConfig object.
// Create a new ImaVmapAdvertisingConfig
ImaVmapAdvertisingConfig imaVmapAdvertising = new ImaVmapAdvertisingConfig.Builder()
        .tag("https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpostpod&cmsid=496&vid=short_onecue&correlator=")
        .build();

// Construct a PlaylistItem
PlaylistItem video = new PlaylistItem.Builder()
        .file("https://playertest.longtailvideo.com/adaptive/bipbop/gear4/prog_index.m3u8")
        .build();


// Add the PlaylistItem to a List 
List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(video);

// Build the PlayerConfig
PlayerConfig playerConfig = new PlayerConfig.Builder()
        .playlist(playlist)
        .advertising(imaVmapAdvertising)
        .build();

// Setup the player
mPlayer.setup(playerConfig);


IMA SDK Settings

You can configure the IMA SDK settings by creating a new instance of ImaSdkSettings. Developers can then assign it to an ImaAdvertisingConfig or ImaVmapAdvertisingConfig instance by passing it to the Builder().

  1. Create an ImaSdkSettings object.
  2. Use ImaAdvertisingConfig.Builder() or ImaVmapAdvertisingConfig.Builder() to assign the ImaSdkSettings object to the ImaAdvertisingConfig or ImaVmapAdvertisingConfig object.
// Create and configure the ImaSdkSettings object
ImaSdkSettings imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
imaSdkSettings.setLanguage("el");

// Set the ad break offset and tag
AdBreak adBreak = new AdBreak.Builder()
        .tag("https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=sample_ar%3Dpreonlybumper&cmsid=496&vid=short_onecue&correlator=")
        .offset("pre")
        .build();

List<AdBreak> adSchedule = new ArrayList<>();
adSchedule.add(adBreak);

// Create video
PlaylistItem video = new PlaylistItem.Builder()
        .file("https://playertest.longtailvideo.com/adaptive/bipbop/gear4/prog_index.m3u8")
        .adSchedule(adSchedule)
        .build();

// Add the PlaylistItem to a List
List<PlaylistItem> playlist = new ArrayList<>();
playlist.add(video);

// Create ImaAdvertisingConfig object
ImaAdvertisingConfig imaAdvertisingConfig = new ImaAdvertisingConfig.Builder()
        .imaSdkSettings(imaSdkSettings)
        .build();

// Build the PlayerConfig
PlayerConfig playerConfig = new PlayerConfig.Builder()
        .playlist(playlist)
        .advertisingConfig(imaAdvertisingConfig)
        .build();

// Setup the player
mPlayer.setup(playerConfig);


Unsupported Features

The following table lists and describes the features that are unsupported.

Unsupported FeatureDescription
Ad Tag WaterfallsWhen using the IMA SDK you do not have the ability to define an ad tag waterfall in your code. An ad tag waterfall analog is instead defined in your Google Dashboard.
Non-linear Overlay AdsNon-linear ads are not currently supported via the IMA SDK. This is a limitation of the Google IMA SDK for Android. For more information please refer to the documentation here: https://developers.google.com/interactive-media-ads/docs/sdks/android/compatibility
Ad Skip OffsetThe ad skip offset is always set within the ad response of a Google IMA ad tag and we do not override the value. To configure your skip offset please contact your ad network.
Ad Tag VariablesThe ad tag variables specified in our VAST documentation are not supported when using the IMA SDK. Instead, we suggest contacting Google IMA to provide you with a list of ad tag variables supported in the Google IMA SDK.
VPAIDThe Google IMA SDK does not support VPAID 1.0 or VPAID 2.0 ads. This is a limitation of the Google IMA SDK for Android. For more information please refer to the documentation here: https://developers.google.com/interactive-media-ads/docs/sdks/android/compatibility


Did this page help you?