This is the documentation for our legacy API. If you have opted into our new player, you can find the updated API documentation here.

Overview

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

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 brand’s 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.

Quickstart

This section is intended to get your project integrated and running with the Rapt Media Player API as quickly as possible. This is intended for readers who have at least a basic understanding of JavaScript and web programming.

Source code

Source code is distributed via JavaScript file that you should include in your markup. We recommend referencing the current version from our CDN:

<script src="https://cdn1.raptmedia.com/system/scripts/api.v2.min.js.gz"></script>

Alternate versions of the API are available to suit your needs:

  • api.v2.nojq.min.js – does not include a namespace-safe version of jQuery and relies on you supplying one. Note: the Rapt Media API was written to be compatible with jQuery 1.11.1.
  • api.v2.jq.min.js – includes a non-namespace-safe jQuery so you don’t have to provide one yourself.

Additionally, all the above versions have a gzipped version which simply have a ‘.gz’ extension at the end.

Hello Rapt!

Before jumping into basic examples of usage for the API, it is important to understand the intialization steps that the player API must go through to allow communication with the player.

The basic requirement is that the expected playback iframe be registered with the Rapt player API before making requests to the player through the API commands. By default, all iframes already on the DOM during page initialization are registered by the Rapt API. In more complicated workflows with dynamic iframes or multiple iframes, extra steps may be needed.

The following example is for the most common API usage example, with other code samples for the more complicated workflows in the advanced intialization section.

<!DOCTYPE html>
<html>
  <head>
    <title>Hello Rapt!</title>
    <script src="http://code.jquery.com/jquery-1.11.1.js"></script>
    <script src="https://cdn1.raptmedia.com/system/scripts/api.v2.min.js.gz"></script>
  </head>
  <body>
    <iframe name="hello-rapt" 
    src="http://cdn1.raptmedia.com/projects/YOUR_PROJECT_SHARE_ID/embed?autoplay=false&controls=overlay" 
    width=720 height=405 scrolling=no frameborder=0 marginheight=0 marginwidth=0 
    webkitallowfullscreen=true mozallowfullscreen=true allowfullscreen=true>
    Iframes are required to view this content</iframe>
    <script type="text/javascript">
      raptor.api.on("ready", function(event, frame){
        frame.onload = function(){
          raptor.api.launch(frame.name);
        }
      });
      raptor.api.on("inboundReady", function(event, data){
        console.log("inbound commands ready");
      });
    </script>
  </body>
</html>

The above example creates a Rapt Media embedded video player and prepares the video player to communicate via the API.

A few items to note:

  1. Include the Rapt Media Player API via the script tag in the head of the document. (We also include jQuery for simplicity of subsequent examples)

  2. Create an iframe tag embedding your project in the body of the document. (The same tag that is provided in your Rapt Media publishing panel for a project)

  3. Upon loading the document, the API registers a collection of the iframe tags available on the page and then triggers a “ready” event for each iframe tag present.

  4. In the “ready” event handler, the response “el” is a reference to the iframe that is being triggered as “ready”. In our example, we are setting an onload handler for the iframe to “launch” the API. “Launch” will wrap a few initialization steps for the developer, including: setting the default framename (since this page only has one Rapt player present), and automatically calling the raptor.api.load() method which readies the Rapt player for playback.

  5. After the specified player frame is launched, “inboundReady”, will be sent from the API signaling that the player is initialized and ready to accept further API commands.

Advanced intialization

In some unique cases, the developer may have constraints that do not allow the Rapt player iframe embed to be present on the DOM during page initialization. For example: with other player integrations or websites/applications with more interactive interfaces, it may be neccessary to create the Rapt embed iframe at runtime instead of intialization.

The following examples highlight two common alternatives for handling the situation described above.

Initialize frame manually

<!DOCTYPE html>
<html>
  <head>
    <title>Hello Rapt!</title>
    <script src="http://code.jquery.com/jquery-1.11.1.js"></script>
    <script src="https://cdn1.raptmedia.com/system/scripts/api.v2.min.js.gz"></script>
  </head>
  <body>
    <div id="player-container"></div>
    <script type="text/javascript">
      var playerFrame = document.createElement("iframe");
      playerFrame.setAttribute("src", "http://cdn1.raptmedia.com/projects/YOUR_PROJECT_SHARE_ID/embed?autoplay=false&controls=overlay");
      playerFrame.width = 720;
      playerFrame.height = 405;
      playerFrame.name = "dynamicPlayerFrame";
      playerFrame.onload = function(){ raptor.api.launch(playerFrame.name) };
      $("#player_container").append(playerFrame);
      raptor.api.initByIframe(playerFrame);
      raptor.api.on("inboundReady", function(event, data){
        console.log("inbound commands ready");
      });
    </script>
  </body>
</html>

The above snippet appends an iframe to the DOM after it has already been loaded, then registers the iframe with the Rapt API.

A few items to note:

  1. It is important that the iframe name attribute is set BEFORE the iframe is appended to the page. It is important that iframe names are not changed after they have been loaded into the DOM, to ensure the browser’s “window.frames” collection has the correct frame name as an index.

  2. The “raptor.api.initByIframe” method registers the newly added iframe with the player API. This method expects an object/element reference to an iframe.

Initialize frame via project

<!DOCTYPE html>
<html>
  <head>
    <title>Hello Rapt!</title>
    <script src="http://code.jquery.com/jquery-1.11.1.js"></script>
    <script src="https://cdn1.raptmedia.com/system/scripts/api.v2.min.js.gz"></script>
  </head>
  <body>
    <div id="player-container"></div>
    <script type="text/javascript">
      raptor.api.initByProject("#player_container", "YOUR_PROJECT_URL_ID", {
        name: "dynamicPlayerFrame",
        params: {},
        secure: true, 
        onload: function(){ raptor.api.launch("dynamicPlayerFrame")}
      });
      raptor.api.on("inboundReady", function(event, data){
        console.log("inbound commands ready");
      });
    </script>
  </body>
</html>

The above snippet uses the Rapt API to intialize and append a player iframe that is already registered with the API.

A few items to note:

  1. The “raptor.api.initByProject” method expects an element selector, project URL ID, and attributes that an iframe would normally expect (eg: onload, name, fullscreen, etc).

  2. Setting secure: true serves the project over https

  3. URL parameters can be passed in through the params object. Options include:

    • controls: overlay(default) - sets the controls to display over the bottom of the video
    • controls: below - sets the controls to display under the video
    • autoplay: false (default) - sets the video to require user action to begin playback
    • autoplay: true - sets the video to automatically play on desktop devices
    • no_controls: true - sets the controls to hidden

Player interaction

Now that our player is initialized, we can fire off API commands and listen for events in order to create our own custom interactive/site-pairing experiences. The possibilities here are somewhat endless, and this section will aim to describe the basics of player interaction so you can dream up your own creative use of the Rapt Media platform.

The main communication between your app and the Rapt Media Player happens through two main concepts, which are analogous to a typical JavaScript-based plugin:

  1. Functions that communicate messages to the player or return status about the player.

  2. Events that report back on current playback and custom timed/user-driven events.

The video player is largely driven by calling functions on the raptor.api object that we referenced in the previous example. Generally, these functions require no arguments assuming a default iframe has already been set.*

For the following example, let’s assume we are building a super cool, innovative shopping experience that plays specific video nodes based on what item is currently selected on our online catalog:

var selectedRaptNode;
//Start node playback when item is clicked
$(“.shopping-list-item”).on(“click”, function(){
    selectedRaptNode = $(this).data(“node”);
    raptor.api.setNode(selectedRaptNode);
    raptor.api.play();
});

But we can’t stop there; let’s make our experience even more valuable for our shopper and give them a coupon code for reaching the end of the video to reward them for their commitment to product discovery!

//Display custom coupon code for reaching the end of the current product video
raptor.api.on(“clipEnd”, function(event, data){
    if (raptor.api.state().id == selectedRaptNode){
        $(“#innovative-coupon-display”).text(generateSweetCouponCode());
    }
});

We could also improve our example by instantiating the on “clipEnd” handler during the click event and removing the handler with raptor.api.off. Although simplistic in nature, we hope these examples shed light on the type of site-pairing that can be accomplished with our API.

*The methods will also accept a frame name should you not have the “defaultIFrame” set to a value. This would be useful where you have multiple video player embed frames on one page.

Methods

function raptor.settings(settingName, value)

Arguments

  • settingName: required
    • Currently the only setting needed is “defaultIFrame,” which defaults all other function calls to the default iframe once set
  • value: required
    • String or iframe object to be set as the default iframe

Description

Method handles configuration of settings for the API.

This function is depreciated and can be ignored when using any of the initialization methods outlined earlier in this documentation.

Example

<script type="text/javascript">
  raptor.api.on("ready", function(event, frame){
    raptor.settings("defaultIFrame", frame.name)
  });
</script>

function raptor.api.load(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to call the load action on. Optional unless default iframe not set

Description

Method loads the Rapt Media Player on behalf of the user, counting as a play. Useful for when the project state needs to be initialized a certain way and autoplay or a user simply clicking the play button is inadequate.

This function is depreciated and can be ignored when using any of the initialization methods outlined earlier in this documentation.

Example

<script type="text/javascript">
  raptor.api.on("ready", function(event, frame){
    raptor.settings("defaultIFrame", frame.name)
    raptor.api.load()
  });
</script>

function raptor.api.initByIframe(iframe)

Arguments

  • iframe: required
    • Should be an JS object referencing the iframe element you want to initialize.

Description

Method is used for registering a Rapt Media embed iframe that has been loaded dynamically after page load.

Example

<script type="text/javascript">
  var playerFrame = document.createElement("iframe");
  playerFrame.setAttribute("src", "http://cdn1.raptmedia.com/projects/YOUR_PROJECT_SHARE_ID/embed?autoplay=false&controls=overlay");
  playerFrame.width = 720;
  playerFrame.height = 405;
  playerFrame.name = "dynamicPlayerFrame";
  playerFrame.onload = function(){ raptor.api.launch(playerFrame.name) };
  $("#player_container").append(playerFrame);
  raptor.api.initByIframe(playerFrame);
</script>

function raptor.api.initByProject(selector, urlId, options)

Arguments

  • selector: required
    • Should be a string representing a jQuery valid element selector.
  • urlId: required
    • Should be a string representing the URL ID for your project.
  • options: optional
    • A JSON object with key value pairs representing expected iframe options (such as: name, onload, width, height) with more granular attributes such as fullscreen, marginheight, frameborder, etc, nested in an “attributes” key.

Description

Method is used for initializing and registering a new Rapt Media embed iframe using a project URL ID.

Example

<script type="text/javascript">
  raptor.api.initByProject("#selector", "YOUR_PROJECT_URL_ID", {
    name: "dynamicPlayerFrame",
    onload: function(){ raptor.api.launch("dynamicPlayerFrame")}
  });
</script>

function raptor.api.play(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to call the play action on. Optional unless default iframe not set

Description

Method starts playback of current media/node for the Rapt Media Player.

Example

<script type="text/javascript">
  raptor.api.play()
</script>

function raptor.api.pause(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to call the pause action on. Optional unless default iframe not setVolume

Description

Method pauses playback of current media/node for the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.pause()
</script>

function raptor.api.setVolume(data, frameName)

Arguments

  • data: required
    • Float representing volume level, 0.00 - 1.00
  • frameName: optional
    • String that represents name of frame to call the setVolume action. Optional unless default iframe not set

Description

Method sets the volume for the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setVolume(1.00)
</script>

function raptor.api.setMute(data, frameName)

Arguments

  • data: required
    • Boolean value representing mute state, true/false
  • frameName: optional
    • String that represents name of frame to call the setMute action. Optional unless default iframe not set

Description

Method handles muting for the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setMute(true)
</script>

function raptor.api.setTime(data, frameName)

Arguments

  • data: required
    • Float value representing desired playback time (in seconds) for current media/node
  • frameName: optional
    • String that represents name of frame to call the setTime action on. Optional unless default iframe not set

Description

Method sets player to desired playback time for current media/node for the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setTime(42.0)
</script>

function raptor.api.setTimePercentage(data, frameName)

Arguments

  • data: required
    • Float representing desired percentage of current playback time for current media/node, 0.00 - 1.00
  • frameName: optional
    • String that represents name of frame to call setTimePercentage action on, Optional unless default iframe not set

Description

Method sets player to desired playback time based on given percentage of playback for current media/node for the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setTimePercentage(0.75)
</script>

function raptor.api.prefetchNode(data, frameName)

Arguments

  • data: required
    • String representing desired Node ID to be pre-loaded in the Rapt Media Player
  • frameName: optional
    • String that represents name of frame to call the prefetchNode action on. Optional unless default iframe not set

Description

Method handles preloading of media for a desired node. For example, normal project structures for a Rapt Media Project would have nodes laid out in a way that media is constantly being pre-loaded for the next node. When using more complicated API implementations, with a nontraditional project structure, you may need to make use of prefetchNode before calling setNode. This will avoid interruptions in the user experience waiting on new node media to load.

Example

<script type="text/javascript">
  raptor.api.prefetchNode("12321")
</script>

function raptor.api.prefetchNodeByName(data, frameName)

Arguments

  • data: required
    • String representing desired Node Name to be pre-loaded in the Rapt Media Player
  • frameName: optional
    • String that represents name of frame to call the prefetchNodeByName action on. Optional unless default iframe not set

Description

Method handles preloading of media for a desired node. See previous function for more details. This method finds the first matching Node with the given name.

Example

<script type="text/javascript">
  raptor.api.prefetchNodeByName("Node 3")
</script>

function raptor.api.setNode(data, frameName)

Arguments

  • data: required
    • String representing desired Node ID to be loaded in the Rapt Media Player
  • frameName: optional
    • String that represents name of frame to call the setNode action on. Optional unless default iframe not set

Description

Method handles loading desired media/node as the current media in the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setNode("12321")
</script>

function raptor.api.setNodeByName(data, frameName)

Arguments

  • data: required
    • String representing desired Node Name to be loaded in the Rapt Media Player
  • frameName: optional
    • String that represents name of frame to call the setNodeByName action on. Optional unless default iframe not set

Description

Method handles loading desired media/node as the current media in the Rapt Media Player. This method finds the first matching Node with the given name.

Example

<script type="text/javascript">
  raptor.api.setNodeByName("Node 3")
</script>

function raptor.api.ccTracks(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to call the ccTracks action on. Optional unless default iframe not set

Description

Method returns array of currently available closed caption tracks for current player.

Example

<script type="text/javascript">
  raptor.api.ccTracks()
  //returns ["en", "ru", "es"]
</script>

function raptor.api.setTrack(data, frameName)

Arguments

  • data: required
    • String representing desired closed-caption state. String must be a valid language code that is available to the current player (see: api.ccTracks). Passing “hide” to the function will turn off closed captioning for current player
  • frameName: optional
    • String that represents name of frame to call the setTrack action on. Optional unless default iframe not set

Description

Method handles setting active closed caption for current media in the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.setTrack("en"); //for english captions
  raptor.api.setTrack("hide"); //for no captions
</script>

function raptor.api.isReady(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to get the ready state of. Optional unless default iframe not set

Description

Method returns Boolean value representing if the API is ready to communicate with the Rapt Media Player

Example

<script type="text/javascript">
  raptor.api.isReady()
</script>

function raptor.api.state(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to get the current state of. Optional unless default iframe not set

Description

Method returns JSON object representing current state and current node of the player.

Example

<script type="text/javascript">
  raptor.api.state()
  //returns 
  // {
  //    duration: 5.056,
  //    id: 66,
  //    isStart: false,
  //    isTerminal: true,
  //    muted: false,
  //    name: "Node 5",
  //    progressPercentage: 100,
  //    progressTime: 5.056,
  //    volume: 1
  // }
</script>

function raptor.api.nodes(frameName)

Arguments

  • frameName: optional
    • String that represents name of frame to return the collection of nodes for the frame given. Optional unless default iframe not set

Description

Method returns hash of node IDs keyed by their names for a given embed frame

Example

<script type="text/javascript">
  raptor.api.nodes()
  //returns {Node 1: "12345", Node X: "12346", Intro Node: "12347"}
</script>

function raptor.api.on(event, callback)

Arguments

  • event: required
    • Desired event to register callback on
  • callback: required
    • Desired callback function to register to the desired event

Description

Method sets callback handler for Rapt Media Player event, see events documentation for specific events that can be triggered

Example

<script type="text/javascript">
  raptor.api.on("EVENT_NAME", function(event, data){
    console.log("event happened: ", event);
  });
</script>

function raptor.api.off(event, callback)

Arguments

  • event: required
    • Desired event to stop listening for
  • callback: required
    • Callback function to match for removing desired event handler

Description

Method removes event listener for specific callback

Example

<script type="text/javascript">
  raptor.api.off("EVENT_NAME", function(event, data){
    console.log("event happened: ", event);
  });
</script>

Events

“button”

Data Payload

  • Returns JSON data for button that was clicked

Description

  • Event fired when Rapt Media button is clicked

“progress”

Data Payload

  • Returns JSON data for media/node progress

Description

  • Event fires on predefined progress quadrants for the currently playing node/media

“userTimed”

Data Payload

  • Returns JSON data for the user-timed API event

Description

  • Event fired for custom API event defined in the Rapt Media project editor. This specific userTimed event is only fired on the first play through of a node

“userTimedRecurring”

Data Payload

  • Returns JSON data for the user-timed API event

Description

  • Event fired for custom API event defined in the Rapt Media project editor. This specific userTimed event is fired on event play through of a node

“userTimedReversing”

Data Payload

  • Returns JSON data for the user timed API event

Description

  • Event fired for custom API event defined in the Rapt project editor. This specific userTimed event is fired when a user is scrubbing backward through a node

“timeUpdate”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired with regularity during playback to notify of player time changes

“play”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player begins playback

“pause”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media pause button is selected

“clipSwitch”

Data Payload

  • Returns JSON data for basic player state and indicates whether new clip is a start clip or terminal clip

Description

  • Event fired when Rapt Media Player switches current media/node

“clipStart”

Data Payload

  • Returns JSON data for basic player state and indicates whether new clip is a start clip or terminal clip

Description

  • Event fired when Rapt Media Player begins playback on new media/node

“clipCanPlay”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player node media has loaded enough data to be able to begin playback

“clipWaiting”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player node media is loading and waiting for more data

“clipSuspended”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player node media loading has suspended

“clipStalled”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player node media loading has stalled unexpectedly

“clipEnd”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player reaches end of media/node

“projectStart”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player starts initial playback on Rapt Media project

“projectEnd”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player reaches a terminal node on Rapt Media project

“volume”

Data Payload

  • Returns JSON data for basic player state, plus volume state

Description

  • Event fired when Rapt Media Player volume is changed

“mute”

Data Payload

  • Returns JSON data for basic player state, plus volume state

Description

  • Event fired when Rapt Media Player is muted

“unmute”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player is unmuted

“fullscreen”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player is toggled to full-screen mode

“windowed”

Data Payload

  • Returns JSON data for basic player state

Description

  • Event fired when Rapt Media Player is toggled back to windowed mode

“error”

Data Payload

  • Returns JSON data for the encountered media error

Description

  • Event fired when Rapt Media Player encounters an HTML5 media error