Rapt Media Player API v2

Size: px

Start display at page:

Download "Rapt Media Player API v2"

Lenard O’Brien’
6 years ago
Views:

1 Rapt Media Player API v2 Overview The Rapt Player API is organized as a JavaScript plugin that, when paired with a Rapt Video project*, allows developers to extend their interactive experiences into their own custom applications or websites. The API handles secure delivery of video playback status, custom events and linkouts, and the ability to manage video playback between your asset and the Rapt Player. With creative use of the API alongside the Rapt 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 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 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 you should include in your markup. We recommend referencing the current version from our CDN: < script src = " ></ 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 API was written to be compatible with jquery 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. Rapt Media Player API v2 1 / 13 November 17th, 2015

2 Hello Rapt! The following is a simple example and description of the various concepts that are important to the Rapt API. <!DOCTYPE html> < html > < head > < title >Hello Rapt!</ title > < script src = " ></ script > </ head > < body > < iframe name = "hello-rapt" src = " ls=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, el){ raptor.settings( "defaultiframe", el.name); el.onload = function (){ raptor.api.load(); } }); raptor.api.on( "inboundready", function (event, data){ console.log( "inbound commands ready" ); }); </ script > </ body > </ html > The above example creates a Rapt embedded video player and prepares the video player to communicate via the API. A few items to note: 1. Declare the correct HTML5 doctype via the <!DOCTYPE html> declaration. 2. Include the Rapt Player API via the script tag in the head of the document. (We also optionally include jquery in order to simplify later player interactions) 3. Create an iframe tag embedding your project in the body of the document. (The same tag that is provided on your Rapt project dashboard) 4. Upon loading the document, the API builds a collection of the iframe tags available on the page and then signals when ready via the ready event 5. Once ready, since there is only one iframe on our page, we set the defaultiframe to the iframe s name and then fire the API command to load the Rapt Video Player once the iframe is fully loaded. 6. Finally, the last event handler in this example, inboundready, is sent from the API once the player is ready for interaction. This would happen by automation with the raptor.api.load call, or by the user having pressed the play button. At this point the API is ready to accept commands. Rapt Media Player API v2 2 / 13 November 17th, 2015

3 Player Interaction Now that our page has been 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 platform. The main communication between your app and the Rapt 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, hopefully 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 a the defaultiframe set to a value. This would be useful where you have multiple video player embed frames on one page. Rapt Media Player API v2 3 / 13 November 17th, 2015

4 Methods function raptor.settings( settingname, value ) 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 Method handles configuration of settings for the API function raptor.api.init( data ) data : required Should be an iframe tag JS object or an object with target and id properties where target is the selector of the div or other markup that you want the project to be loaded in and id is the Rapt Media project embed id. Method is used for either initializing a Rapt Media embed iframe that has been loaded dynamically after page load, or for dynamically generating a Rapt Media embed iframe given a target container and project embed id. function raptor.api.play( framename ) String that represents name of frame to call the play Method starts playback of current media/node for the Rapt Player function raptor.api.pause( framename ) String that represents name of frame to call the pause Method pauses playback of current media/node for the Rapt Player Rapt Media Player API v2 4 / 13 November 17th, 2015

5 function raptor.api.setvolume( data, framename ) data : required Float representing volume level, String that represents name of frame to call the setvolume action on, optional unless default iframe not set Method sets current volume level for the Rapt Player function raptor.api.setmute( data, framename ) data : required Boolean value representing mute state, true/false String that represents name of frame to call the setmute Method handles muting for the Rapt Player function raptor.api.settime( data, framename ) data : required Float value representing desired playback time (in seconds) for current media/node String that represents name of frame to call the settime Method sets player to desired playback time for current media/node for the Rapt Player function raptor.api.settimepercentage( data, framename ) data : required Float representing desired percentage of current playback time for current media/node, String that represents name of frame to call the settimepercentage action on, optional unless default iframe not set Method sets player to desired playback time based on given percentage of playback for current media/node for the Rapt Player Rapt Media Player API v2 5 / 13 November 17th, 2015

6 function raptor.api.prefetchnode(data, framename) data : required String representing desired Node ID to be pre loaded in the Rapt Player String that represents name of frame to call the setnode Method handles preloading of media for a desired node. For example, normal project structures for a Rapt 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 non traditional project structure, you may need to make use of prefechnode prior to calling setnode. This will avoid interruptions in the user experience waiting on new node media to load. function raptor.api.setnode( data, framename ) data : required String representing desired Node ID to be loaded in the Rapt Player String that represents name of frame to call the setnode Method handles loading desired media/node as the current media in the Rapt Player function raptor.api.cctracks(framename) String that represents name of frame to call the setnode Method returns array of currently available Closed Caption tracks for current player. Example: [ en, ru, es ] function raptor.api.settrack(data, framename) Rapt Media Player API v2 6 / 13 November 17th, 2015

7 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 String that represents name of frame to call the setnode Method handles setting active closed caption for current media in the Rapt Player function raptor.api.isready( framename ) String that represents name of frame to get the ready state of, optional unless default iframe not set Method returns Boolean value representing if the API is ready to communicate with the Rapt Player function raptor.api.state( framename ) String that represents name of frame to get the current state of, optional unless default iframe not set Method returns JSON object representing current state of the player. Example: { duration: 5.056, id: 66, isstart: false, isterminal: true, muted: false, name: "Node 5", progresspercentage: 100, progresstime: 5.056, volume: 1 } function raptor.api.nodes( framename ) String that represents name of frame to return the collection of nodes for the frame given, optional unless default iframe not set Rapt Media Player API v2 7 / 13 November 17th, 2015

8 Method returns hash of node IDs keyed by their names for a given embed frame function raptor.api.load( framename ) String that represents name of frame to call the load Method loads the Rapt Player on behalf of the user, counting as a play. Useful for when the project state needs to be initialized a certain way where autoplay or a user simply clicking the play button is inadequate. function raptor.api.on( event, callback ) event : required Desired event (see event docs for possible events) to register callback on callback : required Desired callback function to register to the desired event Method sets callback handler for Rapt Player event function raptor.api.off( event, callback ) event : required Desired event (see event docs for possible events) to stop listening for callback : required Callback function to match for removing desired event handler Method removes event listener for specific callback Rapt Media Player API v2 8 / 13 November 17th, 2015

9 Events button Returns JSON data for button that was clicked Event fired when Rapt media button is clicked progress Returns JSON data for media/node progress Event fired on predefined progress quadrants for the currently playing node/media usertimed Returns JSON data for the user-timed API event Event fired for custom API event defined in the Rapt project editor, this specific usertimed event is only fired on the first play through of a node usertimedrecurring Returns JSON data for the user timed API event Event fired for custom API event defined in the Rapt project editor, this specific usertimed event is fired on every play through of a node usertimedreversing Returns JSON data for the user timed API event Event fired for custom API event defined in the Rapt project editor, this specific usertimed event is fired when a user is scrubbing backwards through a node timeupdate Event fired with regularity during playback to notify of player time changes play Rapt Media Player API v2 9 / 13 November 17th, 2015

10 Event fired when Rapt Player begins playback pause Event fired when Rapt media button is selected clipswitch, and indicates whether new clip is a start clip or terminal clip Event fired when Rapt Player switches current media/node clipstart, and indicates whether new clip is a start clip or terminal clip Event fired when Rapt Player begins playback on new media/node clipcanplay Event fired when Rapt Player node media has loaded enough data to be able to begin playback clipwaiting Event fired when Rapt Player node media is loading and waiting for more data clipsuspended Event fired when Rapt Player node media loading has suspended Rapt Media Player API v2 10 / 13 November 17th, 2015

11 clipstalled Event fired when Rapt Player node media loading has stalled unexpectedly clipend Event fired when Rapt Player reaches end of media/node projectstart Event fired when Rapt Player starts initial playback on Rapt project projectend Event fired when Rapt Player reaches a terminal node on Rapt project volume, plus volume state Event fired when Rapt Player volume is changed mute, plus volume state Event fired when Rapt Player is muted unmute Event fired when Rapt Player is unmuted fullscreen Rapt Media Player API v2 11 / 13 November 17th, 2015

12 Event fired when Rapt Player is toggled to full-screen mode windowed Event fired when Rapt Player is toggled back to windowed mode error Returns JSON data for the encountered MediaError Event fired when Rapt Player encounters an HTML5 media error Rapt Media Player API v2 12 / 13 November 17th, 2015

Tutorials The following section details quick picture tutorials for creating custom site-pairing functionality to be paired with the Rapt API.

earlier in document ) 1) Navigate to the Rapt Editor for your project you desire a custom API event 2) Select the node you wish the API event to occur 3) Once on the node editor

existing site-pairing events. Double click on the timeline to insert a new timed event as shown below.

13 Tutorials The following section details quick picture tutorials for creating custom site-pairing functionality to be paired with the Rapt API. Custom API Events Assuming you have a project with API event permissions enabled, the following steps will create a custom timed API event ( usertimed API event referenced earlier in document ) 1) Navigate to the Rapt Editor for your project you desire a custom API event 2) Select the node you wish the API event to occur 3) Once on the node editor form, select the show Site Pairing events button on the bottom of the form 4) Once clicked, the area will change to a timeline representing the node duration with marks for existing site-pairing events. Double click on the timeline to insert a new timed event as shown below. Custom Button Event Data While a linkout will always fire a button event, they can also pass custom data if desired. When creating a linkout/button, add a custom event name to the linkout editor form in the button behavior editor, like shown below: Rapt Media Player API v2 13 / 13 November 17th, 2015

PLAYER DEVELOPER GUIDE

PLAYER DEVELOPER GUIDE CONTENTS MANAGING PLAYERS IN BACKLOT 5 Player V3 Platform and Browser Support (Deprecated) 5 How Player V3 Works (Deprecated) 6 Setting up Players Using the Backlot REST API (Deprecated)