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 - click images below to see
Collect and save quiz results and display aggregated response rates to viewers:
Read a tutorial on how we built this demo.
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: 'video', id: 'NAME_OF_CHOICE', duration: NEW_DURATION_IN_SECONDS } }"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);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:
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"></iframe>Initialize an instance of playerjs.Player:
const player = new playerjs.Player('iframe');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.play();
});The examples below assume you are using the Player.js library.
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');Available 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 during playback:
{ seconds: 10, duration: 40 }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.
choice fires when a user makes a choice or when an automatic transition occurs (details above).
{ type: 'video', id: 'option2', duration: 78 }