Overview: The Context Script gives publishers the ability to retrieve context and IAB category information on a given asset. This is mean 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

• A feed with video URLs needs to be provided for IRIS.TV to import and add contextual data to assets. Video asset URLs need to link to either MP4 or m3u8 files.

• An ad tag that can be appended with iris_context custom key-value pair.

• Ad targeting on the iris_context key-value pair needs to be set up through the ad server.

Please speak to your IRIS.TV representative for details on these requirements.

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 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 your client token to the IrisContextAPI Object:

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

• If you are using the global Adaptive Plugin option, add the value for the global option to the initialize:

var IrisContext = window.IrisContextAPI({
 client_token: '<your client token here>',
 global: 'IrisInstance', // <<<< Same value as Iris Plugin global option
})

Details on the global option can be found here: Adaptive Plugin Customization Options

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 video here>', function(data) { 
  // data is ready to be used
  // where data is an object of the form { context: [‘context-value’], categories: [‘iab-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.

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 (/watch call)

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

Sample formatting of the getRecommendationInfo request (/next call)

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