Google IMA Ad Parameters

Use the following parameters to configure Google IMA ads in Player V4 using the Google IMA Ad Plugin. See Integrating Google IMA Ads for details.
Note: These parameters are specific to Google IMA ads. You can also set global parameters for Google IMA ads. See Configuring Ad Parameters for details.
Note: Due to legacy reasons, provider-level page settings override ad manager-level page settings. If a specific set of fields are set outside of the google-ima-ads-manager parameter, such as pauseAdOnClick, they will take precedence over settings inside google-ima-ads-manager.
Scroll to the right to see whether a parameter is required or optional.
Name Description Type Required?
google-ima-ads-manager Master object key used to pass Google IMA ad server tags or network tags to the Ooyala player. This key has effect only with the values described below.   Yes
google-ima-ads-manager.additionalAdTagParameters additionalAdTagParameters get added to the ad tag URL and are automatically populated (if they are macros) before making the ad request. The additional ad tag url parameters need to be in the form of key-value pairs. When you use these parameters, we append them to the end of the ad tag. Appended parameters do not override anything in the URL from Backlot.

Valid Values:

If you want the Ooyala code to fill in the ad tag url data using a macro, the following macros are supported:
  • [random] or [cache_buster]: These insert a random number
  • [timestamp]: This inserts the time at which the request is run
  • [referrer_url]: This inserts the URL of the page
  • [oo_embedcode]: This inserts the Ooyala embed code for the current video
If you do not use additionalAdTagParameters, you can manually add macros to your ad tag. This circumvents Ooyala's code and is processed directly by the Google iMA SDK. According to Google, the following macros are supported (as of 02/04/2016):
  • url=[referrer_url]
  • correlator=[timestamp]

Google IMA documentation lists macros at : You can read Google IMA's documentation on how to add custom parameters to ad tags at


Here is an example of using Google IMA's macros:[referrer_url]&correlator=[timestamp]

Here is an example of how to add parameters through the Ooyala Google IMA plugin:

"google-ima-ads-manager": {
  "additionalAdTagParameters": {
This would make your ad tag change from
Note that [timestamp] and [oo_embedcode] would be filled in with the values specified above.
google-ima-ads-manager.all_ads Array of all the ads to be played during the video. Example:
"google-ima-ads-manager": {
object Yes if you do not specify this setting in Backlot; must be specified in either page-level parameters or Backlot.
google-ima-ads-manager.all_ads.tag_url Your Google IMA ad tag. If you want to override the tag attached to the video through Backlot, supply any string value here. string Yes if you are specifying the parameter all_ads
google-ima-ads-manager.all_ads.position Meaning depends on the value of all_ads.position_type:
  • If position_type is set to "t", then position specifies the time at which the ad should play, in milliseconds:
    • pre-roll ad: a value of 0.
    • mid-roll ad: any value greater than 0 and less than the total time of the video.
    • post-roll ad: any value greater than the total time of the video.
  • If position_type is set to "p", then position specifies the percentage of the total time of the video:
    • pre-roll ad: a value of 0.
    • mid-roll ad: any value greater than 0 and less than 100.
    • post-roll ad: a value of 100 or more.
  • If position_type is set to "r" (Ad Rules), then position is ignored.
integer Yes for ad overrides without ad rules
google-ima-ads-manager.all_ads.position_type Specifies how to interpret the position value. Valid salues:
  • "t" - indicates that position is the time at which the ad should play, in milliseconds.
  • "p" - indicates that position is the percentage of the total time of the video.
  • "r" - indicates that Ad Rules determine the position. The all_ads.position setting is ignored.
string Yes
google-ima-ads-manager.iframeZIndex Overrides the zindex of the Google IMA iframe. Set this parameter to 0 if you are using clickable VPAID ads with VPAID INSECURE mode on desktop devices to avoid covering up the ad. You can specify an integer greater than or equal to 0. Default is 10004.
Warning: Using this parameter may cause undesirable interactions with the player skin and the video. VPAID INSECURE mode allows UI elements to be placed outside of the iframe. Due to this behavior, the UI elements may not interact well with the Ooyala video player. The Player has zindices in the 1000s range. Elements that are below the player cannot be interacted with through the player. One example is that UI elements that control play, pause, and clickthrough of the ad could be placed outside the iframe with a zindex of 10 (which would place the elements below the player). We recommend that you work with your ad creators or ad providers to encourage use of VPAID secure mode for ads played in the Ooyala player to avoid these side effects.
integer No
google-ima-ads-manager.showAdControls If set to true, displays Ooyala's ad control bar while an IMA ad is playing. The IMA ad is displayed above our ad control bar. This feature is disabled by default.
Note: In order for this setting to work, the showControlBar setting (under adScreen in skin.json) must be set to true. For example (in skin.json):
"adScreen": {
   "showAdMarquee": true,
   "showAdCountDown": true,
   "showControlBar": true
Boolean No
google-ima-ads-manager.useGoogleAdUI If set to true, ads will be displayed with the Google Ad UI, including the ad countdown, learn more button, and more. Default is false.
Note: This parameter can be used only for desktop web. This parameter will not work for mobile web.
Boolean No
google-ima-ads-manager.useGoogleCountdown If set to true, the Google IMA countdown timer will be displayed (while still enabling clickthroughs to be triggered by clicks on the video). Default is false.
Note: This parameter can be used only for desktop web. This parameter will not work for mobile web.
Note: The Google IMA documentation states that: "These settings may be ignored for AdSense and ADX ads."


   { "useGoogleCountdown":true }
Boolean No
google-ima-ads-manager.vpaidMode If set to "insecure", the Google IMA SDK will be notified to use the INSECURE VPAID mode. The INSECURE VPAID mode allows you to use "insecure" VPAID creatives. string No

Was this article helpful?