This document will walk you through the steps required to publish a Brightcove player in HTML and begin interacting with it using the Player API. Brightcove exposes an API in JavaScript, so all you need is a text editor and web browser to work with it. This document assumes you understand how to work with JavaScript in general.
Grab the code to embed a player from the Brightcove Studio Publishing module. Since we're embedding in HTML, you want to get the JavaScript code. Paste the code 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>
To make sure all the classes necessary are loaded with the player, the player publishing code must include a reference to the APIModules_all.js file on Brightcove's servers:
<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.
Content can be assigned 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 on startup. The publishing code above shows multiple playlists being provisioned. Here's 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 Players Programmatically and Designating Featured Content in Players.
The onTemplateLoaded event tells you only that the player has loaded and its sub-elements are ready to be interacted with via the 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 in the <head> section of the page, so it automatically gets called as the player loads:
<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 Player API Reference under the APIModules class definition.
Content loading is performed by making calls to the Content module APIs. The player will load with the content programmed to it. This content can be retrieved synchronously 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, you would use the getMediaAsynch method. The same rules apply to playlists.
Here's an example of getting the video currently loaded into the player, and then retrieving 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.CONTENT_LOAD, onContentLoad); modCon.addEventListener(BCContentEvent.VIDEO_LOAD, onVideoLoad); } function onTemplateReady(evt) { alert("EVENT: TEMPLATE_READY"); } function onContentLoad(evt) { alert("EVENT: CONTENT_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>
The Player API can tell you when users perform specific actions in the player, like sending off an email to a friend. You can capture these events and send them to your analytics backend 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 onVideoLoad isn't defined anywhere, when you call getPlaylistAsynch(), the playlistLoad event never fires, and you get no error or other feedback.
The Brightcove 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.