Adventr Realtime Player API – Adventr

Note: The Adventr Realtime Player API is available to subscribers to our Business plan or above.

With the Adventr Realtime Player API you can write simple javascript code to control playback or have your page react to player events in realtime.

Examples:

Collect and save quiz results and display aggregated response rates to viewers
Build a shoppable video where tapping on products adds them to a shopping cart without interrupting the video experience
Survey viewers through an interactive video

How it works

The Realtime Player API is built to be fully-compatible with the popular Player.js library, so we recommend using the player.js library to listen for events and call methods on an Adventr player.

The Adventr API extends the Player.js spec with additional events unique to interactive videos.

The Adventr player attempts to send events via window.postMessage. You can add listeners for these events manually or for Player.js-compatible events, using the player.on() method (see below).

Adventr-Specific Events

`choice`

A choice event (when someone chooses a video or link in the Adventr player) sends a message to your window that looks like:

'{ 
  "context": "adventr", 
  "version": "0.1", 
  "event": "choice", 
  "value": { 
    "type": "clip", 
    "id": "option2", 
    "label": "label string", 
    "mainImage": "https://full-url-of-button-image", 
    "hoverImage": "https://full-url-of-button-hover-image", 
    "autoChoose": 0, 
    "duration": 78, 
    "overlayType": "image-button" 
  }
}'

You can add a listener for that event as follows:

window.addEventListener("message", (event) => {
  // first, determine if event is JSON
  let received;
  try {
    received = JSON.parse(event.data);
  } catch (e) {
    received = {event: event.data}
  }
  // check the message is in adventr format and if the event is a choice
  if (received.context === 'adventr') {
    if (received.event === 'choice') {
      // do something cool with received.value!
    }
  }
}, false);

Adventr-specific Methods

getCurrentClip()

Use the getCurrentClip method to obtain details about the current clip and its possible choices.

adventrPlayer = document.getElementById('adventrPlayer'); // the id of the Adventr iframe

// set up a listener for the method's response
window.addEventListener("message", (event) => {
  // first, determine if event is JSON
  let received;
  try {
    received = JSON.parse(event.data);
  } catch (e) {
    received = {event: event.data}
  }
  // check the message is in adventr format and if the event is a response to getCurrentClip
  if (received.context === 'adventr') {
    if (received.event === 'getCurrentClip') {
      // do something cool with received.value
    }
  }
}, false);

// call the method
adventrPlayer.contentWindow.postMessage(
    JSON.stringify({
        context: 'adventr',
        version: '4.0.0',
        method: 'getCurrentClip'
    }), '*'
);

The listener will have useful data about the current clip and choices in the received.value object. It will have a format like the following:

{
  "id": "current-clip-id",
  "startTime": 0,
  "choices": [
    {
      "id": "overlay_1",
      "startTime": 2.25,
      "endTime": 15,
      "timeRemaining": 11.1,
      "type": "clip",
      "overlayType": "image-button",
      "label": "Choice 1",
      "mainImage": "https://urlofbuttonimage",
      "hoverImage": "https://urlofbuttohovernimage"
    },
    {
      "id": "overlay_2",
      "startTime": 3.1,
      "endTime": 14,
      "timeRemaining": 10.2,
      "type": "clip",
      "overlayType": "image-button",
      "label": "Choice 2",
      "mainImage": "https://urlofbuttonimage",
      "hoverImage": "https://urlofbuttohovernimage"
    }
  ],
  "clipDuration": 15,
  "choicesTimeRemaining": 11.1
}

`choose(choiceID)`

Use the choose method to select a currently available choice. This will do the same thing as if the user had clicked on or spoken the choice.

adventrPlayer = document.getElementById('adventrPlayer'); // the id of the Adventr iframe

adventrPlayer.contentWindow.postMessage(
    JSON.stringify({
        context: 'adventr',
        version: '4.0.0',
        method: 'choose',
        value: "overlay_1" // use an id you obtained from getCurrentClip
    }), '*'
);

`getAllVariables()`

Use the getAllVariables method to obtain the value of all variables in the Adventr. If you are using Smart Merge or Conditional / Change Variables, this method is a handy way to obtain the current values during playback.

You'll need to set up a listener before calling this method:

function receiveMessage(event) {
  // first, determine if event is JSON
  let received;
  try {
    received = JSON.parse(event.data);
  } catch (e) {
    received = {event: event.data}
  }

  // if the event is JSON, check that it's in the adventr format and if it is what you are looking for
  if (received.context === 'adventr') {
    if (received.event === 'getAllVariables') {
      console.log(received.value);
      // do something with received.value
    }
  }
}
// Add the listener to the window:
window.addEventListener("message", receiveMessage, false);

In the above example, the contents of received.value will be an array of variables like:

[
  {
    "name": "var1",
    "type": "boolean",
    "value": true
  },
  {
    "name": "var2",
    "type": "number",
    "value": 12.2
  }
]

To call the method, use code like this:

let adventrPlayer = document.getElementById('adventrPlayer'); 
adventrPlayer.contentWindow.postMessage(
  JSON.stringify({
      context: 'adventr',
      version: '4.0.0',
      method: 'getAllVariables'
  }), '*'
);

`getVariable(variable_name)`

If you just want to check a single variable, the getVariable method allows you to specify the variable you are looking for.

Again, you'll need to set up a listener before calling this method:

function receiveMessage(event) {
  // first, determine if event is JSON
  let received;
  try {
    received = JSON.parse(event.data);
  } catch (e) {
    received = {event: event.data}
  }

  // if the event is JSON, check that it's in the adventr format and if it is what you are looking for
  if (received.context === 'adventr') {
    if (received.event === 'getVariable') {
      console.log(received.value);
      // do something with received.value
    }
  }
}
// Add the listener to the window:
window.addEventListener("message", receiveMessage, false);

In the above example, the contents of received.value will be a single hash of the requested variable like:

{
  "name": "var2",
  "type": "number",
  "value": 12.2
}

To call the method, use code like this:

let adventrPlayer = document.getElementById('adventrPlayer'); 
adventrPlayer.contentWindow.postMessage(
  JSON.stringify({
      context: 'adventr',
      version: '4.0.0',
      method: 'getVariable',
      value: 'var2' // the name of the variable you want
  }), '*'
);

Using Player.js for additional events and methods

The methods and events listed below can be used directly via window.postMessage but you'll need to format them according to the Player.js spec. Alternatively, you can use the Player.js library to make it easier to work with.

Initialize a player.js instance:

1. Include the library on your page:

<script type="text/javascript" src="//cdn.embed.ly/player-0.1.0.min.js"></script>

2. Embed an Adventr iframe:

<iframe src="https://player.adventr.io/video?link=https%3A%2F%2Fd252srr1zuysk4.cloudfront.net%2Fclients%2F10%2F213%2Fpublished%2F10-news-42993467.data" width="640px" height="360px" frameborder="0" scrolling="no" allowfullscreen allow="autoplay; fullscreen" id="adventrPlayer"></iframe>

3. Initialize an instance of playerjs.Player:

const player = new playerjs.Player('iframe');

4. Then you can use methods and add event listeners once the player has sent its ready event:

player.on('ready', () => { 
  player.on('play', () => { 
    console.log('play'); 
  }); 
  player.getDuration(duration => console.log(duration)); 

  player.mute(); 
});

The examples below assume you are using the Player.js library.

Player.js Methods

play

player.play();

pause

player.pause();

getPaused: boolean (Determine if the media is paused)

player.getPaused(function(value){ console.log('paused:', value); });

mute

player.mute();

unmute

player.unmute();

getMuted: boolean (Determine if the media is muted)

player.getMuted(value => console.log('muted:', value));

setVolume (Set the volume. Value needs to be between 0-100)

player.setVolume(50);

getVolume: number (Get the volume. Value will be between 0-100)

player.getVolume(value => console.log('getVolume:', value));

getDuration: number (Get the duration of the media is seconds)

player.getDuration(value => console.log('getDuration:', value));

setCurrentTime: number (Perform a seek to a particular time in seconds)

player.setCurrentTime(50);

getCurrentTime: number (Get the current time in seconds of the video)

player.getCurrentTime(value => console.log('getCurrentTime:', value));

off (Remove an event listener. If the listener is specified it should remove only that listener, otherwise remove all listeners)

player.off('play'); 
player.off('play', playCallback);

on (Add an event listener)

player.on('play', () => console.log('play'));

supports: ['method', 'event'], methodOrEventName (Determines if the player supports a given event or method.)

player.supports('method', 'getDuration'); 
player.supports('event', 'ended');

Player.js Events

ready fired when the media is ready to receive commands. This is fired regardless of listening to the event. Note: As outlined in the Player.js Spec, you may run into inconsistencies if you have multiple players on the page with the same src. To get around this, simply append a UUID or a timestamp to the iframe's src to guarantee that all players on the page have a unique src.

progress fires when the media is loading additional media for playback:

{ percent: 0.8 }

timeupdate fires periodically during playback:

{ seconds: 10, duration: 40, choicesTimeRemaining: 10.2 }

play fires when the video starts to play.

pause fires when the video is paused.

ended fires when the video is finished.

error fires when an error occurs.

Note: Adventr does not support the getLoop or setLoop methods from player.js - these do not apply to an interactive experience like Adventr.