Rapt Media Player API

The following documentation has been updated to reflect our latest API, which is available alongside of the latest player version. Find out how to opt in to our new player here. Looking for our legacy API documentation? Click here.

Overview

The Rapt Media Player API is organized as a JavaScript plugin that allows developers to extend their interactive experiences into custom applications or websites when paired with a Rapt Media video project*.

The API handles secure delivery of video playback status, custom events and link-outs, and the ability to manage video playback between your asset and the Rapt Media Player. With creative use of the API alongside the Rapt Media Interactive Video project editor, teams have access to exponentially more possibilities for delivering engaging experiences across their organization’s various channels.

The following guide will get you started on integrating your project with basic API usage, details about individual API methods and events, and a collection of sample projects and tutorials for getting a full idea of the scope of the plugin.

*Projects must have the Rapt Media Player API permissions enabled in order to send and receive events to the video player.

Initialization

The Rapt Media Player API is provided as a hosted Javascript file:

With the above on your page, you can then initialize your project by creating a new instance of the Rapt.Player object. Your project will automatically be registered with the API.

Example

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]',
});
player.ready(function() {
  console.log(player.metadata);
});
</script>

The Rapt.Player object expects the following key-value pairs to be present for successful initialization:

target: 'target': the id of the element in which you would like your project to be inserted
project: '[URL ID]': the URL ID can be found in the src of your embed code shown in the distribution pane of the composer

You can listen for the status of the player using two methods:

player.ready : indicates the Rapt project is ready
player.init : indicates that the API is ready. The Rapt project may not be ready at this time.

Both of these methods rely on player.readystate().

Player Information

Public information about the project will be exposed through different methods available within our player object.

Rapt Account Metadata

player.metadata.account: Object

Returns an object with public information about the user account

Properties: -id -ref

Project Metadata

player.metadata.account: Object

Returns an object with public information about the project

Properties: -id -ref

Revision Metadata

player.metadata.revision: Object

Returns an object with public information about the project

Properties: -id -ref

Node List

player.data.nodes: Array

Returns an array of objects containing information about all nodes in the project.

Properties: -id -ref -xref -name

console.table(player.data.nodes)

player.data.videos: Array

Returns an array of objects containing information about all videos in the project.

Properties: -id -ref -xref -name

console.table(player.data.videos)

Current Time

player.currentTime: Number

Returns the current time of the video being played.

Duration

player.duration: Number

Returns the duration of the current video being played.

Current Node

player.currentNode: Object

Returns an object with information on the current node.* Properties: -id -ref -xref -name

Current Video

player.currentVideo: Object

Returns and object with information on the current video.

Properties: -id -ref -xref -name

Current Volume

player.volume: Number 0.0-1.0

Returns the current volume of the player, notated by a number. The volume can also be set: player.volume = 1. This is an asynchronous operation that may not be reflected immediately and may not be supported on all devices.

Muted

player.muted: Boolean

Returns a boolean indicating whether or not the player is currently muted. The muted flag can also be set: player.muted = true. This is an asynchronous operation that may not be reflected immediately and may not be supported on all devices.

Playback Rate

player.playbackRate: Number

Returns the playback rate. The playback rate can also be set: player.playbackRate = 2. This is an asynchronous operation that may not be reflected immediately and may not be supported on all devices.

Ready State

player.readyState: Number

Returns a number indicating the state of the player. Where:

0 indicates nothing
1 indicates the API is ready
2 indicates the project is loading
3 indicates the project is ready

Commands

Commands can be passed to the player object to control different aspects of the player experience, including playing or pausing the video, and jumping to a specific point in the project.

Commands are represented as an object with both type and payload properties, and can be passed using player.execute(commandType), or by using the helper function available for most commands.

Jump to Node

Jumps to a specific node in the project. Accepts autoplay as a boolean. When set to true, the video will play automatically after the new node is loaded. If not included, autoplay is true by default.

Helper method: player.jump(destination, autoplay = true)
Command type: project:jump
Command payload: destination*

*Destination is a locator for a specific node in a project. A locator is an object with a single key-value pair referencing a given node and take the following form: { [id|name|ref|xref]: "[value]" }. e.g. { name: "Start" }; where id is the id of the node, name is the name of the node, ref is the reference of the node, and xref is the external reference of the node provided by the Composer API. The id and ref of the node are not static, and will change each time the project is republished.

Replay

Replay the project from the beginning.

Helper method: player.replay()
Command type: project:replay

Play

Begin playback on the project.

Helper method: player.play()
Command type: player:play

Pause

Pause playback on the project.

Helper method: player.pause()
Command type: player:pause

Seek

Seek to a new point in the current video.

Helper method: player.seek(time)
Command type: player:seek
Command payload: time, where time is number indicating the desired playback time to seek to.

Events

Events are published from the player and can be subscribed to in order to extend the interactive experience or inform analytics services. Every event is an object with type and payload properties. You can listen for all event types or just one specific type. The payload property will return information about the project, it’s current state, and, depending on the event, custom data fed from fields in the Rapt Media composer.

Example

player.on('event', (evt) => {
  switch (evt.type) {
    case 'project:load':
    console.log('loaded');
    break;
  }
});
// OR
player.on('project:load', (evt) => {
  console.log('project:load');
});

project:load

A new project is loading. Project data will not be available.

project:ready

A new project has been loaded.

project:start

The project has started. Triggered on the first media play event of a given play through (will re-trigger on replay’s).

project:ended

The project has reached the end of a given branching structure.

project:replay

The project is being reset for replay.

project:unload

The project has been unloaded.

project:reset

The project has been reset to the beginning.

node:enter

A new node has been loaded.

node:exit

The current node will be unloaded.

node:ended

The current node has ended.

hotspot:click

The user has clicked on a hotspot.

browser:open

The project has opened a new window.

browser:hidden

The browser window has been hidden. The interactive video will be paused.

cue:forward

Playback has crossed over a cue point. Cue points are custom api events that can be added using the Rapt Media composer by entering the node editor and turning on the api event timeline. Custom data can be added to each cue point and is passed through in the payloadproperty.

cue:reverse

Playback has reversed passed a cue point. Cue points are custom api events that can be added using the Rapt Media composer by entering the node editor and turning on the api event timeline. Custom data can be added to each cue point and is passed through in the payload property.

player:play

The current video has started playing.

player:pause

The current video has been paused.

player:progress

The playhead has crossed a predefined progress point. Event fires at 25%, 50%, 75% and 98% of every node.

Example

Overview

Using the events and commands above, let’s build out a quiz based interactive video that assigns individuals a score based on their answers, and serves different final content to these users based on their performance.

Building the project

To start, let’s create a simple interactive quizzing structure inside of the Rapt Media composer. The project will need two end nodes, one for those who score 66% or above (pass) and one for those who score under (fail). For information on how to use the composer, see our Getting Started section.

Each one of the ‘Question’ nodes in the project has 1 correct and 2 incorrect answers. When a user presses the hotspot that corresponds to the correct answer, we want to increment their score by 1. If a user clicks a hotspot that corresponds to an incorrect answer, their score does not change. We can pass these values through by adding them into the api event fields of each hotspot. We’ll add 1 to each correct hotspot in the project, and 0 for each incorrect answer.

After updating all applicable hotspots, you can publish the project.

Using the API

Now, we’ll leverage the API to dynamically add the project to the page, register the project with the API, and add the scoring functionality and logic to serve the viewer the appropriate end node.

To start, let’s set up our page and launch the project. You’ll need the URL ID of the project, which can be found in the embed code in the distribution pane of the composer.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
  var player = new Rapt.Player({
    target: 'target',
    project: '[URL ID]',
  });
</script>

Since this is a simple example, we’ll add the rest of our JS to the same page. First, we’ll need to set our totalScore variable. This will be the variable we increment as users choose a correct answer. We’ll also want to set up our player.on listener and switch statement, so we can listen for specific events coming out of the player.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var totalScore = 0;
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]'
});
player.on('event', (evt) => {
  switch (evt.type) {
  }
});
</script>

Next, we’ll want to parse the evt object and look for our desired Rapt event. In this case, we want to know that a user clicked a hotspot, so using a switch statement, we’ll look at the typeattribute of the event object for hotspot:click.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var totalScore = 0;
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]'
});
player.on('event', (evt) => {
  switch (evt.type) {
    case 'hotspot:click':
      //score increment logic goes here
      break;
  }
});
</script>

Now that we have our switch statement in place, we’ll want to parse the payload every time a hotspot is clicked to find the score being passed through. Since the only information entered into the API event data field in the composer is related to scoring, we can simply check to see if the data exists, and if it does, add it to our score variable. Data is passed through as a string, so we’ll need to change it to an integer first.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var totalScore = 0;
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]'
});
player.on('event', (evt) => {
  switch (evt.type) {
    case 'hotspot:click':
      if(evt.payload.hotspot.customData){
        var score = parseInt(evt.payload.hotspot.customData);
        totalScore += score;
      }
      break;
  }
});
</script>

Now the totalScore variable will increment every time a user clicks a correct hotspot.

The second piece of this functionality involves jumping to a specific node based on the value of totalScore at the end of the quiz. If you look at the project structure in the composer, you’ll notice that the two endings are detached from the main project, and that the correct and incorrect nodes for question 3 do not have any other branches leading out from them. This means that the project:end event will fire at the end of both the 3-Correct and 3-Incorrect nodes. We can use this event to jump to the actual final nodes.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var totalScore = 0;
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]'
});
player.on('event', (evt) => {
  switch (evt.type) {
    case 'hotspot:click':
      if(evt.payload.hotspot.customData){
        var score = parseInt(evt.payload.hotspot.customData);
        totalScore += score;
      }
      break;
    case 'project:ended':
      // logic to jump to appropriate end node goes here
      break;
  }
});
</script>

When the project:ended event is published, we’ll want to check our totalScore and send users who answered 66% or higher to the ‘Pass’ node. Users who fall below that should be sent to the ‘Fail’ node. We can use the command project:jump along with a locator to jump to a specific node by name.

<div id="target" style="width: 600px; height: 400px"></div>
<script src="https://cdn1.raptmedia.com/system/player/v1/api.min.js"></script>
<script>
var totalScore = 0;
var player = new Rapt.Player({
  target: 'target',
  project: '[URL ID]'
});
player.on('event', (evt) => {
  switch (evt.type) {
    case 'hotspot:click':
      if(evt.payload.hotspot.customData){
        var score = parseInt(evt.payload.hotspot.customData);
        totalScore += score;
      }
      break;
    case 'project:ended':
      if(totalScore >= 2){
        player.jump({name: "Pass"});
      } else {
        player.jump({name: "Fail"});
      }
      break;
  }
});
</script>

Using the hotspot:click and project:ended events with a little bit of logic, we’ve created a personalized quiz experience where users receive end content related to their score. We could use this framework to do similar things, such as read data or cookies available on the page and serve different parts of an experience based on what we know about a user.

Overview

Initialization

Player Information

Rapt Account Metadata

Project Metadata

Revision Metadata

Node List

Video List

Current Time

Duration

Current Node

Current Video

Current Volume

Muted

Playback Rate

Ready State

Commands

Jump to Node

Replay

Play

Pause

Seek

Events

project:load

project:ready

project:start

project:ended

project:replay

project:unload

project:reset

node:enter

node:exit

node:ended

hotspot:click

browser:open

browser:hidden

cue:forward

cue:reverse

player:play

player:pause

player:progress

Example

Overview

Building the project

Using the API