Contact Support | System Status
Page Contents

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

    In this topic, you will learn how to use the iab Open Measurement SDK with Brightcove Player's Server-Side Ad Insertion (SSAI) plugin.

    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:

    1. Review the Implementing Server-Side Ads with Brightcove Player document.
    2. 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.partnerName 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:

    3. 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:

    1. 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.
    2. Click the link for the player to open the player's properties.
    3. In the left navigation, click Plugins.
    4. From the Add a Plugin dropdown, select Custom Plugin.

      Custom Plugin
    5. For the Plugin Name enter ssai.
    6. For the JavaScript URL, enter:
      https://players.brightcove.net/videojs-ssai/1/videojs-ssai.js
    7. For the CSS URL, enter:
      https://players.brightcove.net/videojs-ssai/1/videojs-ssai.css
    8. 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"
        }
      }
    9. Click Save.
    10. To publish the player, click Publish & Embed > Publish Changes.
    11. 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.

    1. In Video Cloud Studio, navigate to the PLAYERS module.
    2. In the left navigation, click JSON Editor.
    3. In the plugins array, add the OM options to the options object.
    4. "options": {
        "enableOM": true,
        "omParams": {
          "partnerName": "IAB Partner Name",
          "partnerVersion": "1.0.0",
          "accessMode": "full"
        }
      }
    5. Click Save.
    6. To publish the player, click Publish & Embed > Publish Changes.
    7. 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:

    1. In Studio, navigate to the Media module and select a video.
    2. In the top menu, click Publish and embed.
    3. In the Copy Code section, copy the Advanced player embed code.
    4. 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>
      
    5. 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/

    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

    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.


    Page last updated on 01 Nov 2021