Adventr Realtime API

A few things people build with it:

Collect and save quiz results and display aggregated response rates to viewers
Create shoppable video where tapping/speaking products adds to cart without interrupting the video experience — see how
Survey viewers through an interactive video

How it works

The Realtime Player API is fully compatible with the popular Player.js library, so we recommend using it 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 sends events via window.postMessage. You can add listeners for these manually, or for Player.js-compatible events, using the player.on() method.

Adventr-specific events

choice

Fires when someone chooses a video or link in the Adventr player. The message sent to your window 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"
  }
}

Add a listener for that event:

window.addEventListener("message", (event) => {
  let received;
  try { received = JSON.parse(event.data); }
  catch (e) { received = { event: event.data }; }

  if (received.context === "adventr" && received.event === "choice") {
    // do something cool with received.value
  }
}, false);

Adventr-specific methods

getCurrentClip()

Obtain details about the current clip and its possible choices.

const adventrPlayer = document.getElementById("adventrPlayer");

// set up a listener for the method's response
window.addEventListener("message", (event) => {
  let received;
  try { received = JSON.parse(event.data); }
  catch (e) { received = { event: event.data }; }

  if (received.context === "adventr" && 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"
}), "*");

received.value has a shape like:

{
  "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://urlofbuttonhoverimage"
    },
    {
      "id": "overlay_2",
      "startTime": 3.1,
      "endTime": 14,
      "timeRemaining": 10.2,
      "type": "clip",
      "overlayType": "image-button",
      "label": "Choice 2",
      "mainImage": "https://urlofbuttonimage",
      "hoverImage": "https://urlofbuttonhoverimage"
    }
  ],
  "clipDuration": 15,
  "choicesTimeRemaining": 11.1
}

choose(choiceID)

Select a currently available choice — the same as if the viewer had clicked or spoken it.

const adventrPlayer = document.getElementById("adventrPlayer");

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

getAllVariables()

Obtain the value of every variable in the Adventr. Handy for reading current values during playback if you’re using Smart Merge or Conditional / Change Variables.

Set up a listener before calling the method:

function receiveMessage(event) {
  let received;
  try { received = JSON.parse(event.data); }
  catch (e) { received = { event: event.data }; }

  if (received.context === "adventr" && received.event === "getAllVariables") {
    console.log(received.value);
    // do something with received.value
  }
}
window.addEventListener("message", receiveMessage, false);

received.value will be an array of variables:

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

Then call the method:

const adventrPlayer = document.getElementById("adventrPlayer");

adventrPlayer.contentWindow.postMessage(JSON.stringify({
  context: "adventr",
  version: "4.0.0",
  method: "getAllVariables"
}), "*");

getVariable(variable_name)

Check a single variable by name. Set up a listener before calling the method:

function receiveMessage(event) {
  let received;
  try { received = JSON.parse(event.data); }
  catch (e) { received = { event: event.data }; }

  if (received.context === "adventr" && received.event === "getVariable") {
    console.log(received.value);
    // do something with received.value
  }
}
window.addEventListener("message", receiveMessage, false);

received.value will be a single hash for the requested variable:

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

Then call the method:

const 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 below can be used directly via window.postMessage, formatted to the Player.js spec — or more easily through the Player.js library itself.

Include the library on your page:

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

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>

Initialize an instance of playerjs.Player:

const player = new playerjs.Player("adventrPlayer");

Use methods and add event listeners once the player has fired 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’re using the Player.js library.

Player.js methods

play

player.play();

pause

player.pause();

getPaused — boolean, is the media paused

player.getPaused((value) => console.log("paused:", value));

mute

player.mute();

unmute

player.unmute();

getMuted — boolean, is the media muted

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

setVolume — value between 0 and 100

player.setVolume(50);

getVolume — number, 0–100

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

getDuration — number, duration of the media in seconds

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

setCurrentTime — number, seek to a time in seconds

player.setCurrentTime(50);

getCurrentTime — number, current time in seconds

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

off — remove a listener; removes all listeners for the event if none is specified

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

on — add an event listener

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

supports — whether the player supports a given method or event

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

Player.js events

ready

Fired when the media is ready to receive commands — this fires regardless of whether you’re listening. Note: per the Player.js spec, multiple players on the page with the same src can behave inconsistently. Append a UUID or timestamp to each iframe’s src to guarantee it’s unique.

progress

Fires while the media is loading additional content 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 don’t apply to an interactive experience like Adventr.