Using JavaScript with the Flash-only Player API

This document walks you through the steps required to publish a Video Cloud player in an HTML page and begin interacting with it using the Flash-only Player API. Video Cloud exposes a API in JavaScript for Flash players, so all you need is a text editor and web browser to work with it.

Note that the Flash-only Player API works only when the player is loaded in Flash mode. Unless you need specific functionality that is only available in this API, you should use the Smart Player API instead.

This document addresses solutions for the Flash version of the Video Cloud player. Video Cloud supports two APIs for developing customizations and dynamic solutions for their players: the Flash-only Player API, for solutions for Video Cloud Flash players, and the Smart Player API for solutions for smart players, those players that serve Flash versions of the Video Cloud player where supported, and otherwise serve HTML versions. For a reference to the methods and events for coding Flash players only, use the Flash-Only Player API Reference. For more on creating dynamic solutions for smart players, see Using the Smart Player API.

By understanding how to interact with your Video Cloud Flash player with the Flash-only Player API, you can programmatically control the look and feel of your viewers' video experience. This document assumes you understand how to work with JavaScript in general. If you're not already familiar with the Flash-only Player API, read Getting Started with the Flash-Only Player API. The Flash-Only Player API Reference lists all of the methods and events for each component available in the player.

In this document, you'll learn about:

Getting the publishing code

In Publishing a Video Cloud Player, download the code to embed a player from the Video Cloud Studio Publishing module. Since you are embedding in an HTML page, copy and paste the JavaScript code below into an HTML page anywhere between the <body> tags.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
       "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
      
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Player API HTML Test </title>
</head>
<body>
<!-- Start of Brightcove Player -->
    <div style="display:none">
    </div>
    <!--
    By use of this code snippet, I agree to the Brightcove Publisher T and C 
    found at http://corp.brightcove.com/legal/terms_publisher.cfm. 
    -->
<script language="JavaScript" type="text/javascript" 
        src="http://admin.brightcove.com/js/BrightcoveExperiences.js"></script>
<script src="http://admin.brightcove.com/js/APIModules_all.js"> </script> 
 
 <object id="myExperience" class="BrightcoveExperience">
    <param name="bgcolor" value="#FFFFFF" />
    <param name="width" value="966" />
    <param name="height" value="546" />
    <param name="playerID" value="12000045388" />
    <param name="publisherID" value="18786002"/>
    <param name="isVid" value="true" />
    <param name="isUI" value="true" />
    <param name="@playlistTabs" value="276897321, 12000044025" />
 </object>
<!-- End of Brightcove Player -->
</body>
</html>

Enabling the APIs

To ensure that all the classes necessary are loaded with the player, your player publishing code must include a reference to the APIModules_all.js file on the Video Cloud servers. Copy and paste this code into your document as well.

<script src="http://admin.brightcove.com/js/APIModules_all.js"> </script> 

This line does not get added to the player publishing code automatically, even if you have selected "Enable ActionScript/JavaScript APIs" for the player in the Publishing module.

Assigning content

You can assign content directly in the publishing code. Depending on the player you're using, you can assign either a single video or one or more playlists to be loaded and displayed with the player upon starting. The publishing code above shows multiple playlists being provisioned. The following code shows how you specify content:

// for a single video in a Single Video template:
    <param name="@videoPlayer" value="123456" />
 
// for a single video, using its reference ID:
    <param name="@videoPlayer"  value="ref:myVid12345" />
 
// for one playlist in a multi-playlist template:
    <param name="@playlistTabs" value="123456" />
 
// for multiple playlists:
    <param name="@playlistTabs" value="123456, 7891011" />

For more examples of assigning content in the publishing code, see Assigning Content to Flash Players Programmatically and Designating Featured Content in Flash Players.

Getting references to components

The onTemplateLoaded event only tells you that the player has loaded and the sub-elements are ready for you to interact with them via the Flash-only Player API. To go further, you need to get references to the components you want to work with. Place your onTemplateLoaded function within a script block within the <head> section of the page so that as the player loads, it automatically calls the function:

<script type="text/javascript">
var bcExp;
var modVP;
var modExp;
var modCon;
 
// called when template loads, this function stores a reference to the player and modules.
function onTemplateLoaded(experienceID) {
 
    bcExp = brightcove.getExperience(experienceID);
 
    modVP = bcExp.getModule(APIModules.VIDEO_PLAYER);
    modExp = bcExp.getModule(APIModules.EXPERIENCE);
    modCon = bcExp.getModule(APIModules.CONTENT);
}
</script>

You can access the modules using their constant values or string names. In this example, we're getting a reference to the VideoPlayer module, whose APIs we can use to load and play videos and get playback status and events. The list of constants is in the Flash-only Player API Reference under the APIModules class definition.

Loading content

Content loading is performed by making calls to the Content module APIs. The player loads with the content programmed to it. You can retrieve this content synchronously by using the getMedia method. If you want to retrieve content from the database that hasn't yet been loaded into the player, you must make an asynchronous call since the database lookup takes a finite amount of time and you don't want to block your application until it returns. In this case, use the getMediaAsynch method. The same rules apply to playlists.

The following example shows how to get the video currently loaded into the player, and then retrieve another one:

<script type="text/javascript">

var bcExp;

var modVP; var modExp; var modCon; // called when template loads, this function stores a reference to the player and modules. // Then event listeners will be added for when the template is ready and when a user // clicks on a video. function onTemplateLoaded(experienceID) { alert("EVENT: TEMPLATE_LOAD"); bcExp = brightcove.getExperience(experienceID); modVP = bcExp.getModule(APIModules.VIDEO_PLAYER); modExp = bcExp.getModule(APIModules.EXPERIENCE); modCon = bcExp.getModule(APIModules.CONTENT); modExp.addEventListener(BCExperienceEvent.TEMPLATE_READY, onTemplateReady); modExp.addEventListener(BCExperienceEvent.MEDIA_LOAD, onContentLoad); modCon.addEventListener(BCContentEvent.VIDEO_LOAD, onVideoLoad); } function onTemplateReady(evt) { alert("EVENT: TEMPLATE_READY"); } function onContentLoad(evt) { alert("EVENT: MEDIA_LOAD"); var currentVideo = modVP.getCurrentVideo(); alert("INFO: Currently Loaded videoID: " + currentVideo.id); modCon.getMediaAsynch(1488633950); } function onVideoLoad(evt) { alert("EVENT: VIDEO_LOAD"); // Play video that was just loaded modVP.loadVideo(evt.video.id); } </script>

Listening for user interaction events

The Flash-only Player API can tell you when viewers perform specific actions in the player, like sending an e-mail to a friend. You can capture these events and send them to your analytics back end with simple event listeners:

<script type="text/javascript">
 
var bcExp;
var modMenu;
 
function onTemplateLoaded(experienceID) {
	alert("EVENT: TEMPLATE_LOAD");
	
	bcExp = brightcove.getExperience(experienceID);
	modMenu = bcExp.getModule(APIModules.MENU);
	modMenu.addEventListener(BCMenuEvent.SEND_EMAIL_CLICK, onEmailSent);
		
}
 
function onEmailSent(evt) {
	alert("An Email was sent!");	
}
</script>

Be careful when you define event listeners. In JavaScript, if you add an event listener for an event, but don't add a function to handle that event, it will prevent any subsequent event listeners from being registered. For instance, if you have this:

content.addEventListener(BCContentEvent.VIDEO_LOAD, onVideoLoad);
content.addEventListener(BCContentEvent.PLAYLIST_LOAD, onPlaylistLoad);

But you haven't defined onVideoLoad anywhere, when you call getPlaylistAsynch(), the playlistLoad event never fires, and you get no error or other feedback.

Debugging

The Video Cloud Debugger utility can help you debug your custom code. You can use the experienceModule.debug() method to create custom debug messages that will show up in the Debugger utility.

Additional resources

The following references will help you learn about the Flash-only Player API

Post new comment

The content of this field is kept private and will not be shown publicly.
0

Comments