Overview: The Context Script gives publishers the ability to retrieve Context Data Segments 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 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 the context segments for the initial asset ID.

4. Add either the context segment 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 segments for all Adaptive Plugin recommendations and store data on the client-side.

6. Add context segments 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 segments.

Please confirm with your IRIS.TV Account Manager:

• Where the context segments 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 segments

Parameters for this getVideoInfo route

• platform_id: reference ID of the video. Required

Steps

1. Send platform_id to getVideoInfo route.

2. Retrieve context segments from getVideoInfo,.

3. Send context segments 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’], platform_id: 'platform-id-value' }
  console.log(data.context);
  console.log(data.categories);
});

Example of response for getVideoInfo

{
  platform_id: '6026440620001',
  context: ["e883d22ce29c85f9e910281d2a410c5bad77a098"]
} 

Recommended Videos: Using the getRecommendationInfo route to retrieve context segments

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 segments.

4. Send context segments 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>},
       <platform_id>: { context: <value>},
      }
    */
 });
});