Overview: The Context Script gives publishers the ability to retrieve context and IAB category information on a given asset. This is meant to be used as a part of your ad workflow to send context data through your ad server. This documentation will walk through how clients using the Adaptive Plugin can add the Context Script and retrieve context or IAB category for the initial asset and IRIS.TV recommendations.

See example implementation page here: https://ovp.iris.tv/demos/context/iris-context-api-autoplay.html

Prerequisites

This workflow requires two values:

• client_token: Authentication string associated with each client. This will be provided by IRIS.TV once the content feed is imported.

NOTE: Brightcove clients' client_token is their Brightcove Account ID.

• platform_id: The reference ID for the video from the publisher’s CMS.

Building the Integration

The order of operations for retrieving the context or category information should be as follows:

1. IRIS.TV Context Script is loaded with the page.

2. The context script is initialized.

3. Call script getVideoInfo route to retrieve context and IAB data for the initial asset ID.

4. Add either the context or IAB category information to the pre-roll ad tag for the initial asset ID. Please confirm with your account manager which field will be used for your integration.

5. Call script method to retrieve context or IAB data for all Adaptive Plugin recommendations and store data on the client-side.

6. Add context or IAB category information to the pre-roll for 1st recommendation.

Repeat Step 6 for each new IRIS.TV recommendation.

Installing the Script

• Add the following script to the top of your page: https://ovp.iris.tv/libs/context/iris-context.min.js

NOTE: The script should be loaded as a high priority to ensure you can receive context information for the pre-roll of the initial video.

An example of adding the script to your page HTML:

<script src=”https://ovp.iris.tv/libs/context/iris-context.min.js” type=”text/javascript”></script>

If you do not want to load the script as a high-priority, there is an event that you can listen to at the global-changes level to ensure that the context methods are available. An example of setting up that event listener:

window.addEventListener(‘IrisContextAPI’, function() {
    // window.IrisContextAPI is ready to be used
});

Initializing the Script

• To initialize the script, provide the following to the IrisContextAPI Object:

  • client_token

var IrisContext = window.IrisContextAPI({
  client_token: '<your client token here>',
});

Using the Script

Once the script is initialized, you can send in the video ID of the initial video to retrieve context and IAB category information.

Please confirm with your IRIS.TV Account Manager:

• If your integration is using context or IAB category information.

• Where the field should be added within the ad tag (i.e. in the “cust_params” field in a DFP tag).

Initial Video: Using the getVideoInfo route to retrieve context or IAB data

Parameters for this getVideoInfo route

• platform_id: reference ID of the video. Required

Steps

1. Send platform_id to getVideoInfo route.

2. Retrieve context or IAB categories from getVideoInfo,.

3. Send context or IAB categories in the pre-roll ad call for the initial video.

Sample formatting of the getVideoInfo request

IrisContext.getVideoInfo('<platform_id of the initial video>', function(data) { 
  // data is ready to be used
  // where data is an object of the form { context: [‘context-value’], categories: [‘iab-value’], platform_id: 'platform-id-value' }
  console.log(data.context);
  console.log(data.categories);
});

Example of response for getVideoInfo

{
  platform_id: '6026440620001',
  categories: ["IAB17-26"],
  context: ["e883d22ce29c85f9e910281d2a410c5bad77a098"]
} 

Recommended Videos: Using the getRecommendationInfo route to retrieve context or IAB data

Steps

1. Call getRecommendationsInfo route as a part of callbacks for IRIS.TV /watch and /next API routes, which are exposed through the irisResponseReady event.

   1. You only need to create this event along with the getRecommendationsInfo route once

   2. You need to send the e.detail.platform_id value as shown below

2. Store data returned from getRecommendationsInfo so it can be used to retrieve data each recommended video.

3. On video load, query player for ID of the video and then query stored platform_id values for context or IAB categories.

4. Send context of IAB category data in the pre-roll ad call for the video.

Sample formatting of the getRecommendationInfo request

window.addEventListener('irisResponseReady', function (e) {
 IrisContext.getRecommendationsInfo(e.detail.platform_id).then(function(data) {
   // <data> will contain the information in the form of:
   /* {
       <platform_id>: { context: <value>, categories: <value> },
       <platform_id>: { context: <value>, categories: <value> },
      }
    */
 });
});