Integrating Google IMA Ads with Player V3

The following documentation describes the Google IMA integration with Player V3. For
documentation on the Google IMA integration with Player V4, see Google IMA Ad Plugin.

Overview

Google IMA ad sets can be associated with video assets. This
documentation describes the Google IMA integration with Player V3.

You have two options for
associating Google IMA ads with the Ooyala player:

Via Backlot ad sets. Create ad sets with the Backlot UI or API.

Via player embedded parameters. Specify embedded parameters at the page level of
the player.

Each of these options is described below.

Note: Currently we only support macros with our
Google IMA integration. The supported macros include [oo_embedcode] and [timestamp]. These
macros will only work if you use the Google IMA Ad Module.

Prerequisites

Note: For Ooyala HTML5 Player V3, Google IMA is disabled for all versions of Internet
Explorer.

Before you can use Ooyala's Google IMA ad integration, you need to log
into the Customer Portal and submit a ticket requesting to add the Google
IMA ad source to your account. Once the Google IMA ad source is enabled you'll be able to
create ad sets for Google IMA.

Assign an ad set to an asset or multiple assets using the Backlot UI, Player API, or Backlot API.

Backlot UI: For instructions on how to assign your Google IMA ad set to a single
asset, see Managing
Monetization. For instructions on how to assign your Google IMA ad set to multiple
assets, see Bulk Applying
Settings.

Player API: With the Player API you can only associate an ad set 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. That is, 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 you play the asset on.
To associate an asset with an ad set using the Backlot API, see Associate Ad Set with Asset.

Pass Google IMA ad tags to the Ooyala player using the google-ima-ads-manager parameter
and its child parameters, described below.

(Optional) Assign additional parameters with the additionalAdTagParameters parameter,
described below.

The following parameters can be used with Google IMA Ad Manager and the Ooyala Player.
The last two columns of the table note if the parameter is supported for Flash and/or HTML5.

Parameter

Description

Flash

HTML5

google-ima-ads-manager

This is the parent parameter used to pass Google IMA ad server or network tags
to the Ooyala player. This key only has effect with the values described
below.

Required: Yes

X

X

additionalAdTagParameters

Add functionality to your ad handling such as adding demographic targeting for
ads. These parameters have a dependency on how the ad tag is set up in Backlot. You
can use any of the internal key/value pairs that google-ima supports.

Note: Unlike
adTagUrl, the additionalAdTagParameters appended parameters do not override
anything in the URL from Backlot.

If set to yes, ad playback will continue even if an ad is clicked. For Flash,
if playWhenAdClick is set to false with no ad controls, after the user clicks on the
ad and is redirected, ad playback will continue when the user clicks on the ad the
second time. We are aware that this causes some undesired behavior where the ad url
opens for both ad pause and ad play events. We are working with the Google IMA team
to fix this behavior.

Otherwise, ad playback will pause.

Valid
Values: yes | true | no | false

Default:
no

Required: No

Parent:
google-ima-ads-manager

X

X

adRequestTimeout

Set the time taken, in milliseconds, to make a timeout for the ad request and
continue the video playback.

Valid Values: Any integer greater than or
equal to 1000

Default: 3000

Required: No

X

X

Below is a code snippet showing how to use the google-ima-ads-manager parameter.
You will replace "some url" with the actual Google IMA ad tag containing the response.

Below
is a more robust example of Google IMA V3 integration that will work for both Flash and
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. To include the HTML5 pre-roll playback controls, a
"showInAdControlBar" : true flag needs to be set in the "google-ima-ads-manager" like the
following:

Special Case: Google DFP Premium

This section only applies if you are using Google 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 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.

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. For more information, go to the DFP help article on custom targeting.

Ad Rules

Note: Cuepoints are no longer supported for Google IMA V3. You will now set ad positions
through ad rules which are created in your DFP account.

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 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. For more
information on Google IMA V3 ads in the Backlot UI, see Ad Set Fields for Google IMA V3.

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:

Special Case: Google IMA V3 Companion Ads

Google IMA V3 companion ads
don’t use the standard Player V3 WILL_SHOW_COMPANION_ADS event. This is
because Google IMA itself is responsible for parsing and generating the companion ad. To use
companion ads: