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:

Parameters and Options

Automatic PAL Parameters

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

Optional PAL Parameters:

PAL Integration options

These options allows to modify behavior of the plugin:

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.