Integrating Google IMA Ads

You can integrate Google IMA ads with Player V4 using the Google IMA Ad Plugin (google_ima.min.js).

Enabling the Google IMA Ad Source for Your Account

Before you can use Google IMA ad integration:
  1. Log into the Ooyala Customer Portal.
  2. Submit a ticket requesting that the Google IMA ad source be added to your Ooyala account.

Options for Associating Ad Tags with Your Video Assets

Once the Google IMA ad source is enabled for your account, you can associate Google IMA ad tags with your videos using:

Notes About the Google IMA Plugin

  • Ads that use Backlot settings will be loaded dynamically before the ad position (as determined in Backlot). The ad will now be requested and loaded at the specified ad position (via Backlot settings or Ad Rules). The video will be paused at the pre-determined ad position and an ad request will be made. The loading icon will be displayed until a successful ad response is returned, or the video playback will resume if an ad error is detected. These behavior changes were made because publishers can be very specific about when ad requests are made.
  • For the Google IMA ad plugin, the ad marquee and ad control bar configurations in skin.json are ignored (and are forcibly set to off) to avoid blocking ad interactivity.

Loading the Google IMA Ad Plugin on a Page

Note:
  • If you use Backlot to generate your HTML embed code, and you choose the V4 HTML5 Standard Player Embed Code (recommended) option, the Google IMA plugin is automatically included and should not be explicitly added to the web page where you launch the player. For details, see Configuring Player Embed Settings in Backlot.
  • If you choose the V4 HTML5 Player Embed Code (Advanced) option in Backlot, or if you manually create the HTML embed code yourself, you need to add the Google IMA plugin to your web page so that the Google IMA plugin loads before the player is created.
For every page on which you want to use the Google IMA plugin with a player (regardless of how you associated Google IMA ads with your videos):
  1. Add the google_ima.min.js script to the page where you are loading the player. You must load this plugin after you load core.min.js.
    <script language=“javascript" src="url_where_hosted/google_ima.min.js"></script>
  2. Associate the player with the Ooyala Google IMA ad plugin by passing in google-ima-ads-manager as one of the player parameters during the player creation (OO.Player.create).

Option: Integrate with Google IMA via Backlot Ad Sets

  1. Create a Google IMA ad set using the Backlot UI or Backlot API:
  2. Assign an ad set to an asset or multiple assets using:
    • Backlot UI: To assign your Google IMA ad set to a single asset, see the Support Center topic Managing Monetization. To assign your Google IMA ad set to multiple assets, see the Support Center topic Bulk Applying Settings.
    • Player API: With the Player API, you can associate an ad set only with an asset on your web page. To associate an ad set with an asset on multiple players, you must replicate the code for each player. To associate an ad set with an asset using the Player API, see Assigning Ad Sets Dynamically.
    • Backlot API: With the Backlot API, you can associate an ad set with an asset more concretely. When you associate an asset with an ad set using the Backlot API, the asset and the ad set will be paired together on any player and page on which you play the asset. To associate an asset with an ad set using the Backlot API, see Associate Ad Set with Asset.

Option: Integrate with Google IMA via Player Embedded Parameters

Note: Wherever you see url_where_hosted in sample code, replace this (in your code) with the URL that points to where the resource is hosted. For a list of Ooyala-hosted paths, see Ooyala-hosted Player V4 Resources. The URL can point to a location on the same host (internal link) or on a separate host (prefixed with http:// or https://). If you host resources yourself (see Hosting Player V4 Resources), be sure to check for any path dependencies within the files.
  1. Add the google_ima.min.js script to the page where you are loading the player. You must load this plugin after you load core.min.js.
    <script language=“javascript" src="url_where_hosted/google_ima.min.js"></script>
  2. Use the Player V4 OO.Player.create function to create the player.
  3. Pass any global parameters. See Configuring Ad Parameters.
  4. Pass Google IMA ad tags to the Ooyala player using the google-ima-ads-manager parameter and its child parameters. See Google IMA Ad Parameters.
Note: Ad sets that are loaded at the page level will override the ad set associated with the asset in Backlot.

Here is an example of how to override an ad set in the Google IMA ad manager on your web page. If you want to replace the Ad Set attached to your video (from Backlot), or if it does not have an IMA Ad Set already associated with it, you will replace "yourAdTagUrl" with the actual Google IMA ad tag containing the response. Otherwise, you may leave it out.

<script>
    var playerParam = {
      "pcode": "YOUR_PCODE",
      "playerBrandingId": "YOUR_PLAYER_ID",
      "skin": {
        // Config contains the configuration setting for player skin. Change to your local config when necessary.
        "config": "url_where_hosted/skin.json"
      },
       "google-ima-ads-manager": {
         "all_ads": [              
             {                
               "position_type":"r",                
               "tag_url":"http://pubads.g.doubleclick.net/1234567/ads?sz=640x480&iu=/12345/pb_preroll_ad&ciu_szs&impl=s&cmsid=123&vid=1234567abcdefg&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=[description_url]&correlator=[timestamp]"              
             }            
          ]          
        }
    };
    OO.ready(function() {
      window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
<script>
Here is a more complete example of Google IMA integration that will work for HTML5. The player branding_id of a player and the embed code of an asset can be found in the Embed tab on the MANAGE page of Backlot.
<!DOCTYPE html>
<html>
    <head>
        <title>Google IMA Example</title>
        <!-- V4 JS core is required. Plugins such as skin, discovery and Advertising need to be loaded separately -->
        <script src="url_where_hosted/core.min.js"></script>
        <script src="url_where_hosted/other-plugin/discovery_api.min.js"></script>
        <!-- Change these html5-skin.min.css and html5-skin.js to your local build if necessary -->
        <script src="url_where_hosted/html5-skin.min.js"></script>
        <link rel="stylesheet" href="url_where_hosted/html5-skin.min.css"/>
        <!-- A Video Plugin is required. This example shows the Main Video Plugin -->
        <script src="url_where_hosted/main_html5.min.js"></script>
        <!-- Ad module -->
        <script src="url_where_hosted/google_ima.min.js"></script>
    </head>
    <body>
        <div id="container" style="width:640px; height:360px;"></div>
        <script>
            var playerParam = {
              "pcode": "YOUR_PCODE",
              "playerBrandingId": "YOUR_PLAYER_ID",
              "skin": {
                // Config contains the configuration setting for player skin. Change to your local config when necessary.
                "config": "url_where_hosted/skin.json"
              },
               "google-ima-ads-manager": {
                 "all_ads": [              
                    {                
                    "position_type":"r",                
                    "tag_url":"http://pubads.g.doubleclick.net/1234567/ads?sz=640x480&iu=/12345/pb_preroll_ad&ciu_szs&impl=s&cmsid=123&vid=1234567abcdefg&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=[description_url]&correlator=[timestamp]"              
                    }            
                  ]          
               }
            };
            OO.ready(function() {
              window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
            });
        </script>
    </body>
</html>

Special Case: Google DFP Premium

This section applies only if you are using DFP.

Before trafficking ads, if you are using DFP Premium you must first map your video content and all related custom metadata to Google's platform. To learn how to do this, see the Support Center topic Monetizing your Ooyala Content with DFP.

Custom Metadata

If your video content has been successfully ingested into DFP, all custom metadata key/value pairs should be visible in DFP's Content tab. These values may be used to target ads against particular types of content. The following screenshot, for example, is from an individual video asset from Ooyala’s test DFP account. DFT Metadata

Mapping Custom Metadata to DFP Keys

You have the option of creating custom targeting keys on DFP Premium. These keys are then mapped to the key/values ingested from Backlot. To create these keys, in DFP, go to Inventory > Custom targeting > + New key, as shown below. Custom TargetingFor more information, go to the DFP help article on custom targeting.

Ad Rules

Ad rules can define when ads are inserted, how long they should run for, what format of ads are run, and what to use as the ad source.

Publishers can set up two types of ad rules in DFP in addition to Default Ad Rules that are already available in DFP:
  • Standard Ad Rules, which apply to a single stream of content.
  • Session Ad Rules. which applies to a visitor’s entire visit to customer’s pages. They can be applied across multiple content streams and across multiple sites. Session ad rules can only be applied to pre-roll ads.

To enable ad rules for an ad:

  1. Specify your ad rules in DFP. For information on implementing DFP ad rules, go to https://support.google.com/dfp_premium/answer/2553686?hl=en.
  2. To enable your DFP ad rules to correctly render for your Google IMA V3 ad with the Backlot UI, click MONETIZE > Ad Sets, and set the ad position to "ad rules" for the desired ad.

    OR

    To enable your DFP ad rules to correctly render for your Google IMA V3 ad with the Backlot API, set "ad_type": "rules" for the desired ad. For more information see Ad Sets.
    Note: Settings applied at the page level with the ad tag url will override Backlot settings. However, the position type (ad rule or non ad rule) must match on the page level and in Backlot for ads and ad rules to properly render.

Ad Targeting

To enable targeting against content metadata values, Google DFP requires two values to be included on your IMA tag: cmsid and vid. Once these values are included when making ad requests, the IMA ad manager “knows” which video asset is making the request. As a result, it returns whatever ad response has been defined by the publisher’s ad operations team.

cmsid: A unique value assigned automatically by Google to each content source. To locate it within the DFP Premium platform, click on the Video tab (on the upper right), navigate to Sources and click on the source in question. The value is “ID,” as shown below: CMSID

vid: A unique value for each video asset. The Ooyala-IMA integration uses Ooyala’s Content ID.

When creating the IMA Ad Manager adset, the publisher will need to append the IMA ad tag with the macro [oo_embedcode]. Here’s an example IMA Ad Manager tag with both cmsid and vid:

http://googleads.g.doubleclick.net/pagead/ads?client=ca-video-pub-9498212586027311&slotname=8286566767&cmsid=176&vid=[oo_embedcode]

You can also pass vid and cmsid programmatically on your web page, as shown in the following example.
"google-ima-ads-manager": {
  "all_ads": [              
    {                
    "position_type":"r",                
    "tag_url":"http://pubads.g.doubleclick.net/gampad/ads?sz=640x480&amp;iu=/12345/pb_preroll_ad&amp;ciu_szs&amp;impl=s&amp;cmsid=123&amp;vid=1234567abcdefg&amp;gdfp_req=1&amp;env=vp&amp;output=xml_vast2&amp;unviewed_position_start=1&amp;url=[referrer_url]&amp;description_url=[description_url]&amp;correlator=[timestamp]"              
    }            
  ], 
  "additionalAdTagParameters": {
    "vid": "embed code",
    "cmsid": "349"
  }
}

IMA Ad Rules

Ad rules define how ads display with video content. You can create ad rules on their DFP Premium account to determine when ads play in a video, for how long, and as a result of which triggers, such as content targeting parameters. You can also target ad rules so that they apply to:
  • Specific videos, such as all episodes of a particular TV show.
  • Video metadata, such as videos in the "sports" genre.
  • Users' geography.
  • Users' browsers.
  • Custom targeting keys and values that you define.

Example 1: You want to show two 60-second ad breaks during an episode of a popular TV show. The TV show has specific cue points that DFP ingested from your content management system (CMS). You can set up ad rules to specify when the ads should appear (either at the pre-defined cue points or after a certain number of minutes), what types of ads appear, and how many ads should appear during each ad break.

Example 2: For all sports videos on your website, you want to show pre-roll ads followed by a house ad (also called a bumper). You can set up an ad rule to specify what types of ads can show and how long they should run, then target the ad rule to videos with the correct metadata.

Special Case: Google IMA V3 Companion Ads

Google IMA V3 companion ads don’t use the standard Player WILL_SHOW_COMPANION_ADS event. This is because Google IMA itself is responsible for parsing and generating the companion ad. Google documents how to use the Google Publisher Tag (GPT) at https://developers.google.com/interactive-media-ads/docs/sdks/html5/companions-gpt. To use companion ads:
  1. Include the following code in your webpage:
    <script src="//www.googletagservices.com/tag/js/gpt.js">
    </script>
  2. Create the companion tag.
  3. Call the right Google API to place the companion ad. For example:
    <div id="cad" style="width:300px;height:250px;background-color:red">
    </div>
    </br>
    <script type="text/javascript">
        // Add a command to the command queue
        googletag.cmd.push(function() {     // Define the unit
                
            var adSlot1 = googletag.defineSlot(        "/5129/News/QLD", // Ad Unit Name, obtained by the provider
                         [300, 250],          
                "cad");    
            adSlot1.addService(googletag.companionAds());    
            googletag.enableServices();
            // Immediately signal to show it.
                
            googletag.display("cad");
        });
    </script>
Google documents using Companion Ads with the Ad API at https://developers.google.com/interactive-media-ads/docs/sdks/html5/companions-api. To display companion ads though the WILL_SHOW_COMPANION_ADS event, slot sizes need to be defined as a page level setting while creating the player as follows:
<script>
    var playerParam = {
      "pcode": "YOUR_PCODE",
      "playerBrandingId": "YOUR_PLAYER_ID",
      "onCreate": function(player) {
        player.mb.subscribe("*", "test", function(event, params) {
          if (event.match(/willShowCompanionAds/)) {
            console.log(params); // We get the companion ads from params
          }
        });
      },
      "skin": {
        // Config contains the configuration setting for player skin. Change to your local config when necessary.
        "config": "url_where_hosted/skin.json"
      },
      companionAd: {
       slots: [{width: 300, height: 250}, {width: 300, height: 60}]
      }
    };
    OO.ready(function() {
      window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>       

If there are any companion ads in the XML with the defined slot sizes, you can retrieve them by listening to the WILL_SHOW_COMPANION_ADS event as demonstrated on the onCreate function code above.

This will get the ads as follows, which is the already formatted companion ad as HTML and the corresponding size, so you can identify the ads and place them anywhere on the page.
{"ads":[
 {
   "size":"300x250",
   "ad":"<Companion Ad as HTML>"
 },
 {
   "size":"300x60",
   "ad":"<Companion Ad as HTML>"
 }
]}         

Special Case: Google IMA and Mobile

Ooyala supports Google IMA for both desktop and mobile. For information about working with Google IMA for mobile devices, see the following mobile SDK for iOS topics.

Was this article helpful?