Google PAL SDK for Brightcove SSAI

In this topic, you will learn about Google PAL SDK.

Overview

As of v2.6.0 the Brightcove Player SSAI plugin facilitates usage of Google’s PAL SDK with a simple API. If PAL SDK is enabled, the plugin will load in the SDK script from Google and provide a set of default parameters to generate an identifier that will be appended to the ad request for VOD and Live content. You can customize the parameters on a per-player basis or at runtime before a video source is set.

Setting up the Ad Tag

The SSAI plugin will append a givn parameter to requests for VMAP (VOD) or M3U8 manifests (Live). This can be seen by inspecting the requests in the Network tab of the browsers dev tools:

google-pal-sdk
google-pal-sdk

Parameters and Options

Automatic PAL Parameters

The following parameters are set by the SSAI plugin for all Google PAL SDK enabled requests:

Parameter name Automatic value
adWillAutoPlay Set to true if the ad is auto-played without waiting for user interaction. Set to false if the ad will wait for user interaction before being played.
adWillPlayMuted Set to true if the ad will be played while muted, or set to false if it will play unmuted
playerType 'video-js'
playerVersion The version of the player
url The URL to which the ads will be targeted. By default, this is the same as the page that will display the ads, but it may be manually set
videoWidth The width of the ad video element

The following values will be automatically included in the request if it is set as part of SSAI Options for Open Measurement:

omidPartnerName The name of the partner integrating OMID measurement. Only set if omidPartnerName has been set
omidPartnerVersion The version of the partner integrating OMID measurement. Only set if omidPartnerVersion has been set

Optional PAL Parameters:

Parameter name Automatic value
continuousPlayback Set to true if the player intends to continuously play the content videos one after another, similar to TV broadcast or video playlist. Set to false otherwise
descriptionUrl The description URL of the content during which the ad will be played. Any description URL string longer than 500 characters will be ignored and excluded from the nonce
sessionID The session ID is a temporary random ID. It is used exclusively for frequency capping. The value for this parameter should be a UUID or “bcSession“. If “bcSession“ is used, the player will use the Brightcove Analytics Session ID
supportedApiFrameworks Example: '2,7,9’ (Player support for VPAID 2.0, OMID 1.0, and SIMID 1.1). This must be provided if OM SDK is in use.
url Can be manually set to override the automatic default
PPID A unique ID for the viewer watching the player. Any PPID exceeding 200 characters will be ignored and excluded from the nonce.

PAL Integration options

These options allows to modify behavior of the plugin:

Option Default value Description Description
maxWait 1000 Maximum amount of time (in ms) that the plugin will wait for the PAL SDK script to load into the page. The plugin will wait for the PAL SDK script to load into the page. It can be helpful to set this to a higher number if end-user network conditions are poor. This value will directly impact the end user's perception of the video's load time.

Configuration

Simple Configuration Example

The most straightforward possible configuration can be implemented by adding a “googlePal“ entry to the “options“ property of the SSAI plugin configuration using the JSON editor in the Players module. If the value is set to true or to an empty object*, the SSAI plugin will use default values to generate and attach a givn parameter to the source request.


    {
        ...
        "plugins": [
          {
            "registry_id": "@brightcove/videojs-ssai",
            "version": "2.x",
            "options": {
              ...
              "googlePal": true
            }
          },
        ]
      }

If the plugin is being initialized manually, the same configuration can be achieved by adding a googlePal property to the SSAI options object:


    videojs.getPlayer('myPlayerID').ready(function() {
      var myPlayer = this;
      myPlayer.ssai({
        googlePal: {}
      });
    });

  

Enhanced Configuration Example:


    {
        ...
        "plugins": [
          {
            "registry_id": "@brightcove/videojs-ssai",
            "version": "2.x",
            "options": {
              "enableOM": true.
              "omParams": {
                "partnerName": "IAB Partner Name",
                "partnerVersion": "1.0.0",
                "accessMode": "full"
              }
              "googlePal": {
                "maxWait": 3000,
                "continuousPlayback": true,
                "sessionID": "bcSession",
                "supportedApiFrameworks": "7"
                "url": "https://sub-domain.example.com"
              }
            }
          },
        ]
      }
  

This player is configured to use SSAI Options for Open Measurement


    "options": {
        "enableOM": true.
        "omParams": {
          "partnerName": "IAB Partner Name",
          "partnerVersion": "1.0.0",
          "accessMode": "full"
        }
  
  • All configuration for PAL SDK is provided as the “googlePal“ property: "googlePal": {
  • The plugin will allow up to 3 seconds for Google’s PAL SDK script to load in: "maxWait": 3000,
  • The player is set up to play content items from a playlist, one after another: "continuousPlayback": true,
  • The player will use a Brightcove Session ID: "sessionID": "bcSession",
  • The player is using OMID 1.0 API: "supportedApiFrameworks": "7"
  • Ads will be targeted to https://sub-domain.example.com: "url": "https://sub-domain.example.com"

With this configuration, the following parameters will be provided to the PAL SDK when a nonce is generated:


    {
        adWillAutoPlay: true/false value determined by player at runtime, 
        adWillPlayMuted: true/false value determined by player at runtime,
        playerType: 'video-js',
        playerVersion: 'vX.X.X',
        url: "https://sub-domain.example.com",
        omidVersion: as reported by OMID.getVersion() at runtime,
        omidPartnerName: 'IAB Partner Name',
        omidPartnerVersion: '1.0.0':
        videoWidth: determined by player at runtime,
        videoHeight: determined by player at runtime,
        "continuousPlayback": true,
        "sessionID": Brightcove Session ID,
        "supportedApiFrameworks": "7"
        "url": "https://sub-domain.example.com"
      } 
  

Dynamic Parameters

The above example shows PAL SDK parameters set in the player configuration. It can also use Player.ssai().googlePal.setParams() to dynamically set any PAL SDK parameter, before the source is loaded.

Here is an example showing how to set these dynamically on a web page:


        <div> style="max-width: 960px;">
        
        
      </div>
      <script>src="https://players.brightcove.net/xxxxxxxxxxxxxx/xxxxxxxx_default/index.min.js"></script>
      <script>
        const adConfigId = "your ad config id";
        const ssaiPlayer = videojs.getPlayer('ssaiPlayer');
        function getPpid (){
          // ...
        }
        function getDescriptionUrl (videoId){
          // ...
        }
        // set dynamic values
        ssaiPlayer.ssai().googlePal.setParams({
          ppid: getPpid(),
          descriptionUrl: getDescriptionUrl('your video id')
        })
        ssaiPlayer.catalog.getVideo('your video id', function(error, video) {
          if (error) {
            ssaiPlayer.error(error);
          } else {
            ssaiPlayer.catalog.load(video);
          }
        }, adConfigId);
      </script>
    

Events

The following events are emitted by the player when the PAL SDK integration is used:

  • bcov-ssai-palsdk-error : This could be fired in response to a few error conditions that may arise. Details of the exact problem can be found in event.message.
  • bcov-ssai-palsdk-loaded: Fired when the Google PAL SDK has loaded.
  • bcov-palsdk-nonce-request: Fired whenever a nonce is requested from the PAL SDK. event.params will list the params used for the request.

Loading the PAL SDK

The SSAI plugin will load the PAL SDK script onto the page if necessary. However, some users may include the script themselves, for example, if it is needed to add an integrity hash for CSP compliance. The SSAI plugin will check for the presence of window.goog.palbefore attempting to add the script and will not add it again if window.goog.palexists.