Open Measurement for Server-Side Ads (SSAI) and Brightcove Player

Overview

The Open Measurement SDK for web video can be integrated with the videojs-ssai plugin to allow IAB partners and ad vendors “third-party” access to creative performance measurement data using a standardized API.

The SSAI plugin includes an opt-in feature set that uses VAST ad verification data and Open Measurement (OM) service/client scripts imported by the user to manage client sessions and OM ad life-cycle events during live or VOD content playback.

Requirements

Open Measurement session features for SSAI require the following:

Active membership with the IAB Tech Lab for organization name space registration and access to OM SDK files
Access to and ability to directly host the following:
- omweb-v1.js service script
- omid-session-client-v1.js session client (part of the Web Video OM SDK files provided by IAB)
- Optionally, if using the domain access mode, omloader-v1.html is also required
The SSAI plugin must be initialized on the player with required options
VMAP/VAST XML must include AdVerifications tags and nested content
Brightcove Player SSAI Plugin v1.14.0 or higher
Brightcove Player v6.57.2 or higher

Getting started

Enabling OM features for the videojs-ssai plugin is nearly identical to (and actively leverages) a regular SSAI implementation.

To enable OM features, follow these steps:

Review the Implementing Server-Side Ads with Brightcove Player document.
When initializing the SSAI plugin, you must set OM options as follows:
- The SSAI enableOM option must be set to true.
- omParams.partnerName must be provided as the organization's IAB name space.
- omParams.partnerVersion must be provided as the app version.
- omParams.accessMode is optional, though the session client will default to a limited access mode if none is provided.
For details, see the SSAI Options for Open Measurement section.

These options can be passed to the plugin using Brightcove Player configuration using either of the following:
- Implementing OM using Studio
- Implementing OM programmatically
Add the domain access mode. (Optional)

The domain access mode parameter will cause the imported OM service script to look for omloader-v1.html file in the following relative directory path:
```
.well-known/omid/omloader-v1.html
```
If the file is missing from that specific path, the OM session client will fail to start.

For details, see the IAB documentation for publishers regarding access modes.

Implementing OM using Studio

The easiest way to configure your player for Open Measurements with SSAI is with Video Cloud Studio. Configure the player as follows:

In Video Cloud Studio, navigate to the PLAYERS module and either create a new player or locate the player to which you wish to add the plugin.
Click the link for the player to open the player's properties.
In the left navigation, click Plugins.
From the Add a Plugin dropdown, select Custom Plugin.
For the Plugin Name enter ssai.

For the JavaScript URL, enter:

https://players.brightcove.net/videojs-ssai/1/videojs-ssai.js

For the CSS URL, enter:

https://players.brightcove.net/videojs-ssai/1/videojs-ssai.css

In the Options(JSON) section add your values for the OM options.

{
  "enableOM": true,
  "omParams": {
    "partnerName": "IAB Partner Name",
    "partnerVersion": "1.0.0",
    "accessMode": "full"
  }
}

Click Save.
To publish the player, click Publish & Embed > Publish Changes.
Import the OM scripts.

The omweb-v1.js and omid-session-client-v1.js files must be imported ahead of any other script tags in the page DOM. These can be hosted locally or via a CDN.

Example
```
<script src="./omweb-v1.js"></script>
<script src="./omid-session-client-v1.js"></script>
<script src="./video.core.js"></script>
...
```

Using the JSON editor

Alternatively, you can use Studio's JSON editor to add OM options to a player that is already configured with the SSAI plugin.

In Video Cloud Studio, navigate to the PLAYERS module.
In the left navigation, click JSON Editor.
In the plugins array, add the OM options to the options object.

"options": {
  "enableOM": true,
  "omParams": {
    "partnerName": "IAB Partner Name",
    "partnerVersion": "1.0.0",
    "accessMode": "full"
  }
}

Click Save.
To publish the player, click Publish & Embed > Publish Changes.
Import the OM scripts.

The omweb-v1.js and omid-session-client-v1.js files must be imported ahead of any other script tags in the page DOM. These can be hosted locally or via a CDN.

Example
```
<script src="./omweb-v1.js"></script>
<script src="./omid-session-client-v1.js"></script>
<script src="./video.core.js"></script>
...
```

Implementing OM programmatically

You can easily add OM features to your player using Video Cloud Studio, as shown in the previous section. If you prefer to do this programmatically, follow these steps:

In Studio, navigate to the Media module and select a video.
In the top menu, click Publish and embed.
In the Copy Code section, copy the Advanced player embed code.

Modify the Advanced player embed code to include the SSAI plugin and the OM options.

<script>
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;
    myPlayer.ssai({
      enableOM: true,
      omParams: {
        partnerName: 'IAB Partner Name',
        partnerVersion: '1.0.0',
        accessMode: 'full'
      });
  });
</script>

Import the OM scripts.

The omweb-v1.js and omid-session-client-v1.js files must be imported ahead of any other script tags in the page DOM. These can be hosted locally or via a CDN.

Example
```
<script src="./omweb-v1.js"></script>
<script src="./omid-session-client-v1.js"></script>
<script src="./video.core.js"></script>
...
```

SSAI Options for Open Measurement

Options can be passed to the SSAI plugin at initialization. Both the enableOM and omParams options are required for an OM session to be started.

`enableOM`

If true (and the necessary Open Measurement SDK scripts have been successfully imported), the plugin will use values from the omParams object to start an OM manager and create a new OM session client.

Example

"enableOM": true

`omParams`

An object describing the required parameters for starting an Open Measurement session client and OM ad/media event calls.

omParams.partnerName

Partner name string. This is name-spaced to an organization upon IAB partnership.
omParams.partnerVersion

Partner application version string in a semver format.
omParams.accessMode

Preferred access mode string. Values:
- limited
- domain
- creative
- full
A missing or unrecognized value here will cause the OM client to default to limited/

As of October 2021, the creative access mode is translated to full by the OM manager, per session client requirements, and will appear as full in the OM ad session call data.

Example

"omParams": {
  "partnerName": "IAB Partner Name",
  "partnerVersion": "1.0.0",
  "accessMode": "full"
}

Player and Extension Support

The Open Measurement (OM) manager uses data from VAST AdVerifications tags to communicate player, ad, and media event information before and during content playback via the OM session client.

AdVerifications tag support using VAST 3.0 is provided via Extensions. AdVerifications tags are expected to be nested in the InLine element with VAST 4.0 and up.

VAST 3.0

VAST/Ad/InLine/Extensions/AdVerifications/...

VAST 4.0+

VAST/Ad/InLine/AdVerifications/...

Sample `AdVerifications` Tag and Child Elements

<AdVerifications>
  <Verification vendor="sample-vendor">
    <JavaScriptResource apiFramework="omid" browserOptional="false">
      <![CDATA[vendor-defined-url/omid-script.js]]>
    </JavaScriptResource>
    <VerificationParameters>
      <![CDATA[vendor-defined-content]]>
    </VerificationParameters>
  </Verification>
</AdVerifications>

The SSAI OM manager is specifically interested in the following items for session context definition:

vendor attribute
JavascriptResource content
VerificationParameters content

The SSAI plugin parses VMAP/VAST XML to a more javascript-friendly object. You can access VAST ad data by calling the following:

player.ssai().vmap.adBreaks[i].adSource.vastAdData

The use of [i] denotes that the property is an array.

OM Ad Events

The OM manager currently listens for and mediates the following Brightcove Player ad events:

Brightcove Player events
Event	Description
`ads-ad-started`	start
`ads-first-quartile`	first quartile
`ads-midpoint`	midpoint
`ads-third-quartile`	third quartile
`ads-ad-ended`	complete
`ads-pause`	pause
`ads-play`	resume
`adwaiting`	bufferStart
`adplaying`	bufferEnd
`advolumechange`	player volume change
`ads-ad-skipped`	skipped

Notes

The following notes apply to the Open Measurement integration:

The OM service and manager both expect VAST data to contain AdVerifications elements. If the elements are not present for an inline ad, the OM session client will skip over it.
The OM manager sets the impression type to loaded ("Integration is using count-on-download criteria") to match the expected player definition of an ad impression.
IAB advises against attempting to concatenate the omweb service script. It must be imported with a script tag.

Changelog

See the SSAI Plugin Release Notes.

For historical release notes, see the changelog here.

Open Measurement for Server-Side Ads (SSAI) and Brightcove Player

Overview

Requirements

Getting started

Implementing OM using Studio

Using the JSON editor

Implementing OM programmatically

SSAI Options for Open Measurement

enableOM

Example

omParams

Example

Player and Extension Support

VAST 3.0

VAST 4.0+

Sample AdVerifications Tag and Child Elements

OM Ad Events

Notes

Changelog

`enableOM`

`omParams`

Sample `AdVerifications` Tag and Child Elements