Advertising with the IMA3 Plugin

Introduction

The IMA plugin integrates the Brightcove player with Google's Interactive Media Ads (IMA) for HTML5 version 3. This allows you to request and track VAST, VPAID and VMAP ads for your player. For details about Google IMA, see the Using the IMA HTML5 SDK Version 3 document.

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.

CCPA and GDPR Support

Support for CCPA (California Consumer Privacy Act) is provided by Google's IMA3 SDK. Customers are able to restrict data processing either in the Google Ad Manager interface, or by specifying "rdp=1" in the ad tag itself. For more information and best practices, see Google's documentation here: https://support.google.com/admanager/answer/9561023.

GDPR (General Data Protection Regulation in the EU) is supported in a similar way, instead using "npa=1" in the ad tag, and a different setting in the Google Ad Manager interface. https://support.google.com/admanager/answer/7666366.

Player sample

The sample video below demonstrates the use of the IMA Plugin. Play the video to see a pre-roll, a skippable mid-roll at 5 seconds, then finally a post-roll.

Testing the ad server

The first thing you should do is verify the validity of the ad tag you are planning to use. Be sure you have copied its URL and browse to the following page: Video Suite Inspector (clicking this link will cause the page to open in a new window or tab).

Paste your ad tag URL into the Input type form input field. Click Test Ad and you will see your ad(s) play, with the Google supplied video interspersed. If your ad tag is not working in this test environment, it will not work with Brightcove Player.

Implement using Players module - Advertising section

In this section of the document you will use Studio to implement advertising using the Advertising section. In this case, you are limited to what options the form provides. If you wish to customize the implementation using some of the many available options that happen NOT to be provided in this section, use the Implement using Players module - Plugins section, which provides the opportunity to supply options via JSON.

To implement the IMA Plugin using the Players module, follow these steps:

1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add advertising functionality.
2. Click the link for the player to open the player's properties.
3. Click Advertising in the left navigation menu.
4. Check the Enable Client-Side (IMA) checkbox.
5. Enter the Server URL for the ad server.
6. Select the Request Ads setting.
   • On load - Ads are requested immediately when the player loads (this is normally the best experience for GAM / VPAID).
   • On play - The first ad request is delayed until playback is initiated.
   • On demand - All ad requests will be initiated programmatically using the player.ima3.adrequest() method. This mode does not support preroll or postroll ads.
   • On cue point - Ad requests will be initiated on a dispatched ad cue point. See the Displaying Ads Using Ad Cue Points document for complete details.
7. Select the ad VPAID Mode. The VPAID Mode is used to enable VPAID 2 support in IMA ads.
   • Enabled - Play VPAID ads in an iframe with a different domain
   • Insecure - Play VPAID ads in an iframe with the same domain
   • Disabled - VPAID ads throw an error
8. Set the Timeout value. This is the maximum amount of time to wait, in milliseconds, for an ad to initialize before playback.
9. Make a choice for Hard timeouts. Unchecking this option could result in a slow loading advertisement interrupting video playback.
10. Set the Maximum Number of Redirects. This specifies the maximum number of redirects before the subsequent redirects will be denied, and the ad load aborted. The number of redirects directly affects latency and thus user experience.
11. For the Plugin Version, it is strongly recommended you use the latest version.
12. View an example, completed form:

    

13. Click Save.
14. To publish the player, click Publish & Embed > Publish Changes.
15. To close the open dialog, click Close.

When the changes to the advertising properties are saved, the IMA plugin will be configured as part of the Plugin settings. The JavaScript and CSS will be hidden since you added them via the Advertising section.

The IMA plugin does support additional properties that are not available in this section of the UI. See the next section of this document for a way to use more configuration options.

Implement using Players module - Plugins section

If you wish to configure the IMA3 plugin beyond the options provided in the Advertising section, you can use the Plugins section, which provides a way to supply options via JSON.

To implement the IMA3 Plugin you will add the function name of the plugin and the URLs to the plugin's JavaScript and CSS files:

1. Open the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
2. Click the link for the player to open the player's properties.
3. Click Plugins in the left navigation menu.
4. From the Add a Plugin dropdown, select Custom Plugin.

   

5. For the Plugin Name enter ima3.
6. For the JavaScript URL, enter:

   https://players.brightcove.net/videojs-ima3/4/videojs-ima3.min.js

7. For the CSS URL, enter:

   https://players.brightcove.net/videojs-ima3/4/videojs-ima3.css

8. Enter the configuration options in the Options(JSON) text box.

   {
     "serverUrl": "//pubads.g.doubleclick.net/gampad/ads?sz=400x300&iu=%2F6062...",
     "timeout": 5000,
     "debug": true
   }

9. Click Save.
10. To publish the player, click Publish & Embed > Publish Changes.
11. To close the open dialog, click Close.

Hybrid implementation

So far in this document you have seen the IMA plugin implemented in Studio, then in code. Some customers like to perform a hybrid implementation where the basic plugin is added in Studio, but then configuration done in the page's JavaScript. This hybrid implementation is discussed in this section.

As you have just seen in the previous section, when implementing the IMA3 plugin purely in code you manipulate the plugin in function format. When you install the plugin in Studio, then configure in the page, you must treat the plugin as an object. For instance, assume you have installed the IMA3 plugin using Studio as shown here, noting that no Ad Tag is supplied:

Now, in the JavaScript in the page you can assign property values (remember, treat the plugin as an object now) as shown here:

videojs.getPlayer('myPlayerID').ready(function() {
  var myPlayer = this;
  myPlayer.ima3.settings.serverUrl = 'http://solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml';
});

Of course, other properties can be assigned values in this manner.

Implement using code

To implement the IMA3 Plugin the player needs to know the location of the plugin code, a stylesheet, the plugin name and plugin configuration options. The location of the plugin code and stylesheet are as follows:

https://players.brightcove.net/videojs-ima3/4/videojs-ima3.min.js

https://players.brightcove.net/videojs-ima3/4/videojs-ima3.css

The name of the plugin is ima3, and an example set of options is:

{
  "serverUrl": "//pubads.g.doubleclick.net/gampad/ads?sz=400x300&iu=%2F6062...",
  "timeout": 5000
}

The following example uses the Advanced implementation of the player to associate the IMA Plugin with a single instance of a player.

• Line 7: Uses a link tag to include the plugin's CSS in the head of the HTML page.
• Line 12: Gives the video tag an id attribute, with some value, in this case myPlayerID.
• Line 21: Uses a script tag to include the plugin's JavaScript in the body of the HTML page.
• Lines 25-29: Initializes the player using the bc() method, and then calls the ima3() method.
• Lines 30-33: On player ready, a reference to the player is created. The comment is shown to indicate where you can place code to add other player behaviors beyond IMA3 plugin setup and configuration.

<!doctype html>
<html>

<head>
  <meta charset="UTF-8">
  <title>IMA3 Plugin v4 Code Example</title>
  <link href="https://players.brightcove.net/videojs-ima3/4/videojs-ima3.css" rel="stylesheet">
</head>

<body>

  <video-js id="myPlayerID"
    data-account="1752604059001"
    data-player="JLvQcZgxxV"
    data-embed="default"
    controls=""
    data-video-id="5550679964001"
    data-playlist-id=""
    data-application-id=""
    width="960" height="540"></video-js>
  <script src="https://players.brightcove.net/1752604059001/JLvQcZgxxV_default/index.min.js"></script>

  <script src="https://players.brightcove.net/videojs-ima3/4/videojs-ima3.min.js"></script>
  <script>
    var myPlayer;
    var player = bc('myPlayerID');
    player.ima3({
      serverUrl: '//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml'
    });
    player.ready(function () {
      myPlayer = this;
      //Do something
    });
  </script>

</body>
</html>

IMA3 plugin and autoplay

Advertisments played via the IMA3 plugin will use a similar autoplay configuration set for Brightcove Player. (See Autoplay Considerations.) Full control is granted and all possible Brightcove Player autoplay values are supported.

JSON vs JavaScript notation

If you examine the Options section below, you see the configuration information is supplied in JSON format. If you are using code to implement your IMA3 plugin, the notation for setting options with JavaScript is slightly different.

Here you see options in JSON format you could use in Studio:

{
  "requestMode": "onload",
  "serverUrl": "//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml?cust_params={mediainfo.ad_keys}",
  "timeout": 5000
}

If you are using JavaScript to configure your options, the JSON format would work, but you could also use the JavaScript syntax as shown here:

{
  requestMode: 'onload',
  serverUrl: '//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap',
  timeout: 5000
}

Options

The video.js IMA3 plugin is built on top of the video.js ads framework and accepts any options that the ad framework provides. Take a look at the ad framework README for details. Both the IMA plugin specific options and ad framework options are documented here.

The options are:

• clickTrackingElement
• debug
• disableCustomPlaybackForIOS10Plus
• hardTimeouts
• ima3SdkSettings
• omidAccessModeRules
• postrollTimeout
• prerollTimeout
• requestMode
• sdkurl
• serverUrl
• showVpaidControls
• timeout
• usePlayerAutoplayHandling
• useMediaCuePoints
• vpaidMode

clickTrackingElement

Type: HTMLElement
Default Value: undefined

If the HTML ad tech is being used in custom ad playback mode, this specifies an alternative HTML element to be used to track advertisement taps on devices that don't support input events over the video element. More details are available in the parameter documentation for the IMA AdDisplayContainer. If you provide a click tracking element, it is your responsibility to show and hide it at the appropriate times on the appropriate platforms. In most cases, it's best to leave this setting undefined and allow the plugin and IMA to manage ad interaction.

debug

Type: boolean
Default Value: false

If debug is set to true, the ads framework will output additional information about its current state during playback. This can be handy for diagnosing issues or unexpected behavior in an ad integration.

This option is part of the ad framework and is configured as follows:

player.ima3({
  debug: true
});

The following screenshot shows part of the extensive information displayed by turning debug on.

disableCustomPlaybackForIOS10Plus

Type: boolean
Default Value: false

This property is part of the ima3SdkSettings object. It acts as a getter and setter to control whether to disable custom playback on iOS 10+ browsers. Behavior is as follows:

• When true, ads will play inline if the content video is inline, which enables skippable ads. However, the ad will stay inline and not support iOS's native fullscreen.
• When false, ads will play in the same player as your content.

See the iOS skippable ads section of this document for an example of usage of this setting.

hardTimeouts

Type: boolean
Default Value: true

Abandon ads that finish loading after they have timed out. This will prevent slow preroll ads from interrupting after the timeout has elapsed and content video has begun playing.

This option is part of the ad framework and is configured as follows:

player.ima3({
  hardTimeouts: true
});

Setting this option to false will result in content flash before ads.

ima3SdkSettings

Type: object
Default Value: undefined

If provided, the properties of this object are used to set the page-level Ima3SdkSettings when the IMA SDK has finished loading. The properties of this object are expected to be the camel-cased equivalent of setter methods on the SDK settings object, minus the 'set' prefix. For example, if you provided this object when initializing the plugin:

player.ima3({
  ima3SdkSettings: {
    'numRedirects': 3,
    'ppid': 'publisher-provided-id'
  }
}

Then the video.js IMA plugin would run code that looks something like this when IMA had loaded:

window.google.ima.ImaSdkSettings.setNumRedirects(3);
window.google.ima.ImaSdkSettings.setPpid('publisher-provided-id');

omidAccessModeRules

Type: Four access modes
Default Value: undefined

The OM SDK supports running verification scripts in different access modes, which control how much the verification script can access. The three access modes are:

• FULL: The verification script has direct access to the creative and the publisher page.
• DOMAIN: The verification script is sandboxed and cannot access the creative or publisher page. However, the script is loaded in such a way that it can directly confirm what publisher domain it is on.
• LIMITED: The verification script is sandboxed and cannot access the creative or publisher page, and cannot directly confirm what publisher domain it is on.

The access rules for each OmidVerificationVendor can be set via the omidAccessModeRules plugin option as follows:

{
  omidAccessModeRules: {
    OTHER: 'LIMITED',
    DOUBLEVERIFY: 'DOMAIN',
    GOOGLE: 'FULL'
  }
}

Note that the enableOmidBeta feature flag must be set to true in the ima3SdkSettings to enable omidAccessModeRules, as follows:

{
  "featureFlags": {
    "enableOmidBeta": true
  }
}

Access mode rules must be set at the ad-request level. To set different access modes for different verification script providers, pass a dictionary that maps each OmidVerificationVendor to one of the access modes listed above. OmidVerificationVendor.OTHER is used to set the default access mode for all vendors not explicitly included in the dictionary. If no access mode rules are specified, verification scripts run in LIMITED access mode for vendors.

See the following example which sets GOOGLE to google.ima.OmidAccessMode.FULL. All other providers, including those listed in OmidVerificationVendor, default to how OmidVerificationVendor.OTHER is set.

request.omidAccessModeRules = {};
request.omidAccessModeRules[google.ima.OmidVerificationVendor.GOOGLE] = google.ima.OmidAccessMode.FULL;
request.omidAccessModeRules[google.ima.OmidVerificationVendor.OTHER] = google.ima.OmidAccessMode.DOMAIN;

postrollTimeout

Type: number
Default Value: undefined

Controls postrollTimeout setting in videojs-contrib-ads. If provided, overrides any value set for timeout.

prerollTimeout

Type: number
Default Value: undefined

Controls prerollTimeout setting in videojs-contrib-ads. If provided, overrides any value set for timeout.

requestMode

Type: string
Default Value: onload

This option is part of the ad framework is configured as follows:

player.ima3({
  requestMode: 'onplay'
});

There are four possible values for this option:

• onload: Ads are requested immediately when the player loads. This is normally the best experience for GAM / VPAID.
• onplay: The first ad request is delayed until playback is initiated. This is important for ad networks which consider ad requests to be plays, so you would not want an ad request before a play request. This will cause ads trafficked to eventually drop, or the customer will receive less for the ads shown.
• ondemand: Ads will only play when initiated using the player.ima3.adrequest() method manually. This mode does not support preroll or postroll ads.
• oncue:This option behaves differently depending upon if it is use with the useMediaCuePoints option.

  Using cue points with Video Cloud

  You can create ad cue points for a video in Studio, then have an advertisement played when the cue point is triggered. For full details see the Display Ads Using Ad Cue Points document.

  Using cue points in a live stream

  Ads are requested based on ID3 cue points in a live stream. For this type of request to function correctly, the ID3 TXXX frame received must contain JSON data with the following fields:

  • name: Required; must be the string value adCue
  • id: Required; A unique value to identify the ad given that times are relative in live streams
  • serverUrl: Optional; Appended as a break length parameter to the server url
  • duration: Optional; ad duration

  Example:

  {"name": "adCue", "id": 123}

  You can also cancel ID3 cue points in a live stream created by an adCue by using adCancel. The following format must be used for the object sent:

  {"name": "adCancel", "id": 123}

  Both the name and id are required.

  • Live ID3 ad cues are not supported on Android.
  • Live ID3 ad cancellation cues are not supported on iOS.

sdkurl

Type: string
Default Value:

//imasdk.googleapis.com/js/sdkloader/ima3.js

Set a custom URL to the IMA SDK script. This is not needed in production environments, but can be useful for debugging.

When debug is true, this will point to ima3_debug.js instead.

serverUrl

Type: string or function
Default Value (a generic Google ad):

//pubads.g.doubleclick.net/gampad/ads?sz=400x300&iu=%2F6062%2Fiab_vast_samples&ciu_szs=300x250%2C728x90&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&correlator=[timestamp]&cust_params=iab_vast_samples%3Dlinear

Here, you will provide the URL to your ad server. This option can be configured in Brightcove Studio as shown above. You can also set the value in code. Two examples are shown next. (Remember, you should test the ad tag on your server before trying to use it in the plugin.)

If the value is a string, it represents the ad server URL from where ads are requested and can be set in code as follows:

player.ima3({
  serverUrl: 'your ad server'
});

If the value is a function, the function parameter is a callback function that should be called with your server URL as the argument. This provides support for asynchronous processes such as header bidding. In the following example you see information from the mediainfo object used to determine which ads URL should be used based on an account ID:

// Initialize IMA plugin
myPlayer.ima3({
  serverUrl: function(callback) {
    if (myPlayer.mediainfo.id === '4034552795001') {
      callback('https://pubads.g.doubleclick.net/.../url1');
    } else {
      callback('https://pubads.g.doubleclick.net/.../url2');
    }
  },
  requestMode: 'onload',
  debug: true
});

showVpaidControls

Type: boolean
Default Value: false

Set to true to show custom Brightcove controls over VPAID ads. They may or may not work depending on the VPAID implementation, so Brightcove suggests testing this feature with your ads before enabling it in production.

timeout

Type: number
Default Value: 4000

The maximum amount of time, in milliseconds, to wait for ads to play before an ad break is skipped.

This option is part of the ad framework is configured as follows:

player.ima3({
  timeout: 5000
});

In internal Brightcove testing it was found that four seconds seemed to be long enough to accommodate slow initialization in most cases, but still short enough that failures to initialize didn't look like failures of the player or content video.

usePlayerAutoplayHandling

Type: boolean
Default Value: false

If true, control of autoplay is given to the Brightcove Player rather than the plugin.

useMediaCuePoints

Type: boolean
Default Value: false

Enables the use of ad cue points (as defined in Studio) to trigger an ad to play.

For Video Cloud ad cuepoints to be used to trigger ads, the following is required in the plugin configuration:

• useMediaCuePoints: true
• requestMode: The string oncue
• serverUrl: Must point to a valid VAST ad

If you are using Studio to setup advertising, when you select On cue point the useMediaCuePoints and requestMode options will be set correctly for you.

vpaidMode

Type: string
Default Value: ENABLED

Specify VPAID 2 mode in the IMA HTML5 SDK.

There are three possible values for this option:

• ENABLED: Play VPAID ads in an iframe with a different domain.
• INSECURE: Play VPAID ads in an iframe with the same domain.
• DISABLED: VPAID ads throw an error.

This option is configured as follows:

player.ima3({
  vpaidMode: 'DISABLED'
});

Properties

Only one property exists for the plugin:

• html5: This is the only ad tech that can be loaded when the plugin initializes.

Ad macros and the serverUrl

There are ad macros available to make your job easier when creating the ad server URL. These macros enable you to use variables in the server URL for which the IMA3 plugin will substitute appropriate values. For instance, the following server URL contains some of the variables:

{"serverUrl": "//myadserver.com/ad?video={mediainfo.id}&duration={player.duration}"}

The IMA3 plugins would substitute in the appropriate values, and the server URL actually used would appear as follows:

{"serverUrl": "//myadserver.com/ad?video=12340001&duration=60"}

The following is the complete list of variables for which substituted values will be used:

cust_params={mediainfo.ad_keys}

Brightcove Ad Monetization

At minimum, a Brightcove Ad Monetization ad tag using SpringServe will include the following macros:

Privacy

To add the privacy-related macros to your ad tag, your implementation needs to collect the data from users and pass them to the player at runtime. With a standard implementation, each variable is defined as a global JavaScript variable with the same name within the page or app, allowing the player to access them and send them to the ad server when it makes ad requests.

If the variables are named differently within your page or app, ensure that the relevant macro name (pageVariable.macro_name) is updated to match. For example, you could define each variable within a <script> tag at the top of your page like this:

var my_gdpr_variable = true;

The player will then be able to retrieve the gdpr value of true via {pageVariable.my_gdpr_variable}.

Default values and ad macros

You can give ad macros default values. A default value can be provided within a macro, in which case this value will be used where a variable is undefined. The syntax is:

{macro=default}

For instance,

http://example.com/ad/{pageVariable.adConf=1234}

would resolve to the following if window.adConf is undefined:

http://example.com/ad/1234

Dynamic macros

Dynamic macros provide access to values in the following:

• The video's customFields object through the mediainfo.customFields variable.
• The DOM's window object through the pageVariable variable.

For example, you could use the following in your ad request:

//myadserver.com/ad?l={pageVariable.navigator.language}&category={mediainfo.customFields.type}

For the pageVariable values, only certain value types are allowed to be used, as shown in this table:

TCF macros

If a consent management platform, or CMP (essentially a range of advertising technologies all rolled into one easy-to-use platform), supporting the GDPR Transparency and Consent Framework (TCF) is in use, additional macros are made available. The syntax is {tcf.*}, with * being a property in the tcData object.

The most commonly used macros are:

Since gdprApplies is a boolean and many ad servers expect the value as an integer, an additional {tcf.gdprAppliesInt} is provided which will return 1 or 0.

If the player is in an iframe, a proxy will be added if the TCF API is detected in any parent frame to gain consent with the postmessage API. The CMP must be loaded before the player.

Default values in macros

A default value can be provided within a macro, in which case this value will be used where not resolvable e.g.

http://example.com/ad/{pageVariable.adConf=1234}

http://example.com/ad/1234

if window.adConf is undefined.

Custom ad macros

Although the Dynamic macros technique described just above is the much preferred method to access specific information via macros, you may have defined custom values you use when requesting ads from your ad server that you cannot reach via dynamic macros. In this case, you can utilize your values by overriding the adMacroReplacement() method. When you override this method it allows you to pass your specialized values for the ad request.

The following is an example of overriding the adMacroReplacement() method. In this example, the custom values are defined as part of the page DOM, thus enabling ad requests to be customized on a per page basis. In this example, mySite.category is the location where the ad request information is stored.

brightcovePlayer.ima3.adMacroReplacement = function (url) {
    var parameters = {
    '{category}': mySite.category
  };
  for (var i in parameters) {
    url = url.split(i).join(encodeURIComponent(parameters[i]));
  }
  return url;
}

Using specific values will help clarify exactly what is happening. Assume your request URL to the ad server is the following:

//myadserver.com/myads?adWord={category}

And assume the value dynamically assigned to mySite.category in the page is the string fishing-pole. Then after your version of the adMacroReplacement() method is called your ad request URL would appear as:

//myadserver.com/myads?adWord=fishing-pole

To summarize, when you override the adMacroReplacement() method it allows you to use custom values as ad macros, and dynamically assign values to the URL ad request.

Methods

When you need to interact with the IMA SDK you need to wait for the ima3-ready event to be dispatched before successful use of the SDK can take place. This includes the following two methods.

player.ima3.adrequest( )

Calling this method will create an on-demand adrequest immediately upon receiving an ad response. Invoking this method creates a new IMA adManager which means that any previous ad response information (for instance, a postroll ad returned in a previous VAST response) will be lost. Brightcove recommends that you only use this method in cases where up-front knowledge of ad timings isn't known or you will be making all ad calls on-demand. In all other cases, it makes sense to put all ad data in the initial VAST call on plugin initialization.

The following are two important points to consider when using player.ima3.adrequest( ):

• The method is for use with the ondemand request mode only.
• The method is not recommended for prerolls as content will play before the ad request completes, resulting in a flash of content.

Parameters

• adRequestUrl String Path to a VAST ad tag. You can and should pass relative URLs. This parameter is optional and the configured serverUrl is used if no parameter is passed.

Returns:

• Nothing

Example

player.ima3.adrequest('//pubads.g.doubleclick.net/gampad/ads?sz=640x360&iu=/6062/iab_vast_samples/skippable&ciu_szs=300x250,728x90&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&correlator=[timestamp]');

player.ima3.setAdsRenderingSettings()

This method lets you set ads rendering settings for the IMA SDK for HTML5.

If there is no Ads Manager yet, this method saves your settings and when an Ads Manager is created it uses the settings you provided. If an Ads Manager already exists, it is updated to use your settings. In either case, any new Ads Managers created in the future will also use the most recent settings you provided. You can create an AdsRenderingSettings object by accessing the IMA SDK directly. A variety of settings are available.

Parameters

• google.ima.AdsRenderingSettings object

Returns:

• Nothing

Example:

var adsRenderingSettings = new google.ima.AdsRenderingSettings();
adsRenderingSettings.bitrate = 2500;
adsRenderingSettings.enablePreloading = true;
player.ima3.setAdsRenderingSettings(adsRenderingSettings);

Google's AdsManager

There are methods and properties available from Google's google.ima.AdsManager Interface. You can use the interface's properties/methods that retrieve information. It is not advised to use the methods that perform actions, like destroy, setAutoPlayAdBreaks and stop. For example, one method you can use is shown here:

AdsManager.getRemainingTime

Type: google.ima.AdsManager.getRemainingTime

Usage: myPlayer.ima3.adsManager.getRemainingTime()

Calling this method returns the amount of time remaining for the current ad. If an ad isn't available or has finished playing, it returns -1. For more information see Google's documentation on the method.

Accessing the IMA SDK directly

A number of IMA settings are available on the plugin object at runtime. For instance, to determine the ad ID you would use:

var adId = player.ima3.currentAd.getAdId();

Be careful interacting directly with these properties. Calling the wrong method can lead to unexpected results and failure of advertisements to play properly.

adsLoader

Type: google.ima.AdsLoader

The object used to create ads requests. See ima.AdsLoader. The Ads Loader may not be available until adsready has been fired by the plugin.

adsManager

Type: google.ima.AdsManager

The object responsible for playing ads. See ima.AdsManager. The Ads Manager is not available until adsready has been fired by the plugin.

adDisplayContainer

Type: google.ima.AdDisplayContainer

The object responsible for managing the display elements for ads. See ima.AdDisplayContainer. The Ads Display container may not be available until adsready has been fired by the plugin.

currentAd

Type: google.ima.Ad

When an ad is playing, an object that encapsulates information about the current ad. See ima.Ad.

Events

The plugin emits some custom event types during loading, initialization, and playback. You can listen for IMA3 and ad framework events just like you would any other event:

player.on('ima3-ready', function(event) {
  console.log('event', event);
});

Re-dispatched ima3- prefixed events

When the IMA3 plugin is used in HTML mode, all AdErrorEvents, AdEvents and AdsManagerLoadedEvents are re-dispatched onto the player. When the events are re-dispatched, they are prefixed with ima3-. The following table shows the re-dispatched events:

Live video and IMA3

If you are using version 3.1.0+ of the IMA3 plugin, you can use pre-rolls with a live event. The pre-roll will play when each viewer begins to watch the live event, not the one time the live event begins. When configuring your event in the Live module, as shown in the Creating and Managing Live Events using the Live Module document, you are prompted to select a player. You will want to configure advertising for the player you select, as shown in the Step-by-Step: Implementing Advertising document.

Note the following details of the implementation:

• Only pre-rolls will play. Mid-rolls and post-rolls are not supported.
• The Request Ads type must be either On load or On play.
• You must be using version 3.1.0 or later of the IMA3 plugin, as mentioned earlier.

Player Ad Libraries

The videojs/videojs-contrib-ads GitHub repository contains a plugin which provides common functionality needed by video advertisement libraries working with Brightcove Player. The plugin provides common functionality needed by video ad integrations and takes care of a number of concerns for ad integrators, reducing the code you have to write for your ad integration. The plugin is fully documented, with an index page as the best starting point.

There are methods, events and properties available for use from the plugin. Full details are provided in the videojs-contrib-ads API reference. A sampling of the tools available are provided here, starting with methods:

The plugin also dispatches numerous events, a few are listed here:

The plugin also provides numerous properties, a few are listed here:

The following code demonstrates the use of the properties:

var myPlayer,
  player = bc('myPlayerID');
player.ima3({
  serverUrl: '//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml'
});
player.ready(function () {
  myPlayer = this;
  myPlayer.on('ads-ad-started', function (evt) {
    console.log('ads-ad-started event passed to event handler', evt);
    console.log('myPlayer.ads.ad.id', myPlayer.ads.ad.id);
    console.log('myPlayer.ads.ad.index', myPlayer.ads.ad.index);
    console.log('myPlayer.ads.ad.duration', myPlayer.ads.ad.duration);
    console.log('myPlayer.ads.ad.type', myPlayer.ads.ad.type);
  });
});

The output in the console from the above code is shown here:

Debugging assistance

There are two options for assistance when debugging ad playback issues. If you do nothing, in the console you will see only information on when ads started and finished:

The first option is mentioned earlier in this document in the Options section. This turns on debugging at the plugin level. You will see additional debugging information:

The second option utilizes a tool supplied by Google. You specify a sdkurl option with a value pointing to a JavaScript file supplied by Google. An example configuration is shown here:

var myPlayer = bc('myPlayerID');
myPlayer.ima3({
  "serverUrl": "//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml",
  "debug": true,
  "sdkurl": "//imasdk.googleapis.com/js/sdkloader/ima3_debug.js"
});
myPlayer.ready(function() {
  myPlayer = this;
});

The expanded debugging information would appear similar to the following. (The yellow highlighted information is from the plugin's debugging and the blue highlighted information is generated by the Google tool.)

For more details on Google's IMA errors, see the Class google.ima.AdError section of Google's Google IMA HTML5 SDK APIs document.

Known issues

Manually advancing videos in a playlist when there are postroll ads

When manually advancing to the next video in a playlist, the postroll from the previous video, if present, may play simultaneously over the new video content. Alternatively, on mobile devices advancing the playlist manually may result in no new content playing at all.

This is caused by a 3rd party issue in Google's IMA SDK library. This issue should be addressed in an upcoming Google release.

Safari's Stop Media With Sound setting and autoplay: "play" or autoplay: true

Safari behaves a bit different than other browsers in regards to autoplay. Specifically, if the browser setting is Stop Media With Sound and unmuted autoplay is attempted, the media element will still emit play and playing events even though autoplay is rejected. Currently, this will prevent a smooth fallback to click-to-play and cause ad playback to fail.

This issue will be addressed in a future 4.x plugin release. In the meantime, to avoid this issue, we recommend using either muted or any for the player's autoplay value.

Overlays

When using overlay ads, the position of the thumbnail seeking image may remain stuck to the left side of the progress bar, and the progress bar may not expand when hovering over it.

This issue will be addressed in a future 4.x plugin release.

Livestream with cuepoint ads

When playing cuepoint-triggered ads in a livestream, the ads will play muted and unmuting them will also unmute the livestream behind the ad.

This issue will be addressed in a future 4.x plugin release.

Picture-in-Picture disabled

The picture-in-picture control disabled when the IMA3 plugin is implemented. This is an intentional design decision.

Setting autoplay in Studio

Do NOT set autoplay in Studio if you are using the IMA3 plugin to display advertisements. Setting autoplay in Studio could cause ad playback failure. See the Autoplay Considerations document for further information.

Learn More and Ad Countdown Timer no longer displayed by default

A work around exists using the useStyledLinearAds property from Google's IMA SDK. Set this value to true, as shown here:

adsRenderingSettings.useStyledLinearAds=true;

For more details, see Google's google.ima.AdsRenderingSettings documentation.

Chrome on Android: Unmute pre-roll, video will not autoplay

When using Chrome (latest version) on Android and unmute the player while pre-roll is playing, player does not start playing a video automatically after pre-roll ends. If you unmute the ad, the volume persistence feature of Brightcove Player will also unmute the content since the intention of the viewer is to hear the audio. However, on newer versions of Chrome Android, unmuted content cannot be auto-played and the user-gesture requirement to begin playback has been added. This is an OS/Device-level setting and not something Brightcove can override.

Preroll's Current Time display may not be accurate

This problem has to do with a limitation in the way the IMA SDK reports the current time. There is no work around documented at this time.

Unmuted midrolls may not play on Safari 11 Desktop

Unmuted midrolls may not play on Safari 11 Desktop due to a change in Google's IMA SDK. A new behavior was introduced to trigger an error and cancel an ad when autoplay is rejected by Safari 11 (Desktop and possibly iOS). Midrolls impacted in this way will trigger an ad error 400, with error code 1205 indicating autoplay was prevented.

Supported environments

To check for supported combinations of platforms, advertising standards and video media, see Google's Video Feature and SDK compatibility document. That document and the Video Suite Inspector will help you diagnose attempted IMA3 advertisement configurations that simply will not function.

Overlays and Fullscreen Transitions

video.js uses the fullscreen API where available. Different browsers implement the transition to fullscreen differently and that can produce discrepancies in appearance when transitioning into and out of fullscreen mode. In most implementations, the element that is being taken into fullscreen is geometrically scaled (i.e. zoomed) from its original to the target size. Most overlay advertisements are designed to be displayed at a fixed size, however, and so they may appear distorted until the animation completes.

Skippable ads on iOS devices

With the IMA3 plugin, skippable ads can be played on iPhones when the following conditions are met:

• The playsinline attribute is present on the video element
• The disableCustomPlaybackForIOS10Plus setting is passed to the plugin, and set to true

For the playsinline attribute, simply include it as an attribute in the video tag:

<video-js id="player"
  width="640"
  height="360"
  data-video-id="4524585416001"
  data-account="4360108595001"
  data-player="r12ukws9l"
  data-embed="default"
  playsinline
  controls></video-js>

For the disableCustomPlaybackForIOS10Plus setting, assign it as a property of ima3SdkSettings:

player.ima3({
  ima3SdkSettings: {
    "disableCustomPlaybackForIOS10Plus": true
  }
})

If you are using Studio and wish to use the setting there, add this to your IMA3 plugin configuration:

{
  "ima3SdkSettings": {
    "disableCustomPlaybackForIOS10Plus": true
  }
}

For full details of this setting, see the disableCustomPlaybackForIOS10Plus entry in the ima3SdkSettings section of this document.

Skippable ad limitations:

• The Skip Ad button may be partially covered by the ad control bar on some mobile devices. This makes it difficult for end users to actually skip the ad. The user can pinch to zoom to make the Skip Ad button bigger on mobile devices to be able to click it.
• iPhone without playsinline and disableCustomPlaybackForIOS10Plus - Skippable ads are not played.
• iPhone with playsinline and disableCustomPlaybackForIOS10Plus - Ads are played inline, but if using fullscreen, ads do not show, but audio for the ad will play. In other words, skippable ads in fullscreen do not function correctly.
• iPad - Ads are played inline but skip is not available in fullscreen mode

iOS 10 iPad and iPhone: Preroll ads not working when using playsinline and going fullscreen

If using playsinline on iOS 10 iPad and iPhone to allow viewing a video not fullscreen, then a preroll ad starts, and the fullscreen button is clicked, the ad will NOT continue to play. This is a limitation of the Google's IMA implementation, and Google does not have plans to correct the issue.

Conflict with gpt_proxy.js

If using the GPT proxy script with IMA3, and the adTechOrder is HTML5 first, playback issues can occur. The IMA3 plugin will be affected when using any script that uses window.google or window.google.ima. It is suggested that you check if you're using Brightcove Player, and if so, don't load the proxy on those occasions.

Resize Skip Ad button

It is not possible to resize the Skip Ad button. The Brightcove Player API does not have methods or properties to specify the size of the Skip Ad button. At the developer level, if a publisher is using VPAID ads, the ads can implement their own Skip Ad button and logic to fit within the UI and element distribution of Brightcove Player.

Ads will not autoplay on iOS

Although not specific to the IMA3 plugin, know that autoplay is restricted iOS, so ads will not start until a user gesture is made.

Ad cue point issues

For issues specific to using ad cue points, see the Known issues section of the Displaying Ads Using Ad Cue Points document.

IMA3 SDK's url parameter

Google Ad Manager's url parameter is the full URL from which the ad request is sent. Note that this value is automatically set by the IMA SDK, and will in fact overwrite any values you may provide.

Changelog

See the IMA3 Plugin Release Notes.

For historical release notes, see the changelog here.