PLAYER DEVELOPER GUIDE

Transcription

1 PLAYER DEVELOPER GUIDE

2 CONTENTS CREATING AND BRANDING A PLAYER IN BACKLOT 5 Player Platform and Browser Support 5 How Player Works 6 Setting up Players Using the Backlot API 6 Creating a Player Using the REST API 6 Editing a Player Using the REST API 8 Deleting a Player Using the REST API 10 BASIC TUTORIAL FOR THE HTML5 PLAYER 11 Advanced Layout: Embedding Multiple HTML5 Players 14 Creating an HTML5 Player 18 Creating an HTML5 Player with an External Id 19 Advanced Player Management: Destroying an HTML5 Player 20 DESIGNING THE SKIN FOR AN HTML5 PLAYER 24 Customizing an HTML5 Player With CSS 24 Player CSS Class Names 25 Overriding Default Styles with CSS 28 Linking to the CSS 28 Styling the DIV Container with External CSS 29 Referencing the DIV Container by DIV Id 30 Styling a Player with Inline CSS 30 Embedding an HTML5 Player in an HTML iframe 31 PLAYER JAVASCRIPT API PROGRAMMING 33 Advanced JavaScript Examples for Player 33 Loading the Player and Custom Modules in HEAD 33 Organizing the BODY 34 Event Model for HTML5 Player 37 Event Publish and Subscribe 38 Message Bus API 38 Listening to a Message Bus Event 38 Writing to the Message Bus 43 Listening to Multiple Message Bus Events 48 Advanced Event Handling 51 Integrating Ads in HTML5 Players Using JavaScript 52 Assigning Ad Sets Dynamically 52 Assigning an Ad Set with OO.Player.create 52 Assigning Ad Sets with setembedcode 53 Ad-related Events 53 Customizing Assets for HTML5 Player Using JavaScript 53 Programming Bitrates and Buffering for Flash Players Using JavaScript 55 Programming Closed Captioning Using JavaScript 60 Handling Errors for an HTML5 Player Using JavaScript 61 Localizing a Flash or HTML5 Player Using JavaScript 63 Programming Parameters for Player Using JavaScript 65 PLAYER DEVELOPER GUIDE TOC 2 [email protected] OOYALA

3 Query String Parameters 65 Enabling HLS Playback on Android Web 65 Setting Autoplay in a Parameter Hash Tag 66 Setting the Default Video Platform with a Parameter 67 Hiding the Control Bar for Ad Playback in a Parameter Hash Tag 67 Show or Hide Ad Marquee During Ad Playback 68 Adding a TV Rating Watermark to a Flash Player 68 Toggling the Display of Cue Point Markers 71 Player Embedded Parameters 71 Ads Embedded Parameters Overview 71 DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 73 PLAYER FEATURES AND APPS CUSTOMIZATION 78 Player for Cross-Device Resume (XDR) 78 HTML5 Player Apps for Microsoft Windows 8 78 Building a Player App with Win 8 79 Using the Default HTML File 79 Using the Default.js File 80 Using the Player HTML File 81 DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 83 MIGRATING TO PLAYER V3 88 Differences Between Player V3 and Player V2 88 Why HTML5? 89 Comparing Embed Code Styles 89 Migrating an Existing Embed Code 91 Migration FAQ 91 PLAYER DEVELOPER GUIDE TOC 3 [email protected] OOYALA

4 COPYRIGHT NOTICE Copyright Ooyala Ooyala, Backlot, Ooyala Actionable Analytics, the Ooyala logo, and other Ooyala logos and product and service names are trademarks of Ooyala, Inc. ( Ooyala Marks ). Company agrees not to remove any Ooyala Marks that are contained within and/or affixed to the Services as provided to Company. Except with respect to the foregoing, Company agrees not to display or use in any manner the Ooyala Marks without Ooyala s prior written permission. All contents of the Ooyala website and Services are: Copyright Ooyala, Inc. All rights reserved. Ooyala and Backlot are registered trademarks of Ooyala, Inc. in the United States, Japan, and European Community. All rights reserved. For complete information on terms of service, see: All other trademarks are the property of their respective companies. This content was last updated on PLAYER DEVELOPER GUIDE COPYRIGHT NOTICE 4

5 CREATING AND BRANDING A PLAYER IN BACKLOT Describes how to create and brand players in the Backlot UI. Note: The player customizations described in this section only apply to the Flash Player. You can create and brand players using the Backlot UI. PLAYER PLATFORM AND BROWSER SUPPORT The player provides support for Flash playback with HTML5 fallback for a number of platforms. SUPPORTED MOBILE PLATFORMS The following table lists the supported mobile platforms and devices for the HTML5 player. Note: The Flash player is only supported on desktop platforms. Player Support OS Device HTML5 Android 2.3+ Mobile devices (cell/smart phones and tablets) HTML5 ios 7+ On mobile devices (iphone/ipad) Windows 8 phone and tablet support for the HTML5 player will be available in a future release. SUPPORTED BROWSERS The HTML5 player works with the following browsers on all Ooyala supported devices: Browser Chrome Firefox Internet Explorer (8+) Microsoft Edge (Windows 10) Safari Player Support Flash with HTML5 fallback. Flash playback. Flash playback with HTML5 fallback. Note that IE9 does not support true fullscreen format from JavaScript. Fullscreen support is enabled in IE11 and later. Flash with HTML5 fallback. Flash playback with HTML5 fallback. Note: Per the Apple Support Team, Apple has blocked older versions of Flash Player (versions prior to and ) in Safari. Note: For desktop we support only Chrome and Safari. We support HTML5 fallback (not enabled by default) on Chrome, IE9+ and Safari. PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 5

6 HOW PLAYER WORKS The Ooyala player provides a simple way to embed video in web pages. The latest Ooyala Player uses an object-based embed style that works in a similar way as other objectoriented frameworks (like jquery). It differs from how you embed video in web pages using earlier versions of our player (see Comparing Embed Code Styles on page 89). This embed style affects all JavaScript embeds (regardless of whether you use the HTML5 Player or the Flash player). The latest embed style enables you to enclose your player in a type of container using <div> tags. This gives you more control over the placement of your videos on a web page. You can build a page with player building blocks that results in a more responsive-to-change design. For example, if the browser is resized, the player can readily flow on the page to adapt to the resizing. The player also separates the loading of the player from the creation of the player. You can load once and create multiple players based on the original player instance that was loaded. Player loading and creation process works as follows: 1. You specify a player branding id that identifies a particular player to load. 2. The player code is loaded. 3. Any custom modules are loaded. 4. <div> tags are used to create a container for the player and a <div> id is specified. 5. The player is created and initialized with the JavaScript call: OO.Player.create. This call creates a player instance within the <div>. SETTING UP PLAYERS USING THE BACKLOT API You can use the Backlot player branding tools to perform changes to the Ooyala Flash player. Note: This section applies to the Flash and HTML5 Player. Ooyala branding tools enable you to add or remove player functionality, add social sharing features, brand it with your logos, and change color schemes. You can create as many players as you like and make changes to your players at any time. Note: You can completely re-skin the HTML5 player using the Ooyala Player API (JavaScript). Creating a Player Using the REST API You can create as many players as you like and assign them to videos, channels, or channel sets. Backlot displays the player associated with the piece of content that the viewer accesses. For example, if the viewer accesses a video directly, the video is displayed in the video's player. If the customer accesses the same video through a channel, the video is displayed in the channel's player. To create a player: Use the players route. The following example creates a player that uses the default settings, but is set up for social sharing. [POST]/v2/players{ "name":"social Player", "ooyala_branding":{ "show_share_button":true, "twitter_sharing":true, "facebook_sharing":true, PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 6

7 "digg_sharing":true, "url_sharing":true, " _sharing":true Backlot returns a response similar to the following. { "ooyala_branding":{ "show_share_button":true, "twitter_sharing":true, "show_info_screen_homepage_link":true, "show_ad_countdown":true, "show_info_screen_title":true, "facebook_sharing":true, "show_info_button":true, "url_sharing":true, " _sharing":true, "digg_sharing":true, "show_embed_button":true, "show_info_screen_description":false, "show_bitrate_button":false, "show_channel_button":true, "enable_error_screen":true, "show_end_screen_replay_button":true, "accent_color":"#ffbb00", "show_volume_button":true, "name":"social Player", "provider_homepage_url":null, "related_videos":{ "click_behavior":"new_page", "order":"desc", "sort":"upload_time", "source":"shared_labels", "labels":[ ], "is_default":false, "scrubber":{ "image_url":null, "always_show":false, "playback":{ "buffer_on_pause":false, "id":"b4251d1805b46", "default_closed_caption_language":"", "watermark":{ "image_url":null, "click_url":null, "alpha":1.0, "position":"bottom-right" Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 7

8 The player is successfully added. Editing a Player Using the REST API You can edit the look and feel of a player at any time. Any changes are automatically made for all videos, channels, and channel sets that use the player. To edit a player: 1. Perform a get on the players route to view the current configuration. The following example creates a player that uses the default settings, but is set up for social sharing. [GET]/v2/players/b4251d1805b46 Backlot returns a response similar to the following. { "ooyala_branding":{ "show_info_screen_homepage_link":true, "show_share_button":true, "twitter_sharing":true, "show_ad_countdown":true, "show_info_screen_title":true, "url_sharing":true, "facebook_sharing":true, "show_info_button":true, " _sharing":true, "digg_sharing":true, "show_embed_button":true, "show_info_screen_description":false, "show_bitrate_button":false, "show_channel_button":true, "show_end_screen_replay_button":true, "accent_color":"#ffbb00", "enable_error_screen":true, "show_volume_button":true, "name":"social Player", "is_default":false, "provider_homepage_url":null, "related_videos":{ "click_behavior":"new_page", "order":"desc", "sort":"upload_time", "labels":[ ], "source":"shared_labels", "scrubber":{ "always_show":false, "image_url":null, "playback":{ "buffer_on_pause":false, "id":"b4251d1805b46", "watermark":{ "image_url":null, "click_url":null, "alpha":1.0, "position":"bottom-right" PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 8

9 , "default_closed_caption_language":"" Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. 2. Use PATCH with the players route to update the player. The following example disables Digg sharing and changes the accent color to pink. [PATCH]/v2/players/b4251d1805b46{ "ooyala_branding":{ "digg_sharing":false, "accent_color":"#ff1493" Backlot returns a response similar to the following. { "ooyala_branding":{ "show_share_button":true, "twitter_sharing":true, "show_info_screen_homepage_link":true, "show_ad_countdown":true, "show_info_screen_title":true, "facebook_sharing":true, "show_info_button":true, "url_sharing":true, " _sharing":true, "digg_sharing":false, "show_embed_button":true, "show_info_screen_description":false, "show_bitrate_button":false, "show_channel_button":true, "enable_error_screen":true, "show_end_screen_replay_button":true, "accent_color":"#ff1493", "show_volume_button":true, "name":"social Player", "provider_homepage_url":null, "related_videos":{ "click_behavior":"new_page", "order":"desc", "sort":"upload_time", "source":"shared_labels", "labels":[ ], "is_default":false, "scrubber":{ "image_url":null, "always_show":false, "playback":{ "buffer_on_pause":false, "id":"b4251d1805b46", "default_closed_caption_language":"", PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 9

10 "watermark":{ "image_url":null, "click_url":null, "alpha":1.0 Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. The player is successfully edited. Deleting a Player Using the REST API You can delete a player at any time. Any videos, channels, or channel sets that were using the old player automatically revert to the default player. To delete a player: Use delete with the players route. The following example disables deletes the b4251d1805b46 player. [DELETE]/v2/players/b4251d1805b46 Backlot returns a 200 response. Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. For information about using the Scratchpad, see The Scratchpad. The player is successfully deleted. PLAYER DEVELOPER GUIDE CREATING AND BRANDING A PLAYER IN BACKLOT 10

11 BASIC TUTORIAL FOR THE HTML5 PLAYER Use this tutorial to get started using the HTML5 Player. This tutorial helps you begin working with the Ooyala HTML5 Player. You will code an HTML page and add tags containing the logic required to customize, manage, and use the Ooyala player. The recommended structure for building your HTML page is: A DOCTYPE declaration. A head element containing the code to initialize and load the player. A body element containing <div> tags that define presentation and layout, as well as <script> tags that handle player events and data, customize the player, and manage playback of video and related assets. Follow these steps to build a basic HTML page: Step 1: Create a Simple Web Page on page 11 Step 2: Load Your Ooyala V3 Player on page 11 Step 3: Set up the Player Layout in the UI on page 13 Step 4: Create and Embed Your Player on page 13 See Complete Basic Example on page 14 to view the code for the entire web page. STEP 1: CREATE A SIMPLE WEB PAGE Start by creating an empty HTML5 web page. To ensure your page renders properly in all browsers, begin with a <!DOCTYPE html> declaration: <!DOCTYPE html> <html> <head> <title>my Test Player V3 Web Page </title> </head> <body> My Player V3 Content. </body> </html> Note: All HTML5 web pages should have the <!DOCTYPE html> declaration to work properly in all browsers. Windows IE9 is particularly strict and may not render the page properly if this declaration is not included. STEP 2: LOAD YOUR OOYALA V3 PLAYER The head tag is the section of the web page where you load and initialize the Ooyala Player, as well as any custom modules you would like to use. The advantage to loading the player within the head tag is that the player loads before the rest of the web page loads, ensuring it is ready to use by the time the user is able to interact with the player or any of the controls you provide. In this section you will include a <script> tag that makes the request for your player. To get started, you will need a Player ID. The Player ID is an alphanumeric string that uniquely identifies a specific player you will use in your web page. As shown in the following screenshot, you get this Player Id from the Backlot Manage Embed tab. PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 11

12 Within the head tag, create a <script> tag with a src attribute that makes the request to load the player. Replace player_id with the Player ID you retrieved from the Backlot Manage Embed tab: <head> <!-- Load Ooyala Player --> <script src=' </head> For additional information about the player_id with the REST APIs, see Players. Note: You need to load the player only once, even if you plan to create multiple players. You may also specify any third party or custom modules that you would like to load by including additional <script> tags, each having a src attribute specifying a path to a custom module: <head> <!-- Load Ooyala Player --> <script src=' <!-- Load additional custom modules --> <script src='/custom_module_name.js'></script> </head> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 12

13 STEP 3: SET UP THE PLAYER LAYOUT IN THE UI Now you will begin to work within the body element. The first thing you will do is specify the presentation layout for the player using a named <div> element. By default, the player's UI will occupy the entire space provided by the container <div> tags, which you must use to create a container for the player. This allows you to control the position of the player on the screen, and enables the player to adapt to dynamic changes in the site layout. Begin by creating a <div> element that will display the player UI and video screen. The <div> element will need a unique DOM ID, which you specify in its id attribute (playerwrapper in this example). You will use this div id later to reference the loaded player. <body> My Player V3 Content <!-- The DIV elements specify the layout for the content elements. --> <div id='playerwrapper' style='width:480px;height:360px;'></div> </body> Note: The HTML standard requires that each div id must be unique. STEP 4: CREATE AND EMBED YOUR PLAYER Now you can create the player within the body element. Include a <script> tag below the <div> element where you specified the container for the player. Within this <script> tag, you will create the player, associate a video and related assets with the player, and include any embedded parameters (you will learn more about this later). Initially, you need to manually create your video embed code for the player. In the following example, we create a video player and place it in the <div> container identified by the div id playerwrapper. Wrap the call to OO.Player.create() within the OO.ready() method to ensure the script is initialized and loaded. When you call OO.Player.create(), you will pass in the following parameters: The ID of the div element to which to attach the player object. The embed code for the video. Embedded player parameters. These can be used to customize player ads and behavior, and can determine player styles. In this example we set the autoplay parameter to true for ease of use. For more information, see Embedded Parameters. You can also specify Custom Module Embedded Parameters. <script> // Surround everything with OO.ready to make sure the script has // loaded and initialized. OO.ready(function() { window.player = OO.Player.create( 'playerwrapper', 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { // add the embedded player parameters here autoplay: true ); PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 13

14 ); </script> Note: To destroy a player, call the OO.Player.destroy() method. For examples and additional detail, see Advanced JavaScript Examples for Player on page 33. COMPLETE BASIC EXAMPLE You now have a complete working example of a basic web page that loads the Ooyala V3 Player with default settings, renders it according to the layout specified in the <div> container, creates the player, and runs a video: <!DOCTYPE html> <html> <head> <title>my Test Player V3 Web Page </title> <!-- Load Ooyala Player --> <script src=' e18ab1da ea2d8e67fbd'></script> <!-- Load additional custom modules --> <!-- script src='custom_module_name.js'></script> --> </head> <body> My Player V3 Content <!-- The DIV elements specify the layout for the content elements. --> <div id='playerwrapper' style='width:480px;height:360px;'></div> <script> // Surround everything with OO.ready to make sure the script has // loaded and initialized. OO.ready(function() { window.player = OO.Player.create( 'playerwrapper', 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { // add the embedded player parameters here autoplay: true ); ); </script> </body> </html> ADVANCED LAYOUT: EMBEDDING MULTIPLE HTML5 PLAYERS Learn to use advanced layout techniques to embed and present multiple players. Suppose you would like to display multiple players on your web page. You will learn how to use namespaces to load, initialize, and create each player instance, and use <div> tags to specify how they will appear on the screen. PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 14

15 Follow these steps to build your web page: Step 1: Load Multiple Player Instances on page 15 Step 2: Set up the Layout in the UI on page 15 Step 3: Create the Players on page 16 See Complete Example on page 17 to view the code for the entire web page. STEP 1: LOAD MULTIPLE PLAYER INSTANCES To load and initialize multiple players, create a <script> tag for each within the head element for your page. As you learned in Basic Tutorial for the HTML5 Player on page 11, each <script> tag must specify a src attribute that makes the request to load the player. Since you are using multiple players, you will need a way to be able to refer to each one. To do this, you will use a namespace parameter, which allows you to create and use namespaces other than the default OO.Player namespace. For example, if you specify a Player2 namespace when loading the second player, you can create that player by calling Player2.Player.create(). Here is the portion of the web page code that loads and initializes four player instances using namespaces: <head> <title>my Test Player V3 Web Page </title> <!-- Load 4 Ooyala Player Instances --> <!-- The namespace parameter enables you to reference each of these in the create() method calls below. --> <!-- This first instance uses the default OO namespace. To use this instance, call OO.Player.create(). --> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? platform=html5-priority"></script> <!-- This instance creates a Player2 namespace. To use this instance call Player2.Player.create(). --> <script src="//player.ooyala.com/ v3/953a32aa99ec4023a9875dfba256637b?namespace=player2"></script> <!-- Similarly, these instances create Player3 and Player4 namespaces. --> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? platform=html5-priority&namespace=player3"></script> <script src="//player.ooyala.com/ v3/953a32aa99ec4023a9875dfba256637b?namespace=player4"></script> </head> The namespace parameter is one of several query parameters you can specify when loading a player. In the example here, we also make use of the namespace parameter to set HTML5 as the preferred playback mechanism for those players. For more information, see Player Query String Parameters. STEP 2: SET UP THE LAYOUT IN THE UI Now you will work within the body element to set up the layout and presentation of the four players. As you learned in Basic Tutorial for the HTML5 Player on page 11, you can specify the presentation layout for the players using named <div> elements. In this case, the four players will be displayed by presenting two on the left and two on the right: <body> My Player V3 Content PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 15

16 > <!-- The DIV elements specify the layout for the content elements. --> <!-- In this example, 4 player instances are presented on the screen. -- <div style="overflow:hidden;"> <div id="ooyalaplayer1" style="width:250px;height:180px;float:left"></div> <div id="ooyalaplayer2" style="width:250px;height:180px;float:right"></div> </div> <div style="overflow:hidden;"> <div id="ooyalaplayer3" style="width:250px;height:180px;float:left"></div> <div id="ooyalaplayer4" style="width:250px;height:180px;float:right"></div> </div> </body> Each of the players is assigned a div id that will be referenced in the calls to the Player.create() method, as shown in the next step. STEP 3: CREATE THE PLAYERS At this point you can include a <script> tag within the body element containing the code to create the four player instances and associate them with the layout you specified above. As you learned in Basic Tutorial for the HTML5 Player on page 11, it is a best practice to wrap the calls to the Player.create() method within the OO.ready() method to ensure the script is initialized and loaded. You specified four player instances within the head element for your page: The first instance was specified without a namespace parameter, so it uses the default namespace of OO. In this case we will call the OO.Player.create() method and associate the player with the div id of ooyalaplayer1. The remaining instances were specified with namespace values of Player2, Player3, and Player4. In those cases we will call Player2.Player.create(), Player3.Player.create(), and Player4.Player.create(), associating each with the remaining div ids (ooyalaplayer2, ooyalaplayer3, and ooyalaplayer4): <script> // Surround everything with OO.ready to make sure the script has // loaded and initialized completely OO.ready(function() { // Create instances of each of the players using the // DIV element ids (ooyalaplayer1, ooyalaplayer2, etc). {); // This first create() call uses the default OO.Player namespace. OO.Player.create('ooyalaplayer1','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', // These create() calls use the namespaces declared above in the HEAD section. Player2.Player.create('ooyalaplayer2','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); Player3.Player.create('ooyalaplayer3','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); Player4.Player.create('ooyalaplayer4','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 16

17 ); </script> COMPLETE EXAMPLE You now have a complete working example of a web page that loads multiple Ooyala V3 Players, renders them according to the layout specified in the <div> elements and their CSS attributes, and creates the players: <!DOCTYPE html> <html> <head> <title>my Test Player V3 Web Page </title> <!-- Load 4 Ooyala Player Instances --> <!-- The namespace parameter enables you to reference each of these in the create method calls below. --> <!-- This first instance uses the default OO namespace. To use this instance, call OO.Player.create() as shown below. --> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? platform=html5-priority"></script> <!-- This instance creates a Player2 namespace. To use this instance call Player2.Player.create() as shown below. --> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? namespace=player2"></script> <!-- Similarly, these instances create Player3 and Player4 namespaces. --> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? platform=html5-priority&namespace=player3"></script> <script src="//player.ooyala.com/v3/953a32aa99ec4023a9875dfba256637b? namespace=player4"></script> </head> <body> My Player V3 Content <!-- The DIV elements specify the layout for the content elements. --> <!-- In this example, 4 player instances are presented on the screen. -- > <div style="overflow:hidden;"> <div id="ooyalaplayer1" style="width:250px;height:180px;float:left"></div> <div id="ooyalaplayer2" style="width:250px;height:180px;float:right"></div> </div> <div style="overflow:hidden;"> <div id="ooyalaplayer3" style="width:250px;height:180px;float:left"></div> <div id="ooyalaplayer4" style="width:250px;height:180px;float:right"></div> </div> <script> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 17

18 OO.ready(function() { // Surround everything with OO.ready to make sure the script has // loaded and initialized completely // Create instances of each of the players using the DIV element ids (ooyalaplayer1, ooyalaplayer2, etc). // This first create() call uses the default OO namespace. OO.Player.create('ooyalaplayer1','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN',{); // These create() calls use the namespaces declared above in the HEAD section. Player2.Player.create('ooyalaplayer2','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); Player3.Player.create('ooyalaplayer3','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); Player4.Player.create('ooyalaplayer4','k2bnMxcjokUZuXIE5CZFYiHYS752a_BN', {); ); </script> </body> </html> CREATING AN HTML5 PLAYER You can create three types of players with the new embed style. CREATE A SIMPLE PLAYER The following example shows the simplest way to create a player with no video preloaded. <script> var videoplayer = OO.Player.create('playerwrapper','embed_code'); </script> CREATE A PLAYER WITH A PRE-LOADED VIDEO To create a player with a pre-loaded video, you add the embed code for the video. You can get the embed code from your Backlot account. For more information, see Publishing a Video. <script> var videoplayer = OO.Player.create('playerwrapper','embed_code'); </script> CREATE A PLAYER WITH ADDITIONAL PARAMETERS For a more advanced use of the Player embed style, you can create a player with parameters. The following script creates a player with additional parameters. <script> <script> var videoplayer = OO.Player.create('playerwrapper','embed_code',{ height:'100%', width:'100%' // additional params... ); PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 18

19 </script> CREATE A PLAYER WITH EXTERNAL IDENTIFIERS For a more advanced use of the Player embed style, you can create a player using external identifiers. The following example creates a player using an external Id. <!DOCTYPE html> <html> <body> <script src=" <div id='playercontainer'></div> <script> var myplayer = OO.Player.create('playerContainer', 'extid:<name:numeric_id>', { width: 640, height: 360 ); </script> </body> </html> CREATING AN HTML5 PLAYER WITH AN EXTERNAL ID You can create a player with an External Identifier. You can use an external identifier to assign custom identifiers to your video assets so they are easier to organize, update, and modify. Using external Ids also allow you to control playback by a specific id. CREATE A PLAYER WITH EXTERNAL IDENTIFIERS For a more advanced use of the Player embed style, you can create a player using external identifiers. To create a player with an external id, use the following format. You have to specify the extid: prefix followed by the external id. var externalid = "extid:123456"; The following example creates a player using an external Id. <!DOCTYPE html> <html> <body> <script src=" <div id='playercontainer'></div> <script> var myplayer = OO.Player.create('playerContainer', externalid, { width: 640, height: 360 ); </script> </body> </html> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 19

20 ADVANCED PLAYER MANAGEMENT: DESTROYING AN HTML5 PLAYER Use advanced event handling and player management to destroy a player once the video has finished playing. In this example, you will learn how to use the oncreate() function to handle events related to the playing of a video. In this advanced application, the user plays a video, and the event handlers determine when the video has finished playing. At that point, the event handler destroys the player and displays a message to the user. The purpose of this web page is to monitor and respond to downloading, playhead time changes, and played events, so the design will include: A head element containing a script tag specifying the loading and initialization request. A body element containing: UI presentation and layout for the Player container. Event listeners that monitor and respond to downloading, playhead time changes, and played events. A script tag that creates the Player. Follow these steps to build your web page: Step 1: Listening to Multiple Events on page 20 Step 2: Destroying the Player on page 21 See Complete Example on page 22 to view the code for the entire web page. To develop the head element and the logic for presenting and creating the Player, see Basic Tutorial for the HTML5 Player on page 11. To learn about event handling, see Event Model for HTML5 Player on page 37. For a list of all events, see the Player JavaScript API Reference. STEP 1: LISTENING TO MULTIPLE EVENTS Sometimes it is useful to listen and respond to multiple events at once. One way to do this is to subscribe to all events. The Event Model for HTML5 Player on page 37 provides you with a message bus, accessed via the created Player object's mb object. In this case we will use the message bus subscribe() function specifying a wildcard ("*") for the event name: function oncreate(player) { /* Subscribe to all events: * this allows you to create logic based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { ); Now that we are listening for every possible event, we can include logic based on multiple events within the callback function via its eventname parameter. In this example we write all events, except for downloading and playhead time changed events (OO.EVENTS.DOWNLOADING and OO.EVENTS.PLAYHEAD_TIME_CHANGED ), to the JavaScript console log: function oncreate(player) { PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 20

21 /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); STEP 2: DESTROYING THE PLAYER Once the video has finished playing, we would like to properly destroy the player and dispose of its resources. To do this we listen for the OO.EVENTS.PLAYED event: /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { ); To destroy the player and dispose of its associated resources, call the Ooyala V3 Player object's destroy() method: /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); Note: In ios you can only have one HTML5 player running at a time on a web page. You can call the Ooyala V3 Player object's destroy() method to ensure a player does not prevent the playback of another video in a different player on the page. Here is the completed oncreate() function: function oncreate(player) { /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 21

22 /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); COMPLETE EXAMPLE You now have a complete working example of a web page that responds to multiple events when the user plays a video. The event handlers determine when the video has finished playing, at which point the player is destroyed and a confirmation message is displayed to the user: <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load the Ooyala V3 Player --> <script src=" b2ac6ad82ee54ce4970c996a97868fd5"></script> </head> <body> <b>destroy Player Example</b><br/><br/> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> function oncreate(player) { /* Subscribe to all events: * this allows you to create logic based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 22

23 */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); OO.ready(function() { videoplayer = OO.Player.create( 'ooyalaplayer', 'U3NjZscjp3vm3tcRKUd2TVZIgHgecIRB', { /* Include the oncreate() function in these embedded parameters. */ oncreate : window.oncreate ); ); </script> </body> </html> RELATED INFORMATION For more information about destroying a player, see: Errors and Error Handling Player Events Player Functions PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER 23

24 DESIGNING THE SKIN FOR AN HTML5 PLAYER Ooyala provides many options for customizing the appearance and functionality of an HTML5 player when it is loaded. You can embed your player in a div container and use JavaScript and CSS to customize the player experience. In addition, you can use CSS styling to modify the player container appearance with any of the available CSS and CSS3 styles. Before you use the CSS3 styles and the CSS styles, you need to make sure that your target browsers support these styles. By enabling you to use CSS to customize your player experience, the player provides a convenient and efficient separation of some aspects of UI customization from backend player functionality. The player also enables you to customize player functionality using JavaScript APIs instead of query string parameters. Instead of working with both query string parameters and JavaScript, you can use JavaScript to create the functionality that you want for your HTML5 player, which allows you to retain your Flash player functionality as well. Table 1: Mechanism Description CSS Custom Modules You can customize the Player UI, changing its default look and feel by modifying a CSS file. You can also use CSS files to create custom UI skins. This option enables you to create multiple skins for your Player UI by separating the backend functionality from the look and feel. You can provide highly customized players tailored to a specific geographic region, demographic, or virtually any type of UI theme that you want. Custom modules enables you to develop JavaScript-based functionality that you can load with your player. This custom module capability extends your ability to add complex functionality to your player and create uniquely branded players with JavaScript. The following topics describe how to use the Player CSS and JavaScript customization. For more information about Player, see the Player JavaScript API Reference. The HTML5 player gives you three options for customization: CUSTOMIZING AN HTML5 PLAYER WITH CSS You can customize your Player skin or theme using a Cascading Style Sheet (CSS) file or inline CSS elements. While you can put CSS styles within your HTML file, it is easier and more modular to use a separate file and link to it. To customize your Player UI, you will need the following items which can be in one file (myvideopage.html) or more commonly in multiple files: The HTML or web page (such as myvideopage.html) or pages. The CSS file containing the web page and player styles (such as myvideo.css). Note: The default player has an associated set of styles that you can inspect for examples of the styling used for the default player. HTML5 PLAYER UI ELEMENTS You can use CSS to change the color, border, size and other aspects of various player controls. The following table lists some typical player controls some of which are automatically provided in the Ooyala default player. Note that the terms used for the Player controls are unconstrained and up to the developer PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 24

25 to create. You can however use a web development tool such as Firebug or its equivalent to inspect the DOM tree of the Ooyala demo and see how the player controls were named and styled. Player Control Play Pause Stop Replay Autoplay Fullscreen Scrubber bar Share Embed Info Use this Control to: Start playing a video. Halt the video mid-stream. When selected, the video will resume playing at the point it was paused. Stop the video. Once the video is complete, select to restart at the beginning. Automatically replay the video when it completes. Expand the video to occupy the full dimension of the device screen. Advance or retract the scrubber bar to seek to a particular position in the video. Enable or disable sharing options such as Digg, Stumble Upon, Facebook, Twitter, . Display the embed code and enable copying of the embed code. Display informational text such as the title or description of the video. As long as your target browser supports it, you can style the div id container using ordinary CSS properties, such as: height - set the height of an element such as the div container or an image overlay. width - set the width of an element. border - create a border around an element such as the div container or player. float - used to position a CSS element to the left or right, allowing other elements to wrap around it. There are many other CSS elements that you can apply. A full HTML5 reference is available at the W3C standards website and there are many useful references available via Internet search. You can also use CSS3 properties to add more complex styling. These properties may require additional prefixes to work in particular browsers. Firefox 4 requires the prefix -moz-, while Chrome and Safari requires the prefix - webkit- for many of these CSS3 styles. Some of these styles are: opacity - you can use this to easily create a transparent image or to make a CSS element transparent. mask - combines opacity values and clipping (using shapes, text or paths) to define parts of the mask. gradients - provide a smooth transition from one color to another. You can apply several color transitions to the same element. transforms - enables you to apply 2D or 3D effect to an element, enabling you to rotate, scale, move, and skew elements. transitions - enables you to add an effect when changing from one style to another, without using Flash animations or JavaScript code. animations - enable an element to gradually shift from one style to another. You can use it to replace animated images, JavaScript code or Flash animation with CSS3 animation elements. Again, support for these CSS3 styles is gated on what your target browser supports. You need to check out the level of support for each CSS style for your browser. PLAYER CSS CLASS NAMES For customization with Cascading Style Sheets (CSS), you need to use the same classnames as Ooyala's. When developing your own custom player styles, use must the same CSS classnames that Ooyala uses. These classnames are shown below. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 25

26 For information about linking your styles when you embed the player, see Linking to the CSS on page 28. CSS Class Name Ancilliary Classes Description.oo_promo.oo_start_spinner.oo_spinner.oo_mini_controls.oo_full_controls div.oo_start_button.oo_scrubber.oo_scrubber_track.oo_toolbar_item.oo_currenttime.oo_timetolive.oo_duration.oo_playhead.vod.oo_scrubber.live.oo_scrubber Style of preview panel before the video is played Style and position of the play button on the promo screen Style for the spinner displayed before play button on the promo screen appears Style for the spinner displayed after the play is clicked but before the video starts Styles for the player in "small" mode (opposite of.oo_full_controls below). These styles must minimalize the controls. Style for the scrubber (seek bar) Style for the scrubber track Added to control buttons for consistency Style for current time Style for duration count in live mode Style for duration count for VOD assets Style for the playhead (the indicator on the scrubber of the position in the video) Styles used when the player is in "full" mode (opposite of.oo_mini_controls above) Style for the scrubber (seek bar) for VOD assets Style for the scrubber (seek bar) for live assets.vod.oo_scrubber_track Style for the scrubber track for VOD assets.oo_controls.oo_currenttime.oo_timetolive.oo_duration.oo_toolbar_item.oo_button_highlight.oo_playhead Style for current time Style for duration count in live mode Style for duration count for VOD assets Added to control buttons for consistency Style to highlight buttons to feedback on click/ touch Style for the playhead (the indicator on the scrubber of the position in the video) Style and positioning of control bar PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 26

27 CSS Class Name Ancilliary Classes Description.live.oo_controls_inner.oo_label.oo_scrubber.oo_playhead Style and positioning of control bar Style applied to any text in the controls (duration, time, and so on), for consistent styling Style for the portion of the scrubber track that has already played (that is, that portion to the left of the playhead). Common style for any control button.oo_scrubber_track.vod.oo_scrubber_track.live.oo_scrubber_track.oo_progress.oo_buffer_progress Common styling for progress bars - played and buffered Style for "buffered" portion of scrubber bar.oo_playhead_progress.oo_button.oo_rewind.oo_play.oo_pause.oo_fullscreen.oo_fullscreen_on.oo_fullscreen_off.oo_live_indicator.oo_live_message Style for rewind button Style for play button Style for pause button Style for fullscreen button Style for fullscreen button when fullscreen is off (that is, the button to click to take you to fullscreen) Style for fullscreen button when fullscreen is on (that is, the button to click to exit fullscreen) Style of live video indicator Style of live text indicator.oo_ads_countdown.oo_end_screen.oo_replay Style of ad message text that appears during ad playback Style of end screen panel, which appears after video finished Style of replay button PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 27

28 OVERRIDING DEFAULT STYLES WITH CSS This small example shows how you can override style settings with your custom Cascading Style Sheets (CSS). The following example shows how you can override some of the default styles by redefining the class names described in Player CSS Class Names on page 25. Note: Be sure to use the!important directive (trailing the redefined properties) as highlighted below. This ensures that your redefinitions take priority over the defaults. /* Ooyala-specific classes */ /* Background color of the play progress bar */ /* Use!important to force override */.oo_playhead_progress { background:red!important; /* Background color of the buffer progress bar */ /* Use!important to force override */.oo_buffer_progress { background:#800!important; /* Put a picture of Super Mario under playhead ("slider") */ /* Use!important to force override */.oo_playhead { background-image: url( important; The CSS styling above has the effect shown in this snippet: To make your sure custom CSS file gets loaded in the player, see Linking to the CSS on page 28 LINKING TO THE CSS You can customize your player skin or theme using a Cascading Style Sheet (CSS) file or inline CSS elements. In the following example, the HTML page has a link to the myvideo.css file, which contains some CSS styles applied to the div container. Normally, you would use the HTML link element as shown below: PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 28

29 DON T DO THIS: <link href="myvideo.css" rel="stylesheet" type="text/css" /> However for the player, you need to place the reference to the.css file within the creation of the player instance: DO THIS: var embedcode = "45cmZqNDrKn7TvtpfGa9k9fQSeyK4VaI"; var player = OO.Player.create('playerwrapper',embedCode, { width: '800px', height: '300px', css:'/myvideo.css'); Specify the css in this way ensures that the player automatically loads your specified style and makes sure its is applied correctly. STYLING THE DIV CONTAINER WITH EXTERNAL CSS Style the DIV Container with an external CSS. In the following myvideo.html example, the player is wrapped in a div container with the div id of playerwrapper. We use an external.css file to hold all of the css styles including those for the playerwrapper DIV container. Note that the css file reference is located after we have instantiated a player instance. EXAMPLE The following example shows how to style the video and div container. In this example, we are applying styles to the HTML5 player using CSS. To ensure that we load the HTML5 player, we have specified "priority-html5" with the embed code. Notice that we defined the DIV id as 'playerwrapper' and then reference it when we create the player with the OO.Player.create function. In the hash of the OO.Player.create function we include the name of the CSS file that we want to associate with the player. Note: Remember to replace the embed code (123fake1ZDUzZGVlYmMxNzA3Y2MzNjBk) in this example with your own embed code. Do not just cut and past the placeholder version used in this example. <!DOCTYPE HTML> <html> <head> <meta name="apple-mobile-web-app-capable" content="yes"> <meta name = "viewport" content = "width = device-width, initial-scale = 1.0"> <script src=' platform=priority-html5'> </script> </head> <body> <h2>player V3 SHOWS BELOW THIS LINE</h2> <div id='playerwrapper'> </div> PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 29

30 <script> OO.ready(function() { var embedcode = "45cmZqNDrKn7TvtpfGa9k9fQSeyK4VaI"; var player = OO.Player.create('playerwrapper',embedCode, { width: '800px', height: '300px', css: '/myvideo.css' ); ); </script> </body> </html> REFERENCING THE DIV CONTAINER BY DIV ID You can reference the DIV container by its DIV Id. In the myvideo.css file we defined some very simple styles for the playerwrapper div container. By giving the div an id, you can then reference the player container by its div id name. In the following example, the div id is playerwrapper. The player is: inset from the margin. given a black background. given a border. In addition to the prior styles, the player opacity is set to make the video slightly transparent. In a normal video playback, this wouldn t be desirable. However, you could use this CSS style to set the player to opaque when the viewer selects pause or for some other event. You can create any number of player UI styles and themes using CSS and JavaScript. EXAMPLE The following example shows how to define a div id for a div container and apply some simple styles. #playerwrapper { width: 800px; height:300px; background-color: black; margin: 58px; opacity: 0.5; border:10px solid silver; STYLING A PLAYER WITH INLINE CSS You can style the player with inline CSS. In the previous example we demonstrated how to use a separate css file, myvideo.css, to define your css customizations. You can also use inline css styles in your web page. You can use either an external css file or use inline css to define styles for the div container of your player or for your player itself. Both will work. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 30

31 EXAMPLE In the following example, on the myvideo.html page, we use an inline css statement to give the player start button a background color of red and also give the control panel the background color of red. Note that the player elements have an oo_ prefix. css: '#playerwrapper.oo_promo div.oo_start_button { background-color: red; #playerwrapper div.oo_controls { background-color:red; opacity:0.8;', EMBEDDING AN HTML5 PLAYER IN AN HTML IFRAME Using a special page from Ooyala, you can embed your player in an iframe. With the HTML <iframe> ("inline frame") tag, you can embed content in a separately defined "container" of a web page. Detailed here is how you can embed the Ooyala player in an <iframe>. To use this feature, you should already have created a web page and should know where you want to embed the "iframed" player. OOYALA HTML FOR IFRAME Examine the following HTML. You should put this in your web page where you want the player to appear. This iframe.html page provided by Ooyala does all the work of embedding your player in the iframe. It takes the values you specify in the <iframe> attributes and invokes the Ooyala Player in the inline frame. The lines below have been broken for readability; in actual use, be sure to put this all on a single line. <iframe width="480" height="320" src=" ec=embedcode &pbid=player_branding_id &docurl=http%3a%2f%2fexample.com &platform=platform &options[optionname]=value&options[optionname]=value..." frameborder="0" allowfullscreen> </iframe> Explanation of the <iframe> attributes: Width and height: You can modify these as desired to fit your web page, although the values shown are optimal. The value for src: Leave this as is, except for the protocol (http or https) and the values for ec, pbid, docurl, and platform (detailed below). Depending on the security of the web page where you will put this iframe, set the protocol to either http or https. Insecure iframes (served by http) in a secure web page (served by https) cause alarming error messages about security mismatches in a user's browser. Parameter ec or embedcode pbid Description of Value The Ooyala embed code (asset or content ID) for the desired video. A "player branding ID" (or simply "player ID") for a player you have defined in Ooyala Backlot. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 31

32 Parameter docurl platform options Description of Value This parameter can be used to specify the analytics URL of a video (must be URL encoded). This causes analytics events for the video to be grouped under the URL specified rather than the URL the player is placed on. Any of the defined values for the platform parameter detailed at player_v3_api_qparams.html, such as flash or html5- fallback Standard Ooyala player runtime options, described in the next section. The optionames of nested passthrough parameters (for instance, ad manager parameters) are in dotted notation of the form parameter.subparameter, like ad-manager.url. Values must be URL-encoded. PASSING EMBEDDED PARAMETERS TO THE PLAYER IN AN <IFRAME> Standard Ooyala Player syntax allows you to specify certain runtime arguments as the third argument on the player invocation, such as autoplay:true, initialtime:122, and other options detailed at Embedded Parameters. With Ooyala's <iframe> you can pass the same embedded parameters with the &options= attribute. You can repeat the &options attribute and values as many times as you like. The only limit is the maximum length of a URL. Following the syntax in the code sample above, the &options= attributes look like the following. Be sure to URL-encode values that require it, such as URLs. <iframe width="480" height="320" src=" ec=embedcode &pbid=player_branding_id &platform=platform &options[autoplay]=true&options[initialtime]=122" frameborder="0" allowfullscreen> </iframe> EXAMPLE: PASSING GOOGLE IMA AD TAGS In the example below, the embedded parameters to set the Google Interactive Media Ads (IMA) adtagurl and other parameters are specified in the &options attribute for the iframe. <iframe width="480" height="320" src=" ec=embedcode &pbid=player_branding_id &platform=platform &options[google-ima-ads-manager.adtagurl]=someurlthatisurlencoded &options[google-ima-ads-manager.additionaladtagparameters.cust_params]=env %3Dmobilevcmshost%26siteview%3D1%26pth%3Djsbin.com &options[google-ima-ads-manager.additionaladtagparameters.vid]= </iframe> PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER 32

33 PLAYER JAVASCRIPT API PROGRAMMING The Ooyala V3 Player offers a new way to embed players in your web pages with more control over how and when the Player behaves. Note: This section applies to the HTML5 Player and the Flash Player. You can customize the behavior and functionality of the player using the Player JavaScript APIs for ads, assets, events, and error handling, and you can customize the appearance of the player by specifying its cascading style sheets (CSS) attributes. The following sections describe these customization options. ADVANCED JAVASCRIPT EXAMPLES FOR PLAYER Use the Player V3 JavaScript functions and events to create advanced applications with the Ooyala V3 Player. Note: This section applies to both the HTML5 Player and the Flash Player. This section provides quickstart tutorials with advanced Player JavaScript examples. For a more basic tutorial, see Basic Tutorial for the HTML5 Player on page 11. These complete examples contain sample HTML pages built with JavaScript functions and events from the Player V3 API. You will learn how to load and initialize your player, use advanced layout techniques, listen for events and handle errors, create robust controls, and use powerful Player functions. Loading the Player and Custom Modules in HEAD Load the Player in the <head> element so it is available when the page is loaded. To initialize the Player, include the following <script> element, which includes a src attribute that invokes the Player V3 API with the Player ID: <script src=' You may optionally add Query String Parameters on page 65 to the Player initialization call, and load additional JavaScript modules within the <head> element.... <head> <title>my Test Player V3 Web Page </title> <!-- Load Ooyala Player --> <!-- Include the <script> element in the head so the Player is available when the page loads. --> <!-- You may optionally include Player query string parameters. --> <script src=' e18ab1da ea2d8e67fbd'></script>. <!-- Load additional custom JavaScript modules --> <!-- script src='/mymodule.js'></script --> </head> PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 33

34 .. Organizing the BODY Set up basic sections in the body. The basic <body> structure can be organized into the following parts: 1. Presentation layout with named <DIV> elements. 2. The oncreate function, which ensures the player is in a playback-ready state. See Handling Player State with oncreate on page 35 for more information. 3. Asset information retrieved via listeners and method calls. See Information with Listeners and Method Calls on page 35 for more information. 4. The logic required for Playing the Video on page 36. The snippet below shows the first section, which is the presentation layer defined with <DIV> elements and a getelement() function that accesses them. Those layout elements are referenced later with the Player V3 API (see Information with Listeners and Method Calls on page 35).... <body> My Player V3 Content. // The DIV elements specify the layout for the content elements. <!-- This is where the player will be rendered: --> <div id='playerwrapper' style='width:480px;height:360px;'></div> <!-- This is where the metadata will be displayed: --> <div id='metadata'> -- Metadata --<br/> </div> <!-- This is where the bitrate information will be displayed: --> <div id='bitrate'> -- Bitrate (Flash only) --<br/> </div> <!-- This is where the buffering information will be displayed: --> <div id='buffer'> -- Buffer --<br/> </div> <script type=text/javascript> // This function retrieves the content element corresponding to the specified DIV element ID: function getelement(id) { return document.queryselector('#'+id);... </script> </body> PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 34

35 ... Handling Player State with oncreate You can manage all actions and customization related to the Player object within the oncreate function. As shown in the example below, you can use the Player V3 API to add event listeners and error handling within the oncreate() function. This example contains an event listener for handling errors that relies on the Player V3 message bus. For more information, see Handling Errors for an HTML5 Player Using JavaScript on page function oncreate(player) { // Everything you do with the player should be done either in oncreate // or as listeners on the message bus // to ensure that the player is ready to play videos and assets. console.log("-- oncreate"); player.subscribe('*','mypage', function(eventname) { console.log("received EVENT: "+eventname); );... // Error handling listener // Subscribe to the error event player.subscribe("error", "test-plugin", function(eventname, payload) { console.log(eventname+": "+payload); ); Information with Listeners and Method Calls Use event listeners and Player V3 API methods to retrieve the asset's information you want to work with. The simplistic example here uses getter methods to retrieve the asset's basic information (title, description, and duration) and bitrate- and buffer-related details. There are many other events and methods available. In addition, the basic structure of an event listener is shown here, using mb.subscribe.... // Buffer listener // Need to subscribe to an event if you want updates for the length of the buffer. // Ideally you'd listen for the BUFFERING event. window.bufferlength = -100; player.subscribe('playheadtimechanged', 'mypage', function(eventname) { var newbufferlength = player.getbufferlength(); if (bufferlength === newbufferlength) { return; window.bufferelement.innerhtml += "Buffer length is " + player.getbufferlength() + "<br/>" PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 35

36 window.bufferlength = newbufferlength; ); // Bitrate listener // You *must* listen to bitrateinfoavailable in order to request it. player.subscribe('bitrateinfoavailable', 'mypage', function(eventname) { var rates = player.getbitratesavailable(); if (rates.length > 0) { for (var i=0; i < rates.length; i++) { window.bitrateelement.innerhtml += "Rate: " + rates[i] + "<br/>" ); // Metadata // Content information is available after contenttreefetched, but it is best to wait until // playbackready for duration. player.subscribe('playbackready', 'mypage', function(eventname) { window.metadataelement.innerhtml += "Title is: " + player.gettitle() + "<br/>"; window.metadataelement.innerhtml += "Description is: " + player.getdescription() + "<br/>"; window.metadataelement.innerhtml += "Duration is: " + player.getduration() + "<br/>"; ); window.bufferelement = getelement('buffer'); window.bitrateelement = getelement('bitrate'); window.metadataelement = getelement('metadata');... Playing the Video Make sure everything is ready, specify embedded parameters, and play the video and assets. Wrap the call to OO.Player.create() within the OO.ready method to ensure the script is initialized and loaded. When you call OO.Player.create(), you will pass in the following parameters: The ID of the DIV element to which to attach the player object. The embed code for the video. Embedded player parameters. These can be used to customize player ads and behavior, and can determine player styles. For more information, see Embedded Parameters. You can also specify Custom Module Embedded Parameters. Tip: Rather than calling the asset object's.play function, set the autoplay parameter to true. OO.ready(function() { // Surround everything with OO.ready to make sure the script has // loaded and initialized completely window.player = OO.Player.create('playerwrapper','w3ZHc0Njr33Tdp- RRcwfZMjaOrmzOP82', { PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 36

37 // add the embedded player parameters here oncreate: window.oncreate, autoplay: true // Instead of calling object.play it is easier (and more robust) to set autoplay here ); ); </script> </body> </html> Renaming the Default Namespace Use namespace to place multiple independent copies of a player on a page. The namespace parameter allows multiple independent copies of player code on the same page, by renaming the default namespace OO to any other valid JavaScript id. For example if you use this embed: <script src=' <script src=' You can later use: MYPLAYER_1.Player.create(...) MYPLAYER_2.Player.create(...) EVENT MODEL FOR HTML5 PLAYER The HTML5 Player incorporates the use of a message bus to handle events. Note: This section applies to the HTML5 Player but not the Flash Player. The Ooyala player architecture enables you to use a message bus to handle events. The message bus enables publish/subscribe messaging and simplifies interaction with the player. Any number of modules can subscribe to messages and publish messages. As illustrated in the following figure, the message bus routes published messages to modules that have subscribed to those messages. Each player is independent with regards to the message bus. There is one message bus per each player. Each component decides which message it wants to communicate to or listen to via the message bus. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 37

38 Event Publish and Subscribe You can publish and subscribe to messages for event handling. CREATE, CONNECT, CHECK, AND LOAD The player message bus provides a means for modules to publish and subscribe to messages for event handling. It uses OO.Player.create and oncreate to create a message bus, connect modules to the message bus, check for 3rd party modules and connect them and then load everything. OO.Player.create When called, the OO.Player.create() function: Creates a new message bus. Goes over the list of registered modules and creates all of them. Connects all the registered modules to the message bus. oncreate When called, function oncreate(player): Checks for any additional modules (custom, 3rd party or other type). Enables these additional modules to connect to the message bus. Sends a message to the message bus signaling each module to start up. You must call oncreate() before anything can happen; otherwise, the existing and additional or thirdparty modules are not connected to the message bus and are not initialized. COMPARING PLAYER V3 AND V2 EVENT HANDLING The simplest way to handle events in Player V2 is to define a callback function, then pass its name to the embed tag using the callback parameter. In the current player (Ooyala V3 Player), to handle events, specify an oncreate function that registers for messages in the embedded parameters to the OO.Player.create() call. For example: function oncreate(player) { player.mb.subscribe('*','mypage', function(eventname) {); OO.Player.create('playerwrapper',embedCode, { oncreate: window.oncreate ); Message Bus API Communicate with the message bus using publish, subscribe, and other functions. The Ooyala Player exposes several functions for communication with the message bus. See the Player JavaScript API Reference for more information. Listening to a Message Bus Event You can use the message bus to listen to a single event or multiple events. The following example illustrates how to use the message bus to listen for an event and to use adddependent to block a pause event and display a confirmation message. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 38

39 You can use the adddependent() function to block events on other events. In the following example, we use the adddependent function to block a pause function so that when a pause button is pressed, we can display a message box and ask for confirmation. For more information about using the adddependent() function, see the Player JavaScript API Reference. To develop the head element and the logic for presenting and creating the Player, see Basic Tutorial for the HTML5 Player on page 11. To learn about event handling, see Event Model for HTML5 Player on page 37. Suppose you would like to customize how your web page responds to user interaction with the video player. In this example we intercept the pause and play events. When the user clicks the pause control, a confirmation dialog appears before the video is paused. When the user clicks the play or pause control, a textbox displays the new state of the player. The purpose of this web page is to provide the user with an option to switch to fullscreen mode, so the design will include: A head element containing a script tag specifying the loading and initialization request. A body element containing: UI presentation and layout for the Player container. Event listeners that monitor and respond to player events. Functions that intercept play and pause events and fire dependent events. A script tag that creates the Player. An HTML input element that displays text indicating whether the video is playing or paused. STEP 1: LISTENING TO MULTIPLE EVENTS Sometimes it is useful to listen and respond to multiple events at once. One way to do this is to subscribe to all events. The Event Model for HTML5 Player on page 37 provides you with a message bus, accessed via the created Player object's mb object. In this case we will use the message bus subscribe() function specifying a wildcard ("*") for the event name: function oncreate(player) { /* Subscribe to all events: * this allows you to create logic based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { ); Now that we are listening for every possible event, we can include logic based on multiple events within the callback function via its eventname parameter. In this example we write all events, except for downloading and playhead time changed events (OO.EVENTS.DOWNLOADING and OO.EVENTS.PLAYHEAD_TIME_CHANGED ), to the JavaScript console log: function oncreate(player) { /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 39

40 ); eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); STEP 2: INTERCEPTING EVENTS To intercept a video playing event (OO.EVENTS.PLAYING), call the message bus intercept() function. In this example we include a callback that displays a message in the textbox. If the textbox was previously empty, the message indicates that the video has begun playing whether the video has begun playing or playback has continued. We add a variable called juststartedplaying to keep track of the player state. <script> /* * Use this to control playing state messages. */ juststartedplaying = true; function oncreate(player) { player.mb.subscribe("*", 'example', function(eventname) { if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* * Intercept the video playing event * and display the status in the text box. */ player.mb.intercept( OO.EVENTS.PLAYING, 'example', function(eventname) { var message = OO.$("#messagesTxt").val(); if (message == "" juststartedplaying == true) { OO.$("#messagesTxt").val("Just started playing the video now!!!"); else { OO.$("#messagesTxt").val("Playback continues..."); ); </script> Similarly, to intercept a video pause event (OO.EVENTS.PAUSED), we again call the message bus intercept() function. If the user confirms that the video is to be paused, the callback fires a dependent event called user_allowed_pause, used later in the adddependent() method that blocks the OO.EVENTS.PAUSED event until this dependent event is fired. In this case the callback function displays a confirmation dialog, updates the player state, and updates the message displayed to the user: /* * Intercept the video pause event. * Publish the dependent event required before * actually pausing the video. * PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 40

41 * The adddependent() function monitors * this event ('user_allowed_pause') * and fires the PAUSED event only after this event fires. */ player.mb.intercept( OO.EVENTS.PAUSED, 'example', function(eventname) { if (confirm("pause Video?") == true) { /* * Once the video has paused we will next be able * to change the playing status from just starting * to continuing. */ juststartedplaying = false; OO.$("#messagesTxt").val("You paused the video!"); /* * Fire the dependent event required before * firing the PAUSED event. */ player.mb.publish('user_allowed_pause'); ); else{ player.play(); OO.$("#messagesTxt").val("Playback continues..."); STEP 3: SETTING UP EVENT DEPENDENCIES In order to block the video pause event until the dependent event fires, we call the message bus adddependent() function. In this example we require that the user_allowed_pause event fire before the OO.EVENTS.PAUSED event is permitted to fire: /* * This blocks the PAUSED event from firing until * the 'user_allowed_pause' event has fired * (see the intercept() function above). */ player.mb.adddependent( OO.EVENTS.PAUSED, 'user_allowed_pause', 'example', function(){ ); COMPLETE EXAMPLE You now have a complete working example of a web page that loads multiple Ooyala V3 Players, responds to user interaction with the video player by intercepting pause and play events with a confirmation dialog and textbox that displays messages, and creates the player: <!DOCTYPE html> <html xmlns=" PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 41

42 <head> <title>my Test Player V3 Web Page</title> <!-- Load Ooyala Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"></script> <!-- Load additional custom modules --> </head> <body> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> /* * Use this to control playing state messages. */ juststartedplaying = true; /* * Always add event listeners and error handling * within the oncreate() function. * Include this function in the embedded parameters * in the Player.create() call. */ function oncreate(player) { /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* * Intercept the video playing event * and display the status in the text box. */ player.mb.intercept( OO.EVENTS.PLAYING, 'example', function(eventname) { var message = OO.$("#messagesTxt").val(); if (message == "" juststartedplaying == true) { OO.$("#messagesTxt").val("Just started playing the video now!!!"); else { OO.$("#messagesTxt").val("Playback continues..."); ); /* * Intercept the video pause event. * Publish the dependent event required before * actually pausing the video. * * The adddependent() function monitors * this event ('user_allowed_pause') * and fires the PAUSED event only after this event fires. */ player.mb.intercept( OO.EVENTS.PAUSED, PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 42

43 'example', function(eventname) { if (confirm("pause Video?") == true) { /* * Once the video has paused we will next be able * to change the playing status from just starting * to continuing. */ juststartedplaying = false; OO.$("#messagesTxt").val("You paused the video!"); /* * Fire the dependent event required before * firing the PAUSED event. */ player.mb.publish('user_allowed_pause'); ); else{ player.play(); OO.$("#messagesTxt").val("Playback continues..."); /* * This blocks the PAUSED event from firing until * the 'user_allowed_pause' event has fired * (see the intercept() function above). */ player.mb.adddependent( OO.EVENTS.PAUSED, 'user_allowed_pause', 'example', function(){ ); </body> </html> OO.ready(function() { var videoplayer = OO.Player.create( 'ooyalaplayer', 'VwZjJ2czoYkk20dfBsb9VuAI1TIbQrg-', { oncreate: window.oncreate ); ); </script> Messages: <input type="text" id="messagestxt" size="108" value=" "> Writing to the Message Bus Use the publish() function to write to the message bus, setting parameters as needed. To write to the message bus, use the publish() function. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 43

44 For example, you can set the player to fullscreen mode by publishing the WILL_CHANGE_FULLSCREEN event with an event parameter of true: this.mb.publish(oo.events.will_change_fullscreen, true); To exit from fullscreen, set the WILL_CHANGE_FULLSCREEN event parameter to false: this.mb.publish(oo.events.will_change_fullscreen, false); The following is a complete example in which the publish() function is used to control fullscreen mode for the player. To develop the head element and the logic for presenting and creating the Player, see Basic Tutorial for the HTML5 Player on page 11. To learn about event handling, see Event Model for HTML5 Player on page 37. For a list of all events, see the Player JavaScript API Reference. In this example, you will learn how to use the oncreate() function to handle events related to the use of fullscreen mode. In this advanced application, the user clicks a button to switch to fullscreen mode, which is automatically disabled after 5 seconds via an event handler that monitors the playhead time (the video duration). The purpose of this web page is to provide the user with an option to switch to fullscreen mode, so the design will include: A head element containing a script tag specifying the loading and initialization request. A body element containing: UI presentation and layout for the Player container. An event listener that monitors the playhead time. A script tag that creates the Player. An HTML button for switching to fullscreen mode, with an associated button click event handler. Note: You cannot force your webpage to display in fullscreen mode for security reasons. User interaction is required to initiate the fullscreen mode. STEP 1: CAPTURING A BUTTON CLICK We will create the button used for switching to fullscreen mode, along with its associated event handler. Let's create a button with the label Swap to Fullscreen. We will assign an id attribute called swapbutton so we can associate the button with an event handler: <button id="swapbutton">swap to Fullscreen</button> We must also define a button click event handler, and refer to the button using its id attribute of swapbutton. We will take advantage of the jquery library included with the Ooyala V3 Player, referencing the button using the jquery functionality included in the OO namespace: OO.$("#swapbutton").click(function() { // logic to handle fullscreen event ); Now we can add the logic to handle the fullscreen event once the button is clicked. The Event Model for HTML5 Player on page 37 provides you with a message bus, accessed via the created Player object's mb object. In this case we will use the message bus publish() function to notify the Player that it is changing to fullscreen mode: PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 44

45 player.mb.publish(oo.events.will_change_fullscreen,true); In this case we pass the OO.EVENTS.WILL_CHANGE_FULLSCREEN event with a value of true, indicating that the Player is to switch to fullscreen mode. For a list of all events, see the Player JavaScript API Reference. Here is the web page design we have so far: <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load the Ooyala V3 Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"></script> </head> <body> <b>full Screen Example</b><br/><br/> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> OO.ready(function() { player = OO.Player.create( 'ooyalaplayer', 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { ); // embedded parameters will go here // This function defines a button that enables fullscreen mode when clicked. // The id, swapbutton, matches the id attribute of the <button> control defined below. OO.$("#swapbutton").click(function() { // Use the message bus API to publish the WILL_CHANGE_FULLSCREEN event. // This time the boolean argument (true) indicates // that the full screen setting is to be enabled. player.mb.publish(oo.events.will_change_fullscreen,true); ); ); </script> <br /> <!-- Place a button below the player container. Its id attribute, swapbutton, is referenced above in the click event. --> <button id="swapbutton">swap to Fullscreen</button> </body> </html> PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 45

46 STEP 2: MONITORING THE PLAY DURATION You can manage all events, errors, and customization related to the Player object within the oncreate() function, which is included in the body as shown here: <body> <b>full Screen Example</b><br/><br/> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> // Always add event listeners and error handling within the oncreate() function. // Include this function in the embedded parameters in the Player.create() call. function oncreate(player) { In this case we are monitoring the play duration. We would like to disable fullscreen mode once the playhead reaches 5 seconds, so we will need to subscribe to the OO.EVENTS.PLAYHEAD_TIME_CHANGED event. This event calls the handler with several arguments: argument[1] is the duration in seconds, so we will test whether argument[1] exceeds 5 seconds before publishing the OO.EVENTS.WILL_CHANGE_FULLSCREEN event with a value of false (to disable fullscreen mode): // Always add event listeners and error handling within the oncreate() function. // Include this function in the embedded parameters in the Player.create() call. function oncreate(player) { // Listen for the playhead time change event, // and disable fullscreen mode after 5 seconds of play: player.mb.subscribe(oo.events.playhead_time_changed, 'test', function(event) { // The PLAYHEAD_TIME_CHANGED event calls the handler with several arguments. // argument[1] has the duration. if(arguments[1] > 5) { // Use the message bus API to publish the WILL_CHANGE_FULLSCREEN event. // The boolean argument (false) accompanies the event, // indicating the full screen setting is to be disabled. player.mb.publish(oo.events.will_change_fullscreen,false); ); For more information about play events, see Displays, Plays, and Play Starts. Now that we have the the oncreate() function, we must include it in the embedded parameters for the OO.Player.create() method call: player = OO.Player.create( 'ooyalaplayer', PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 46

47 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { // Include the oncreate() function you defined above in these embedded parameters. oncreate : window.oncreate ); COMPLETE EXAMPLE You now have a complete working example of a web page that lets the user click a button to switch to fullscreen mode, which is automatically disabled after 5 seconds via an event handler that monitors the playhead time: <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load the Ooyala V3 Player --> <script src=" f6d2bba353f74b3db7683cf6b0a91f29?platform=html5-priority"></script> </head> <body> <b>full Screen Example</b><br/><br/> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> // Always add event listeners and error handling within the oncreate() function. // Include this function in the embedded parameters in the Player.create() call. function oncreate(player) { // Listen for the playhead time change event, // and disable fullscreen mode after 5 seconds of play: player.mb.subscribe(oo.events.playhead_time_changed, 'test', function(event) { // The PLAYHEAD_TIME_CHANGED event calls the handler with several arguments. // argument[1] has the duration. if(arguments[1] > 5) { // Use the message bus API to publish the WILL_CHANGE_FULLSCREEN event. // The boolean argument (false) accompanies the event, // indicating the full screen setting is to be disabled. player.mb.publish(oo.events.will_change_fullscreen,false); ); OO.ready(function() { player = OO.Player.create( 'ooyalaplayer', PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 47

48 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { // Include the oncreate() function you defined above in these embedded parameters. oncreate : window.oncreate ); // This function defines a button that enables fullscreen mode when clicked. // The id, swapbutton, matches the id attribute of the <button> control defined below. OO.$("#swapbutton").click(function() { // Use the message bus API to publish the WILL_CHANGE_FULLSCREEN event. // This time the boolean argument (true) indicates // that the full screen setting is to be enabled. player.mb.publish(oo.events.will_change_fullscreen,true); ); ); </script> <br /> <!-- Place a button below the player container. Its id attribute, swapbutton, is referenced above in the click event. --> <button id="swapbutton">swap to Fullscreen</button> </body> </html> Listening to Multiple Message Bus Events You can use the message bus to listen to multiple events. The following is a complete example that illustrates how to use the message bus to listen for multiple events. To develop the head element and the logic for presenting and creating the Player, see Basic Tutorial for the HTML5 Player on page 11. To learn about event handling, see Event Model for HTML5 Player on page 37. For a list of all events, see the Player JavaScript API Reference. In this example, you will learn how to use the oncreate() function to handle events related to the playing of a video. In this advanced application, the user plays a video, and the event handlers determine when the video has finished playing. At that point, the event handler destroys the player and displays a message to the user. The purpose of this web page is to monitor and respond to downloading, playhead time changes, and played events, so the design will include: A head element containing a script tag specifying the loading and initialization request. A body element containing: UI presentation and layout for the Player container. Event listeners that monitor and respond to downloading, playhead time changes, and played events. A script tag that creates the Player. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 48

49 STEP 1: LISTENING TO MULTIPLE EVENTS Sometimes it is useful to listen and respond to multiple events at once. One way to do this is to subscribe to all events. The Event Model for HTML5 Player on page 37 provides you with a message bus, accessed via the created Player object's mb object. In this case we will use the message bus subscribe() function specifying a wildcard ("*") for the event name: function oncreate(player) { /* Subscribe to all events: * this allows you to create logic based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { ); Now that we are listening for every possible event, we can include logic based on multiple events within the callback function via its eventname parameter. In this example we write all events, except for downloading and playhead time changed events (OO.EVENTS.DOWNLOADING and OO.EVENTS.PLAYHEAD_TIME_CHANGED ), to the JavaScript console log: function oncreate(player) { /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); STEP 2: DESTROYING THE PLAYER Once the video has finished playing, we would like to properly destroy the player and dispose of its resources. To do this we listen for the OO.EVENTS.PLAYED event: /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { ); To destroy the player and dispose of its associated resources, call the Ooyala V3 Player object's destroy() method: /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 49

50 */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); Note: In ios you can only have one HTML5 player running at a time on a web page. You can call the Ooyala V3 Player object's destroy() method to ensure a player does not prevent the playback of another video in a different player on the page. Here is the completed oncreate() function: function oncreate(player) { /* * Subscribe to all events: * this allows you to create logic * based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); COMPLETE EXAMPLE You now have a complete working example of a web page that responds to multiple events when the user plays a video. The event handlers determine when the video has finished playing, at which point the player is destroyed and a confirmation message is displayed to the user: <!DOCTYPE html> <html xmlns=" <head> <title>my Test Player V3 Web Page</title> <!-- Load the Ooyala V3 Player --> <script src=" b2ac6ad82ee54ce4970c996a97868fd5"></script> PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 50

51 </head> <body> <b>destroy Player Example</b><br/><br/> <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> function oncreate(player) { /* Subscribe to all events: * this allows you to create logic based on multiple events. */ player.mb.subscribe("*", 'example', function(eventname) { /* Write all events, except for downloading and playhead time changed events, * to the JavaScript console: */ if (eventname!= OO.EVENTS.DOWNLOADING && eventname!= OO.EVENTS.PLAYHEAD_TIME_CHANGED) console.log(eventname); ); /* Subscribe to the PLAYED event, * which only occurs when the video has finished playing: */ player.mb.subscribe(oo.events.played, 'example', function(eventname) { */ /* Destroy the player and properly dispose of its resources: player.destroy(); /* Notify the user: */ alert('the player has been destroyed!'); ); OO.ready(function() { videoplayer = OO.Player.create( 'ooyalaplayer', 'U3NjZscjp3vm3tcRKUd2TVZIgHgecIRB', { /* Include the oncreate() function in these embedded parameters. */ oncreate : window.oncreate ); ); </script> </body> </html> Advanced Event Handling You can customize what messages that you want to receive. Using a message bus model for event handling allows you to tailor what messages you receive. You can register for specific messages instead of getting all published messages. This gives you improved performance and clearer code: The message bus enables you to define your own plugins that will: Integrate deeply with the player. Have access to the message bus to respond to events with a change in functionality. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 51

52 INTEGRATING ADS IN HTML5 PLAYERS USING JAVASCRIPT You can work with ad networks to provide ad sets for your video assets. Note: Ads positions behave somewhat differently on desktop and mobile devices: Desktop platforms support all ad positions. ios-based devices support only pre- and post roll positions. Assigning Ad Sets Dynamically The player enables you to assign ad sets dynamically. You can assign an ad set to a specific embed code using the setembedcode function. With this setting, you can override a Backlot ad set with one that you set dynamically at runtime. Instead of having static ad content, you can adjust the ad content in response to any number of demographic factors. There are two ways to assign ad sets dynamically OO.Player.create Player V3 JavaScript function and the adsetcode parameter. Embedded parameters. Assigning an Ad Set with OO.Player.create The Ooyala Player enables you to assign ad sets dynamically with OO.Player.create and the adsetcode parameter. Each ad set has a unique Ad Set Code identifier. You must first setup the Ad Set Code in Backlot, as shown in the first steps below. To assign the ad set with OO.Player.create and the adsetcode parameter: 1. Associate an ad set with an asset (movie) in Backlot. 2. Once you create the association, you can get the Ad Set Code.The following figure shows an example of this association and the Ad Set Code that you create in the MONETIZE tab. 3. Use the OO.Player.create function to generate a player that takes a DOM element and the embed code of the player. In the following script example we name the DOM element playerwrapper and add the standard parameters height and width. 4. Add the additional adsetcode key value pair to associate an ad set with a particular player and player asset (video). <script> var videoplayer = OO.Player.create('playerwrapper','embed_code',{ height:'100%', PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 52

53 width:'100%', adsetcode:'youradsetcode' ); <script> Assigning Ad Sets with setembedcode You also have the option of assigning ad sets using the setembedcode function. With this function you can set up playlists with different ad sets or set up ad sets for different contexts. Note: This function requires that you associate an ad set with a movie in Backlot as shown in Assigning an Ad Set with OO.Player.create on page 52. The setembedcode function takes an additional options parameter that must be an object and must belong to the same provider as the embed code. In the options hash, use the adsetcode parameter, as in the following example. <script> player.setembedcode(embedcode, { adsetcode: 'youradsetcode' ); <script> Ad-related Events Several ad-related events are exposed on the Player message bus. Events related to ads all have the prefix OO.EVENTS. You can subscribe to the events to invoke your own callback functions when they occur; for an example, see Working With the Error Event on page 62 Event WILL_FETCH_ADS WILL_PLAY_ADS Published Before fetching ad information from the ad manager. When starting to play ads, second parameter is the details of the ad being played. Triggers an Ad Analytics AD_IMPRESSION event. ADS_PLAYED WILL_SHOW_COMPANION_ADS After the ad was complete, second parameter is the details of the ad being played. Before displaying companion ads. CUSTOMIZING ASSETS FOR HTML5 PLAYER USING JAVASCRIPT Customize assets using the Player message bus. The Ooyala Player exposes events for assets with all events prefixed with OO.EVENTS. Supported JavaScript methods for Player are shown in the following table. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 53

54 Table 2: JavaScript Methods for Assets get Methods set Methods other Methods getbufferlength getcurrentitem getcurrentitemdescription getcurrentitemembedcode getcurrentitemtitle getdescription getduration getembedcode getitem getlivetime getplayheadtime gettitle gettotaltime setplayheadtime setembedcode setcurrentitemembedcode play playmovie pause pausemovie seek Note: Currently, Player does not support the Player getactivepanel method. Events associated with Player assets are described in the following table. Table 3: Asset Events Event WILL_FETCH_ADS WILL_PLAY_ADS ADS_PLAYED WILL_SHOW_COMPANION_ADS SET_EMBED_CODE EMBED_CODE_CHANGED CONTENT_TREE_FETCHED METADATA_FETCHED AUTHORIZATION_FETCHED PLAYBACK_READY PLAYHEAD_TIME_CHANGED PLAYING PLAY_FAILED PAUSED PLAYED Published Before fetching ad information from the ad manager. When starting to play ads, second parameter is the details of the ad being played. After the ad was complete, second parameter is the details of the ad being played. Before displaying companion ads. Before the embed_code is changed. After embed_code was changed. When content tree is received, second parameter is the new content tree. When asset and module metadata is received, second parameter is the metadata. When authorization for playback is received, includes the actual streaming URLs. When player is ready to play. When seek time has changed. When content playback has started. If for some reason playback has failed. When content playback has paused. When content playback has finished (including all the ads). PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 54

55 Note: The Ooyala Player does not include activepanelchanged, ratingsapiready, and relatedmediaready events. Although the apiready, playercreated, loadcomplete, and playerembedded events are not provided, you can use the PLAYBACK_READY Event for equivalent functionality. PROGRAMMING BITRATES AND BUFFERING FOR FLASH PLAYERS USING JAVASCRIPT Ooyala provides bitrate and buffering functions and events. In addition, Ooyala uses a number of heuristics to make playback as smooth as possible. Bitrates and buffer control for Flash (RTMP, HDS, Akamai HD2) are supported in the Player. See the example code in Information with Listeners and Method Calls on page 35. End users can use a bitrate selector in the Flash player UI to select from bitrate options. To enable the bitrate selector for a Flash player, enable user controls for the player in Backlot. Bitrate controls on the player UI and bitrate APIs are supported on Flash for all content types (Ooyala VOD, remote VOD, remote live, remote live DV). The following table shows the JavaScript methods for bitrates and buffering. For detailed API docs, please see Note: The following APIs do not apply to the HTML5 player or mobile SDKs. Table 4: JavaScript Methods for Bitrates and Buffering get Methods getbitratesavailable() getbitratequalitiesavailable() gettargetbitrate() gettargetbitratequality() getbufferlength() getbitrateinfo() set Methods settargetbitrate(bitrate) settargetbitratequality() JAVASCRIPT CONSOLE LOG FOR SETTARGETBITRATE Calls to the bitrate control API settargetbitrate supply additional information to the browser's built-in JavaScript console log. You can use this log for end user video configuration. See the table below for the possible input values for your_player_id.settargetbitrate(x) and their corresponding JavaScript console log outputs. When the entered value in invalid, the actual targetbitrate value is adjusted to match the reported possible value. your_player_id.settargetbitrate(x) JavaScript Console Log Output X is equal to one of the available stream bitrates "targetbitrate set to: X" X is not equal to any available stream bitrate but is higher than one of the available stream bitrates, Y (Y is chosen as the closest bitrate below X) 0 < X < the lowest available stream, Y (X is between 0 and the lowest stream, Y) "Desired targetbitrate of X is invalid. Setting targetbitrate to nearby value of Y" "Desired targetbitrate of X is invalid. Setting targetbitrate to nearby value of Y" PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 55

56 your_player_id.settargetbitrate(x) X <= 0 JavaScript Console Log Output "Negative or zero-value targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto." X is an invalid value, such as a non-numerical value "Invalid targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto." Manual bitrate setting cannot be done "Manual targetbitrate setting has not been enabled, using targetbitrate of -1 to set bitrate to auto." EXAMPLE The example below will show determining what bitrates are available and then will show what happens when you attempt to set some incorrect and correct values. This example assumes the player ID is 'pp'. You will often see 'undefined' in the console logs, which is normal for the bitrate API. These examples crop out items in the console log that are not relevant to the example. Determining Available Bitrates pp.getbitratesavailable() Array [ 198, 364, 728, 1328, 2328, 4528 ] Setting the Bitrate Where 0<Bitrate<Minimum Available Bitrate Setting a value above 0 but lower than the minimum available bitrate is a special case that rounds up to the lowest available bitrate, and changes the 'targetbitrate' to that value. pp.settargetbitrate(20) undefined Desired targetbitrate of 20 is invalid. Setting targetbitrate to nearby value of 198 pp.gettargetbitrate() 198 pp.gettargetbitratequality() "low" Setting a Non-Number Bitrate Any non-number is always treated as an attempt to flip ABR back on. The API uses '-1' as a placeholder for ABR being on, so the 'targetbitrate' is adjusted to '-1'. pp.settargetbitrate("hello there") Invalid targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto. pp.gettargetbitrate() -1 pp.gettargetbitratequality() "auto" Setting the Bitrate to 0 PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 56

57 Attempts to set bitrates to zero also flip ABR back on, and move the targetbitrate to the placeholder value of '-1'. pp.settargetbitrate(0) Negative or zero-value targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto. pp.gettargetbitrate() -1 pp.gettargetbitratequality() "auto" Setting the Bitrate to a Value <0 Any negative value is always treated as an attempt to flip ABR back on. Again the 'targetbitrate' value is then moved to the '-1' placeholder value. pp.settargetbitrate(-501) Negative or zero-value targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto. pp.gettargetbitrate() -1 pp.gettargetbitratequality() "auto" Setting the Bitrate to -1 Actually using '-1' of course flips on ABR, and keeps the targetbitrate at '-1' as the ABR placeholder. Using '-1' is the proper way to use the manual API to flip the auto 'ABR' system back on. pp.settargetbitrate(-1) Negative or zero-value targetbitrate attempted, using targetbitrate of -1 to set bitrate to auto. pp.gettargetbitrate() -1 Setting the Bitrate to a Value One Below a Valid Value Even though this is only 1 below the next value up, the API always rounds down. So here it rounds down to 364. pp.settargetbitrate(727) Desired targetbitrate of 727 is invalid. Setting targetbitrate to nearby value of 364 pp.gettargetbitrate() 364 pp.gettargetbitratequality() "low" Setting the Bitrate to an Existing Value Setting an existing value simply tells you the value is set. pp.settargetbitrate(728) targetbitrate set to: 728 PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 57

58 pp.gettargetbitrate() 728 pp.gettargetbitratequality() "medium" Setting the Bitrate to a Value One Above a Valid Value Again the API always rounds down, so this attempt of 729 is treated as 728. pp.settargetbitrate(729) Desired targetbitrate of 729 is invalid. Setting targetbitrate to nearby value of 728 pp.gettargetbitrate() 728 Setting the Bitrate to an Existing Value Setting an existing value simply tells you the value is set. pp.settargetbitrate(4528) targetbitrate set to: 4528 pp.gettargetbitrate() 4528 pp.gettargetbitratequality() "high" Setting the Bitrate to a Value Above the Maximum Bitrate Setting any value above the maximum available bitrate rounds down to the maximum, changing the 'targetbitrate' to that maximum value. pp.settargetbitrate( ) Desired targetbitrate of is invalid. Setting targetbitrate to nearby value of 4528 pp.gettargetbitrate() 4528 pp.gettargetbitratequality() "high" Setting the Bitrate Quality Setting quality picks a targetbitrate. Low will pick the lowest, high the highest, and medium rounds up to a valid value near the middle on an even number of streams, or the middle on an odd number of streams. Available qualities are always low, medium, high, and auto unless the stream has less than 3 available bitrates. pp.getbitratequalitiesavailable() Array [ "high", "medium", "low", "auto" ] pp.settargetbitratequality("low") pp.gettargetbitrate() 198 pp.settargetbitratequality("medium") pp.gettargetbitrate() 1328 PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 58

59 pp.settargetbitratequality("high") pp.gettargetbitrate() 4528 pp.settargetbitratequality("auto") pp.gettargetbitrate() -1 Setting a Misspelled Target Bitrate Quality Setting targetbitratequality will not report an error back to the console if it is misspelled. getbitrateinfo is a generalized summary of your current status with the bitrate API: pp.settargetbitratequality("auto") pp.getbitrateinfo() Object { bitratequalities: Array[4], bitrates: Array[6], targetbitratequality: "auto", targetbitrate: -1 pp.settargetbitrate(728) pp.getbitrateinfo() Object { bitratequalities: Array[4], bitrates: Array[6], targetbitratequality: "medium", targetbitrate: 728 As the example contained 6 valid bitrates, this returns an array of 6 bitrates, and 4 qualities. ABOUT ABR In addition to the bitrate and buffer functions and events, Ooyala uses a number of heuristics to make playback as smooth as possible on every device, such as bandwidth estimation, content size, screen size and so forth. ABR playback (HLS, specifically) is preferred whenever available on the underlying devices. ABR stands for Adaptive Bite Rate. This is a technology that allows the Ooyala Player to adjust/change the bitrate of the stream delivered based on the bandwidth available to the viewer as measured over a period of time. The purpose of ABR is to compensate for drops or increases in bandwidth by lowering or upgrading the stream quality. The ABR changes to the stream quality do not happen immediately. This is not an instantaneous process. To make a bitrate change to the video stream, the player: Detects the change in bandwidth. Waits to confirm it is permanent vs. a momentary fluctuation. Sends a request to the Akamai Flash Media Server to shift to stream at the new bitrate. Waits for Akamai to deliver the new bitrate stream. Starts delivering the new bitrate to the viewer. ABR takes effect only when the player has detected there is sufficient bandwidth available to support a higher bitrate and higher quality stream. To upgrade the player makes multiple checks over a period of time. If all of the checks show the viewer has the required bandwidth to support a higher stream, then it will upgrade. If any of the checks fail to show the required bandwidth, then the process is repeated. The upgrade also depends on the buffer length meeting a minimal threshold, and being stable or increasing. Dropping the bitrate of the stream being delivered is done to favor smooth and uninterrupted playback. Therefore, if the player sees the buffer size dropping, then it will start the process of downgrading the bitrate in order to have a lower bitrate stream available when the current buffer is exhausted. Note: The current Ooyala player does not support activepanelchanged, ratingsapiready, and relatedmediaready events. Although the apiready, playercreated, loadcomplete, and playerembedded events are not provided in the player, you can use the PLAYBACK_READY Event for equivalent functionality. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 59

60 PROGRAMMING CLOSED CAPTIONING USING JAVASCRIPT Closed Captioning (CC) APIs enable you to get/set supported closed captions and localize the Player UI language. The Ooyala Player V3 supports closed captioning (also known as subtitles) for VOD and Live Streams. Ooyala supports closed captions for VOD in our ios and Android SDKs and for Flash and ios Web. For live streams, closed captions are supported for Flash-based devices. Note: ios Web - Because of the way that closed captions are supported in ios, we are not able to add closed caption data for ios web for remote assets. Live Streaming - For live streaming on HTML5 players, if closed caption data is available in the stream and the underlying platforms supports it (as ios does) then closed captions are displayed. The player does not facilitate the display of closed captions. If closed captions already exist in the stream, the player will not prevent them from appearing during playback. For closed captioning to work with live streams, you need to run the broadcast stream through your encoder to convert the stream and include Adobe Flash oncuepoint Data. The oncuepoint Data can be inserted by many encoders, such as the Cisco 8100 series media encoders. You must configure the source encoder to convert the CEA format to the cue points format to include closed captions and to have them work properly. The process begins with the capture and encoding of the live stream. The live stream is also converted to have include the Flash cue points inside the stream. The stream is passed as an RTMP stream (as is) or as an Akamai HD2 live stream and is then passed to the Ooyala player. JavaScript Closed Captioning APIs enable you to get supported closed captions and set closed caption languages. In live streaming mode, the closed caption languages are derived from the stream itself. The Closed Caption functions are: getcurrentitemclosedcaptionslanguages() setclosedcaptionslanguage() Note: The default behavior of closed captions in the V3 Player is "Off". You can enable closed captions with setclosedcaptionslanguage(). The player supports a number of LTR and RTL languages for close captioning and UI localization. You can review this list in the topic "Supported Closed Caption Languages". Note: When the closed caption file is uploaded, not played, Ooyala uses a strict XML parser for handling Closed Captioning. Your closed caption files at minimum need to work with your browser s parser. LIVE STREAM CLOSED CAPTIONS WITH CUSTOM OPF MODULES If you are working with an Ooyala Player Framework (OPF) module (Player V3 Flash-based) that you want to include in Player V3 and include live stream closed captioning, you will need to use the Ooyala Closed Caption APIs. For more information about creating OPF modules, contact Sales, your Customer Success Manager, or Technical Support. Note: Closed captioning for live streams only works with the Flash-based OPF module. The custom module available with Player V3 is a JavaScript-based module and only supports closed captioning for VOD. During live stream playback with a custom OPF module, Ooyala will first fire a OoyalaAPIConstants.CLOSED_CAPTIONS_TEXT_READY when we receive Closed Caption information on the first cue point. If you have a third party OPF UI module: PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 60

61 1. The module needs to check the available languages whenever this event goes off during live stream playback. 2. Use getcurrentitemclosedcaptionslanguages() to perform this check. 3. If the live stream happens to add more languages to their available languages in the middle of stream playback, Ooyala also fires CLOSED_CAPTIONS_TEXT_READY. 4. You can then enable closed captions as you would with VOD closed captions, using the setclosedcaptionslanguage()function. HANDLING ERRORS FOR AN HTML5 PLAYER USING JAVASCRIPT Error Handling functions and events enable you to get information about Player errors. The Ooyala Player error functions and events are described in the following tables. ERROR FUNCTIONS The following table describes the supported error handling functions. Function geterror, geterrorcode getstate Description Displays the video error code. Note that geterrortext() is not available or supported. Retrieves the current player state. Possible states are defined in OO.STATE as follows LOADING READY PLAYING PAUSED BUFFERING ERROR DESTROYED ERROR MESSAGES The following namespaces, described in the Player JavaScript API Reference, contain the error messages that can be handled through the V3 JavaScript Message bus. Use message bus events to handle errors by subscribing to or intercepting the OO.EVENTS.ERROR event: Error Namespace OO.ERROR OO.ERROR.API OO.ERROR.API.SAS OO.ERROR.PLAYBACK Description Represents the Ooyala V3 Player Errors. This is the parent namespace for all errors, and includes errors for channel content. Represents errors related to content, metadata, and server connection. Represents all authorization-related errors. Represents all errors related to playback. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 61

62 ERROR EVENTS The following table describes the error handling events published by the message bus. Error Event PLAYER_CREATED ERROR DESTROY Description The very first message that is published after player is created, used to notify all plugins to initialize themselves. Published when error has occurred, second parameter has error details. Published when player is being destroyed. WORKING WITH THE ERROR EVENT The OO.EVENTS.ERROR event is published to the message bus. Here's how you can work with it. You have two design options for how you handle the error: mb.subscribe triggers the function you specify (the callback function) when an error happens, and the error continues to propagate to other subscribers. mb.intercept hijacks the error notification and allows you to modify the payload for future subscribers. That is, intercepting errors allows you to change error messages if you really want to. Perhaps the most practical recommendation is to use mb.subscribe and handle the error as desired according to any existing error-handling functions you might already have in place(such as print it out to console, stop playback, throw up an error screen, etc). In the following example illustrating the use of the Message Bus subscribe() method, the callback function YourErrorHandlingFunctionNameHere is invoked if the OO.EVENTS.ERROR event is published to the message bus: <div id="ooyalaplayer" style="width:640px;height:360px"></div> <script> function oncreate(player) { player.mb.subscribe( OO.EVENTS.ERROR, 'test', function(event, payload) { YourErrorHandlingFunctionNameHere(yourArgs); ); OO.ready(function() { player = OO.Player.create( 'ooyalaplayer', 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { oncreate : window.oncreate ); </script> In the following example illustrating the use of the Message Bus intercept() method, when an error occurs, the message "Houston, we have a problem." is printed to the JavaScript console. //Intercept error PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 62

63 player.mb.intercept(oo.events.error, "test-plugin", function(eventname, payload) { return ["Houston, we have a problem."]; ); For complete examples that include the use of Message Bus events, see Advanced JavaScript Examples for Player on page 33. LOCALIZING A FLASH OR HTML5 PLAYER USING JAVASCRIPT You can localize your player user interface using Ooyala Player APIs in JavaScript. The default language for the player user interface (UI) is American English. For Flash, the Ooyala player is localized in languages listed in the table below. At this time, for HTML5, the Ooyala player is only localized in English and Japanese. The player detects the language selection in the browser and sets the user interface to display text in that language. Here are some things to keep in mind about Player localization: Only Ooyala can add new languages to the player. You can override the language settings. For example, you might set your browser to French but have the player language set to Hebrew. To do this, you need to specify a locale string in the Player's DIV. For example: <!-- Player Placement --> <div id='playerwrapper'style='width:480px;height:360px; OO.Player.create(...{ locale: 'he' );>... The following table lists the valid values for the locale parameter. Language String Player Support English en Flash, HTML5 German de Flash Spanish es Flash French fr Flash Italian it Flash Japanese ja Flash, HTML5 Polish pl Flash Portuguese pt Flash Russian ru Flash Simplified Chinese zh-hans Flash Traditional Chinese zh-hant Flash Arabic ar Flash Catalan ca Flash Czech cs Flash Danish da Flash PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 63

64 Language String Player Support Dutch nl Flash Finnish fi Flash Greek el Flash Hebrew he Flash Hungarian hu Flash Icelandic is Flash Korean ko Flash Malay ml Flash Norwegian no Flash Persian fa Flash Punjabi pa Flash Romanian ro Flash Serbian sr Flash Croatian hr Flash Bosnian bs Flash Slovenian sl Flash Slovak sk Flash Swedish sv Flash Thai th Flash Turkish tr Flash Ukranian uk Flash Vietnamese vi Flash Indonesian id Flash Hindi hi Flash Brazilian Portuguese pt-br Flash Portuguese (Portuguese) pt-pt Flash Spanish (Spanish) es-es Flash Latin Spanish es-419 Flash British English eng-gb Flash US English en-us Flash PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 64

65 PROGRAMMING PARAMETERS FOR PLAYER USING JAVASCRIPT You can use query string parameters and embedded parameters to modify the player experience. The Ooyala Player has two types of parameters that you can use to modify the player experience. The primary difference between the two parameter types is in where you place them: 1. Query string parameters: in the URL in the <script> for invoking the Player. 2. Embedded parameters: within the Player DIV container. Query String Parameters Modify the player with query string parameters. You add these types of query parameters to the <script> tag. These query string parameters include the following: Parameter Description namespace=(uniquejavascriptid) Use the namespace parameter to place multiple independent copies of a player on a page. See details in Renaming the Default Namespace on page 37. platform=( flash-only flash html5-fallback html5-priority ) tweaks=android-enablehls Use the platform parameter to control the selection mechanism between Flash and HTML5 playback. See details in Setting the Default Video Platform with a Parameter on page 67. Use the tweaks parameter to enable HLS on your Android devices for the web. Although you can use this parameter to enable HLS on Android devices, certain limitations exist for HLS playback on 2.x and 4.x devices. For more information about operability on Android devices, see "Enabling HLS on Android Web." Note: As the use of the tweaks parameter can involve native playback issues, we cannot guarantee optimal playback experience on every Android device and OS version. Example v3/123fake6b6774f909c2fa6d23ce5334a?tweaks=androidenable-hls Note: The legacy Player API had query string parameters for passing tags of ad server and ad networks to the Ooyala player. For Player V3, the supported ad servers/networks and the mechanisim for passing related tags is detailed in Ads Embedded Parameters Overview on page 71. Enabling HLS Playback on Android Web Ooyala provides HLS playback support for web browsers on devices running specific versions of the Android OS. Ooyala offers a very simple solution to enable HLS playback on the web for your Android devices. You can use the tweak query string parameter on the URL to enable HLS playback. It works only with our HTML5 player and has no impact on playback for ios devices. You can enable HLS for Android Web, however PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 65

66 depending upon the device and Android OS, the playback experience can vary due to the native Android implementation. Note: Due to known limitations on Android 2x devices, Ooyala cannot guarantee HLS playback on these devices. How it Works You can use the tweaks parameter to enable HLS playback on your Android devices. You include this embed parameter in the URL just as you do any other query parameter. For details about how to use this parameter on our web page, see the Player "Query Strings Parameter" article. Although you can use this parameter to enable HLS playback on Android devices, certain limitations may exist for specific Android devices of version 4.x and later. In general, our tested playback shows that using HLS playback on Android web works more consistently on the Ooyala player than native player for VoD content. Some rendering issues with the player controls can occur depending upon the Android device and OS version. The following table lists what versions of Android we support, and at what level. Android Version Ooyala VoD Ooyala Live Streaming 4.0 Optimal playback experience. 4.1 Optimal playback experience. Some potential rendering issues with player controls 4.2 Optimal playback experience. Playback as expected. Potential rendering issues with player controls. Optimal playback experience. Optimal playback experience. 4.3 Limited support. Playback as expected. Potential rendering issues with player controls. 4.4* Plays as expected. Plays as expected. 5.0 Some devices do not play as expected. There are some issues related to seek operations on certain devices. Some devices do not play as expected. There are some issues related to seek operations on certain devices. * Tested with a small subset of devices. Setting Autoplay in a Parameter Hash Tag Enable autoplay through an option hash tag. Autoplay is not supported on all mobile devices. For example, the Apple ios requires that a user action to start playback. It is important for you to be familiar with the underlying capabilities of your target devices. You can enable autoplay for your player by setting autoplay to true in after an option hash tag. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 66

67 EXAMPLE The following example shows how to enable autoplay. var player = OO.Player.create('playerwrapper',embedCode, { width: '800px', height: '300px', css: '/myvideo.css' autoplay: true Setting the Default Video Platform with a Parameter With the platform parameter, you control the selection mechanism between Flash and HTML5 playback. The parameter format is: platform=(flash-only flash html5-fallback html5-priority) For the player, the multimedia default is Flash. When Flash is not available, the player will now default to html5-fallback (if available). The parameter takes any one the following values. Value for platform parameter flash flash-only html5-fallback html5-priority Description For desktop, enables default Adobe Flash playback. For mobile devces, sets the preference to Flash but also allows HTML5 fallback. Flash playback only. If Flash is not detected, an error message is displayed and the viewer requested to install the Flash plug-in. Uses Flash but enables fallback to HTML5. Sets HTML5 as the preferred playback mechanism but also allows Flash fallback. Warning: If you have custom OPF modules, they will continue to work only when specifying platform=flash or platform=flash-only in the request to load the Ooyala V3 Player. Hiding the Control Bar for Ad Playback in a Parameter Hash Tag Hide the control bar during ad playback through an option hash tag. Note: This parameter is available for Flash and HTML5 desktop. You can hide the control bar when a video ad is playing on your player by setting showinadcontrolbar to false in an option hash tag. If showinadcontrolbar is missing or set to true, the control bar will appear while an ad is playing on your player. By default showinadcontrolbar is set to true. This global parameter works for all ad types supported by Ooyala. Note: There is a Google IMA embedded parameter also called 'showinadcontrolbar'. You should not use both showinadcontrolbar parameters simultaneously. The preferred method is to use the global parameter explained on this page outside of the 'google-ima-ads-manager' hash. EXAMPLE The following example shows how to hide the control bar. var player = OO.Player.create('playerwrapper', embedcode, { showinadcontrolbar: false PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 67

68 ); Show or Hide Ad Marquee During Ad Playback Show or hide the ad marquee during ad playback. Note: This parameter is only available for Flash. The showadmarquee parameter specifies whether to show or hide the ad marquee during ad playback. Valid values are true and false. The default value is true. If showadmarquee is missing or set to true, the ad marquee will appear while an ad is playing on your player. If showadmarquee is set fo false, the ad marquee will be hidden during ad playback. This global parameter works for all ad types supported by Ooyala. EXAMPLE The following example shows how to hide the ad marquee during ad playback. var player = OO.Player.create('playerwrapper', embedcode, { showadmarquee: false ); Adding a TV Rating Watermark to a Flash Player Add a TV rating watermark to assets using player parameters and custom metadata in Backlot. Note: This feature is only available for Flash desktop. Ooyala Flash player is now FCC compliant for displaying TV ratings associated with broadcast content. TV ratings are applied at the asset level, and each asset can only have one TV rating. The TV rating watermark appears when the video starts playing and will appear again when the video resumes after ad playback. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 68

69 Note: The TV rating watermark will not appear during ad playback. CUSTOM METADATA TO ADD TO BACKLOT PER ASSET Populate the following metadata in Backlot as custom metadata for each asset you want to give a TV rating watermark. Custom Metadata Description Valid Values Required Example tvrating Specifies audience ratings or recommended audience. TV-X Where X can be one of the following: Y Y7 G PG 14 MA Yes tvrating: TV- PG PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 69

70 Custom Metadata Description Valid Values Required Example Go to the FCC site to see descriptions of each rating. tvsubratings Specifies content label or nature of content. Note: tvsubratings can only be applied to Y7, PG, and 14 TV ratings. V S L D FV V: violence S: sexual situations L: coarse or crude indecent language D: suggestive dialogue FV: fantasy violence No tvsubratings: D,S Note: For multiple sub ratings, values should be comma or semicolon separated with no spaces between values. tvratingurl (optional) A click through URL. A URL link. No tvratingurl= " ptc/ parentsguide/ tvratings2.html" PLAYER PARAMETERS Apply the following parameters at the page level. tvratingstimer: This required parameter specifies the duration of the TV rating watermark on the player (in seconds) on initial play and every time the video resumes from Ad breaks. The default value of this parameter is "never", but other valid values include "always" and "some_number". always: The watermark appears for the duration of the video (but will not appear during ad playback). never: The watermark never appears. some_number: You will replace some_number with the number of seconds you want the TV rating to remain on the player. tvratingsposition: This optional parameter specifies the position on the player where the TV rating will appear. By default this value is set to "top-left", but other valid values include "top-right", "bottom-left", and "bottom-right". EXAMPLE The following example shows how to set the tvratingsposition and tvratingstimer player parameters. var player = OO.Player.create('playerwrapper', embedcode, { tvratingsposition: "top-left", tvratingstimer: "15" PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 70

71 ); Toggling the Display of Cue Point Markers Show or hide cue point markers. Cue points are visual markers that enable an end user to predict ad or segment breaks. shoulddisplaycuepointmarkers is a Boolean parameter. By default, cue point markers are hidden (False). If set to True, and if there are active mid-roll and post-roll ads available, the Player will display any cue point markers on the scrubber bar. Note: This feature is currently available for Flash desktop and FreeWheel ads only. EXAMPLE The following example shows how to enable autoplay. var player = OO.Player.create('playerwrapper',embedCode, { width: '800px', height: '300px', shoulddisplaycuepointmarkers: true, Player Embedded Parameters Embedded parameters are contained in the body of the DIV container. You add these parameters to the player embed code within the DIV container. These parameters include CSS styling such as width and height and ad service tags as passthrough parameters to the Ooyala Player for advanced ad tracking and targeting. The embedded parameters include the following. This is only a partial list. For a complete list, see Player Query String Parameters. Parameter enablechannels initialtime locale Ads Embedded Parameters Overview on page 71 Description Enable loading Flash videos in Channels mode. This parameter provides backwards compatibility for channels. Default is false. Set an initial time in seconds to start playing content at a specific point. This parameter can be used to enable seeking for ios-based devices. Set or override the language and closed caption options. Pass ad server tags to the Ooyala player. Ads Embedded Parameters Overview Customize ads using embedded parameters. You can pass ad-service-related tags to the Player with the embedded parameters listed in the following table. For a full description of these parameters and their tags, see the individual topics for each of the ads embedded parameters by selecting the parameter link. You can also see our Ads Integration developer guide topics for step-by-step information about adding ads to your content and integrating an ad network with your player. Note: Ads positions behave somewhat differently on desktop and mobile devices: Desktop platforms support all ad positions. ios-based devices support only pre- and post roll positions. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 71

72 Parameter in-stream vast freewheel-adsmanager google-ima-adsmanager liverail-adsmanager vpaid-adsmanager Description Pass in-stream ad server or network tags to the Ooyala player. The parameter takes a key/value pair representing an In-Stream URL. For more information see the In-Stream Ads Embedded Parameters reference topic. Pass FreeWheel ad server or network tags to the Ooyala player. The parameter takes a key value pair representing a FreeWheel URL. For more information, see the FreeWheel Embedded Parameters reference topic. Pass Google IMA ad server or network tags to the Ooyala player. The parameter takes a key value pair representing the ad server or network URL. You can pass google-ima-ads-manager ad tags to the Ooyala player. For more information, see the Google IMA Ads Embedded Parameters reference topic. Pass certain LiveRail parameters (LR_ parameters) to communicate with LiveRail. For more information, see the LiveRail Ads Embedded Parameters reference topic. Pass VAST ad server or network tags to the Ooyala player. VAST is an ad format which uses xml to describe Linear ads (video ads), non-linear ads (overlay ads) and companion ads. For more information, see the VAST Ads Embedded Parameters reference topic. Pass VPAID Ad Manger tags to the Ooyala player. For more information, see the VPAID Ads Embedded Parameters reference topic. PLAYER DEVELOPER GUIDE PLAYER JAVASCRIPT API PROGRAMMING 72

73 DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER The Ooyala Player enables you to build JavaScript custom modules using our Event Model and JavaScript APIs. To create a custom module for your player, you simply need the player and the tools you normally use to create your HTML5 web pages and JavaScript code. You can load your custom player plugins directly on your web page and then attach them to your Ooyala player. Note: The Player V3 custom module plug-in (JavaScript-based) for HTML5 serves a similar customization role as the Player V2 Open Player Framework (OPF) module does for Flash. You can load the Player V3 custom modules directly on your web page. JAVASCRIPT EXAMPLE The following sample JavaScript, samplev3module.js, illustrates how to build a custom UI without loading our default UI. You need to define your custom module using the OO.plugin method. You can use this sample as a template for building custom modules that can be embedded within an Ooyala player for syndication. This example: Creates a UI with a play and pause button located outside the video display and also lists the Current Time and Duration of the video. A slider bar is positioned beneath the play/pause button row. Makes use of an external jquery-ui.css file for theming. Subscribes to three events. Note that the events are prefixed with OO.EVENTS. Publishes play, pause, and seek events. Returns the module class constructor so that the Ooyala player can instantiate the custom module correctly. /** * Ooyala, Inc.All Rights Reserved.*/ // samplev3module.js // Each custom module must be defined using the OO.plugin method // The first parameter is the module name // The second parameter is a factory function that will be called by // the player to create an instance of the module. This function must // return a constructor for the module class (see the end of this example) OO.plugin("SampleUIModule", function (OO, _, $, W) { /** * Custom UI Sample Module * Modules developed using this template can later be embedded * within Ooyala's player for syndication. * * A sample UI module to demonstrate how to build a custom UI * instead of loading our default UI. This module contains a * simple play/pause button and scrubber bar. * Parameters: * OO, namespace for PlayerV3 * _, a reference to underscore.js lib. * $, a reference to jquery lib. * W, a reference to window object. */ // load jquery UI lib and css: var Sample = {; PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 73

74 $('head').append('<link rel="stylesheet" type="text/css" href=" ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css">'); // This section contains the HTML content to be used as the UI var CUSTOMER_TEMPLATE = '<div class="customer_ui" style="position:relative; top:20px;' + 'height:80px; left:31px; width:640px;">' + '<input class="playbutton" type="button" value="play">' + '<input class="pausebutton" type="button" value="pause">' + '<span>current Time:</span><span class="currenttime"></span>' + '<span>duration:</span><span class="duration"></span>' + '<div class="slider" style="margin-top:20px; width:640px;"></ div>' + '</div>'; // A constructor for the module class // will be called by the player to create an instance of the module // First parameter is a reference to a message bus object, which // is required to be able to pub/sub to player events. // Second parameter is a unique id assigned to the module for // debugging purposes Sample.SampleUIModule = function (mb, id) { this.mb = mb; // save message bus reference for later use this.id = id; this.duration = NaN; this.playing = false; this.init(); // subscribe to relevant events ; // public functions of the module object Sample.SampleUIModule.prototype = { init: function () { // subscribe to relevant player events this.mb.subscribe(oo.events.player_created, 'customerui', _.bind(this.onplayercreate, this)); this.mb.subscribe(oo.events.playhead_time_changed, 'customerui', _.bind(this.ontimeupdate, this)); console.log("before CONTENT_TREE_FETCHED"); this.mb.subscribe(oo.events.content_tree_fetched, 'customerui', _.bind(this.oncontentready, this));, " + // Handles the PLAYER_CREATED event // First parameter is the event name // Second parameter is the elementid of player container // Third parameter is the list of parameters which were passed into // player upon creation. // In this section, we use this opportunity to create the custom UI onplayercreate: function (event, elementid, params) { this.playerroot = $("#" + elementid); this.rootelement = this.playerroot.parent(); this.playerroot.find(".plugins").append("<div class='foomessage' "style='color:red; text-align:center; font-size:2em;'>" + "Hello this is a custom UI</div>"); console.log("hello, init here!!!", this.rootelement, this.id); $(CUSTOMER_TEMPLATE).insertAfter("#" + elementid); W.$( ".slider" ).slider({ stop: _.bind(this.onsliderstop, this), slide: _.bind(this.onslide, this) ); this.playbutton = this.rootelement.find('.playbutton'); PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 74

75 , this.pausebutton = this.rootelement.find('.pausebutton'); this.playbutton.click(_.bind(this.onplay, this)); this.pausebutton.click(_.bind(this.onpause, this)); // Handles CONTENT_TREE_FETCHED event // Second parameter is a content object with details about the // content that was loaded into the player // In this example, we use the parameter to update duration oncontentready: function (event, content) { this.duration = content.duration / 1000; this.rootelement.find(".duration").html(this.duration); W.$( ".slider" ).slider("option", "max", this.duration);, played // Handles PLAYHEAD_TIME_CHANGED event // In this example, we use it to move the slider as content is ontimeupdate: function (event, time, duration, buffer) { // update scrubber bar. if (duration > 0) { this.duration = duration; this.rootelement.find(".currenttime").html(math.round(time)); this.rootelement.find(".duration").html(math.round(this.duration)); W.$( ".slider" ).slider("option", "max", this.duration); W.$( ".slider" ).slider("option", "value", time);, onplay: function () { this.playerroot.find(".foomessage").remove(); this.rootelement.find('video.video').css('left', '0px'); //this is temporary code. this.play(); this.playing = true;, onpause: function () { this.pause(); this.playing = false;, // Sends PLAY event to start playing the video play: function () { this.mb.publish(oo.events.play);, // Sends PAUSE event to pause the video pause: function () { this.mb.publish(oo.events.pause);, // Sends SEEK event to seek to specified position seek: function (seconds) { this.mb.publish(oo.events.seek, seconds);, onslide: function (event, ui) { console.log("onslide"); if (this.playing) { this.pause(); PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 75

76 , onsliderstop: function (event, ui) { this.seek(ui.value); if (this.playing) { this.play();, ; end_marker: true ); // Return the constructor of the module class. // This is required so that Ooyala's player can instantiate the custom // module correctly. return Sample.SampleUIModule; CUSTOM MODULE HTML EXAMPLE The following HTML file uses the custom module JavaScript code shown above. In this file: 1. We have included jquery, jquery UI, and and jquery CSS for theming. 2. We have set the platform parameter to HTML5 priority. 3. We call the samplev3module.jscode that we created earlier. /** * Ooyala, Inc.All Rights Reserved.*/ <html> <head> <title>sample Player Module</title> <script src=" <script src=" <script src=" <link href=' jquery-ui.css' rel='stylesheet' type='text/css'> <script src=" with player branding id>?platform=html5-priority"></script> <script src="samplev3module.js" type="text/javascript"></script> </head> <body> <div id='ooyalaplayer' style='width:640px;height:360px'></div> <script> OO.ready(function() { OO.Player.create('ooyalaplayer', <'replace with video embed code'>); ); </script> <noscript><div>you must enable Javascript to watch this video</div></ noscript> </body> </html> Note: In this example, the div container represents the physical space in the HTML page. When we create the player, we need to pass it the player location in the web page. This requires that we give the PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 76

77 div container and the player name the same name. The player name ooyalaplayer provides a reference to the location of the player on the page. The first use of ooyalaplyaer occurs in the HTML to name the div container and the second reference to ooyalaplayer occurs within the JavaScript to create the player within the div container location. PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER 77

78 PLAYER FEATURES AND APPS CUSTOMIZATION You can incorporate and customize many of the player features and apps to offer your customers the ability to view videos on multiple devices, dedicated mobile device app, start viewing a video on one device and move it to another, and more. Player provides a number of additional features that you can use and customize to provide a rich and compelling video offering to your customers. PLAYER FOR CROSS-DEVICE RESUME (XDR) The Ooyala Player includes support for Cross-Device Resume (XDR) that enables you to provide a seamless video experience across multiple devices. Note: This topic applies to the HTML5 Player and the Flash Player. Cross-Device Resume (XDR) gives viewers the flexibility to start watching a video on one device and continue watching it on the same or different device at a later time, automatically resuming where the viewer left off. A secure server architecture is required. This architecture, REST API requests, and programmatic calls in JavaScript for Player v3, Objective C for the Ooyala Mobile SDK for ios, and Java for the Ooyala Mobile SDk for Android are fully detailed in Cross-device Resume (XDR). HTML5 PLAYER APPS FOR MICROSOFT WINDOWS 8 The Ooyala HTML5 Player includes support for the Microsoft Windows 8 OS that enables you to leverage the cross-device and cross-platform compatibility of HTML5 to provide your video and audio content across multiple devices from tablets to mobile phones. The Microsoft Windows 8 UI is a new design philosophy and application development platform that lets you build apps that conform to Windows 8 style principles. The Ooyala Player supports the embedding of Ooyala HTML5 players on devices that rely on the Windows 8 OS, featuring: Live Tile display with support for touchscreen actions on devices that support the feature. Quick intuitive user interactions and transitions. Support for multiple states. Windows 8 style apps support a full-screen, immersive state, and a minimal, snapped view that runs while a second app takes up the majority of screen space. Support for app contracts that provide a way for apps to work together. Flexible settings and user context that can roam via the cloud providing a continuous experience, regardless of where users sign in. The Player for HTML5 works with devices that support the Window 8 OS and HTML5. The Player does not support Flash players for Windows 8. This topic describes how to use the Player on Windows 8 devices. ABOUT THE WINDOWS 8 PLAYER APP The app that you create for Windows 8 will feature an HTML5 player that automatically expands to fullscreen mode when a user selects the app tile. You can set the player to not have UI controls (chromeless) and add your custom components to the player and app. One other aspect of developing a player app for Windows 8 is that if has a different method of distribution that is similar to what is done for ios and Android player apps. That is, when you create an app for Windows 8, you need to distribute it PLAYER DEVELOPER GUIDE PLAYER FEATURES AND APPS CUSTOMIZATION 78

79 through the Windows app store. For testing purposes, this means when you are in dev mode you cannot sideload your app in another device and test it. However, you can test by running the app in test mode in a simulator. Note: When you create your Ooyala player app for Windows 8 in Visual Studio, the project wizard will auto create a shell or template of a default.js file that has the boilerplate contents needed for this file. You will need to add your logic and perhaps tweak some of the boilerplate but much of it will be provided. Building a Player App with Win 8 Player support for Windows 8 gives you the ability to extend your content audience by taking advantage of this significantly new platform with your Player apps. How to Build a Player App for Windows 8 1. Download the Ooyala Player Windows 8 sample application. The package is available as a tar file: OOView.tgz. You can also see the OOView demo and inspect the source. 2. Download the Windows 8 Release Preview from Microsoft. 3. Download the Microsoft Visual Studio 2012 Express RC for Windows Set up your downloaded developer environment. 5. Open the Visual Studio project. 6. Open the Visual Studio Project link. 7. Open the following three files: default.html (local), default.js,player.html. Using the Default HTML File The default.html file provides the entry point for the application and the layout of the player app. The default.html file provides the entry point for the application and the layout of the player app. For a Window 8 app we use two different HTML files (default.html and player.html). In the default.html file you need to do the following: Within the player.html file: 1. Specify the div container and give it a div id. The div contains the app and the basic layout definition of the app. In this case the app is the player. 2. Place another container, the iframe within the pair of div tags. Specify an id or name for the iframe. 3. You specify the reference to the player inside the iframe container. WHAT IS IFRAME? The Windows 8 iframe works as a floating frame or container. You are able to access the contents of an iframe through a read or write to the elements within the iframe. For more information about the Windows 8 iframe, see the Iframe Element topic in the Microsoft Windows 8 UI Developer Guide. Since the Windows 8 model uses these separate sandboxes for apps, you need to be able to reference the player.html file or you will not be able to see a newly loaded player in the default.html because one file is local and the other remote. EXAMPLE: DEFAULT.HTML FILE In the following example, a div is created within a body tag and given the div id of playercontainer. Within a specified iframe container, the player.html file is referenced. This file contains the reference to the embedded player. <!DOCTYPE html> <html> PLAYER DEVELOPER GUIDE PLAYER FEATURES AND APPS CUSTOMIZATION 79

80 <head> <meta charset="utf-8" /> <title>ooview</title> <!-- WinJS references --> <link href="//microsoft.winjs.1.0.rc/css/ui-dark.css" rel="stylesheet" /> <script src="//microsoft.winjs.1.0.rc/js/base.js"></script> <script src="//microsoft.winjs.1.0.rc/js/ui.js"></script> <!-- OOView references --> <link href="/css/default.css" rel="stylesheet" /> <script src="/js/default.js"></script> </head> <body> <div id="playercontainer"> <iframe id="ooplayer" src="ms-appx-web:///player.html" width="100%" height="100%"></iframe> </div> </body> </html> Using the Default.js File The default.js file defines the DOM object handle and is auto-loaded at the beginning processing. The default.js file defines the DOM object handle and is auto-loaded at the beginning processing. When a user selects the app, the default.html file is loaded and all its references to other files. The default.js file is loaded next followed by the player.html file. The default html notifies the player.html that there is an action to perform and indicates that it should begin its actions. Windows 8 apps use a model, where each app is contained in a sandbox. This allows for much better control and prevents one app from affecting another. However, as a result of this model, you will need to provide a set of Web Services or other means of accessing remote data as if it were coming from a server on the web. In the default.js file you can post messages to the iframe container using a data-store to access remote data as if it were coming from a server on the web. // For an introduction to the Blank template, see the following documentation: // (function () { "use strict"; var app = WinJS.Application; var activation = Windows.ApplicationModel.Activation; WinJS.strictProcessing(); app.onactivated = function (args) { if (args.detail.kind === activation.activationkind.launch) { if (args.detail.previousexecutionstate!== activation. ApplicationExecutionState.terminated) { // TODO: This application has been newly launched. Initialize // your application here. app.ooplayer = document.getelementbyid('ooplayer'); app.ooplayer.contentwindow.postmessage({ eventtype: 'startapp', "ms-appx-web://" + document.location.host); else { // TODO: This application has been reactivated from suspension. // Restore application state here. PLAYER DEVELOPER GUIDE PLAYER FEATURES AND APPS CUSTOMIZATION 80

81 ; args.setpromise(winjs.ui.processall()); app.oncheckpoint = function (args) { // TODO: This application is about to be suspended. Save any state // that needs to persist across suspensions here. You might use the // WinJS.Application.sessionState object, which is automatically // saved and restored across suspension. If you need to complete an // asynchronous operation before your application is suspended, call // args.setpromise(). ; )(); app.start(); Using the Player HTML File The player.html file is where you implement the logic of the player and define how to interact with the UI elements of the player.js. You can think of the default.js as existing in a remote sandbox and the default.html in a local sandbox. They can t communicate with each other. If you use JavaScript to build your app and construct a script to directly affect the default html, you won t be able to unless you access the contents of the iframe as a remote container. The default.html is a local file and the default.js is loaded in a remote environment. Window 8 iframe lets you talk directly to the remote default.js file. Within the player.html file: 1. You provide the player branding id for your app. 2. You include a body tag and within it define the layout of the player and instantiate the player. 3. At the end of the page, you include the OO.ready function which indicates that the player is ready for playback. 4. You also include a receivemessage function to gather messages from the default.html console log. 5. You then can implement additional logic, if you want to add functionality. EXAMPLE: PLAYER.HTML FILE In the following example, we define the layout of the player and reference the css to style the player. In the body tag, we instantiate the player. <html> <head> <title>player V3 Demo</title> <script src=' </head> <body style=""margin:0; padding:0; background:black;"> <div id="playerwrapper" style="width: 100%; height:400px"></div> <div id="status" style="width:100%; height:50px; color:red;"> </div> <button id="playbutton" value="play" disabled="true">play</button> <button id="reloadbutton" value="play" disabled="true">change to new embed code</button> <script> // This app is based on a blog post from MS // /creating-a-windows-8-metro-slippy-map-application/ PLAYER DEVELOPER GUIDE PLAYER FEATURES AND APPS CUSTOMIZATION 81

82 // All logic is impleted in player.html for now var embedcodes = ["45cmZqNDrKn7TvtpfGa9k9fQSeyK4VaI", '1lM21wNDrCTF8nA4YaQibBh16vv4D8pM', "UxaXI5MzruPkO9medlrVQ9sZbgpqgMxr"]; var currentindex = 0; var oplayer = null; function onvideoplaying() { var status = document.getelementbyid("status"); status.innerhtml = "Playing"; function onplaybuttonclicked() { oplayer.play(); function onreloadbuttonclicked() { currentindex = (currentindex + 1) % embedcodes.length; oplayer.setembedcode(embedcodes[currentindex]); oplayer.play(); function createplayer(oo) { OO.$("#playerwrapper").html(''); var embedcode = embedcodes[currentindex]; oplayer = OO.Player.create('playerwrapper', embedcode, { width: '100%', height: '100%' ); oplayer.subscribe(oo.events.playing, "ie_iframe", onvideoplaying); OO.ready(function (OO) { var playbutton = document.getelementbyid("playbutton"); playbutton.disabled = false; playbutton.onclick = onplaybuttonclicked; ); var reloadbutton = document.getelementbyid("reloadbutton"); reloadbutton.disabled = false; reloadbutton.onclick = onreloadbuttonclicked; createplayer(oo); function receivemessage(e) { // Notification from default.html console.log("from parent", e.data); window.attachevent("onmessage", receivemessage); </script> </body> </html> PLAYER DEVELOPER GUIDE PLAYER FEATURES AND APPS CUSTOMIZATION 82

83 DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME Use our Chrome extension to help Ooyala debug video problems you might encounter. Ooyala offers a debugging/troubleshooting tool to help you gather information for Ooyala Technical Support about problems you might have with your HTML5 or Flash video player implementation. A summary of the steps is as follows: 1. You run the tool yourself to collect debugging details. In many cases, you can solve your problems yourself by looking at the debugging log. The tool bundles information into a URL and downloads logs and other debugging files. 2. You open a technical support request, supply the URL with the debugging information, and attach the saved logs to the request. 3. Ooyala technical support or engineering use the debugging information to help isolate the problem. SUPPORTED BROWSER: CHROME The debugging/troubleshooting tool works only in conjunction with Google Chrome. INSTALLING THE EXTENSION Download and install the extension from this link: When prompted to allow the tool access, click Add. MODES OF OPERATION: DEBUGGING YOUR OWN SITE The debugger has two modes: 1. Debug against values you enter on the site debug.ooyala.com. This mode is described in the majority of this document. 2. Debug your own player v3 site. This is described in Debugging Your Own v3 Site on page 85. BEFORE RUNNING THE TOOL You need the following details to run the debugger: The embed code (also called content ID or asset ID) of the problematic video. The player branding ID (or player ID) of the player in use when you encounter the issue. Advanced details (only if you use them) as described in Working with HTML5 or Advanced Settings on page 84. RUNNING THE TOOL To start the tool, click the Ooyala logo at the upper right of your browser window. PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 83

84 Note: By default, the debugger works with Ooyala Flash-based player. If you need to debug HTML5, see Working with HTML5 or Advanced Settings on page 84. Follow the onscreen steps. Use the Show Me buttons to orient yourself. Make note of where on your computer you download the HTTP archive (HAR) file and the player logs. You need to attach these files to the support request you might need to create. EXAMINING THE CONSOLE OUTPUT You can examine the output written to the console to isolate your problem. In many cases, you yourself will be able to isolate and solve your issues, independently from Ooyala technical support. As a start, look for error or warning messages. This is an example of a SEVERE log message, with the log line number to the left: 829 SEVERE >> Error Screen: removedcontent (content): error.content_unavailable - error.removed_content On the right of the console is a search field that supports regular expressions (regexps): Enter a search string (regular expression or otherwise). As you type, the occurrences of that string are filtered from the entire log and displayed. Many of the error messages that can occur are described in the following topics: Flash-based Player Error Messages HTML5-based Player Error Messages FILING A TICKET If the console messages are not helpful in isolating your problem, the final step of this process is for you to open a support request on Ooyala's Support Center. In addition to describing the issue, be sure to: Paste the link from the Get URL step into the request. Attach both the downloaded HAR file and the downloaded player logs. WORKING WITH HTML5 OR ADVANCED SETTINGS If you need to gather debug info for HTML5, click the Advanced tab. In the lower left, click the checkbox for Use HTML5 and follow the onscreen steps. You can set other advanced options on this tab: The player v3 version override. PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 84

85 The player v3 options hash. These are parameters passed in the third argument on the OO.Player.create() call. For example, the parameters height, width, and autoplay below are part of the options hash: var videoplayer = OO.Player.create('playerwrapper', 'embed_code', { height:100%, width:100%, autoplay:true,... ); Be sure to enter only the parameters and their values. No braces or other delimiters on the call are needed. DEBUGGING YOUR OWN V3 SITE The default site for debugging, debug.ooyala.com, is a "vanilla", generic implementation of Player v3 designed for simple debugging tasks and which does not cover all possible player v3 configurations and settings. For this reason, you might debug against the debug.ooyala.com site but not experience a problem you encounter on your own site. This is an indication that the problem is specific to your site. Therefore, it is sometimes essential to debug directly against your own site. This is easily done: 1. In your browser, bring up the suspect page that has player v3 embedded in it. 2. Open the Chrome Developer Tools as shown below. PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 85

86 3. Refresh your page if you are instructed to do so. 4. Click Ooyala Panel in the Developer Tools Panel. 5. In the Ooyala Flash Console, click Reload Page. 6. Play the problematic video. 7. If an issue occurs, click Save HAR File and Save Player Logs. 8. Follow the instructions above under Examining the Console Output on page 84 and Filing a Ticket on page 84. ISOLATING THE OOYALA PLAYER Any website that uses Ooyala's V3 code has a method OO.Player.isolate(). Using this method in your browser's JavaScript console, you can generate a "debug.ooyala.com" URL with an Ooyala Player, shown below. PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 86

87 This Player is configured as closely to your website as possible but isolated to our test site. When you have issues with your Ooyala Player, use isolate() to determine if the issue is due to the website environment, or issues with the Ooyala player itself. If you have multiple Ooyala Players on your website, you will have to specify which player to isolate by using OO.Player.isolate("div-id"). PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME 87

88 MIGRATING TO PLAYER V3 You can migrate from your legacy players to the Ooyala player. Migrating from your legacy player to the current Ooyala Player V3 can be fairly straightforward. This topic describes how to migrate your existing legacy player embed to the Ooyala Player V3 embed and event model. The new Ooyala Player was designed to have minimal impact on your existing set up. You can migrate your Flash player and custom modules in a fairly direct manner. Note:You can cut and paste your embed code from Backlot as you have done with prior players. If you use existing embed code callbacks and want to migrate to HTML5, you need to switch to using the message bus. Callbacks are not supported for the new embed style. They will continue to work for the Flash Player but not HTML5 Player. Migrating from Embed Code Callbacks If you use existing embed code callbacks and want to migrate to HTML5, you must switch to using the OnCreate embedded parameter. In Player V3,Callbacks are not invoked directly on the new embed style; instead, use the OnCreate parameter to specify the name of a callback function invoked when a player is created. DIFFERENCES BETWEEN PLAYER V3 AND PLAYER V2 The Ooyala player provides support for Flash playback with HTML5 fallback for a number of platforms. The following table describes the differences between the current Player V3 and the deprecated Player V2 (see V2 Player APIs (Player V2 Deprecated)). Player V3 Player V2 (Deprecated) Change from Player V2 to Player V3 JavaScript API (V3) only JavaScript API (V3) only (no ActionScript API) All interaction is done entirely in JavaScript API (V3) All player configuration is done through JavaScript API (V3). Flash Player supports YouTube videos, HTML5 currently player does not JavaScript API (V2) and Flash ActionScript API (V2 only) ActionScript API APIs and events tied DOM objects. Player configuration using query parameters Flash Player supports YouTube videos For more information, see HTML5 Player and Flash Player. JavaScript and Flash ActionScript APIs are unified. ActionScript APIs are no longer directly supported. If you want to embed the player within a Flash app, use prior player versions. They continue to work but you still interact with the embedded player through JavaScript. APIs and events are no longer tied to DOM objects. Some query parameters are still supported in Player v3. PLAYER DEVELOPER GUIDE MIGRATING TO PLAYER V3 88

89 WHY HTML5? The Ooyala player supports the new HTML5 standard for a wide array of devices. Supporting this standard offers increasing opportunities for expanding your video market and increasing monetization options. HTML5 is an emerging web standard that enables you to reach a wider audience on many different devices without having to re-code an app or web page for each device. Users don t have to install and reinstall the same app on their different devices. Important to video consumers, HTML5 includes support for video through a <video> tag. In addition to its HTML attributes, this video tag provides an extensive JavaScript API for controlling its content. The player supports both the HTML5 <video> tag and <flash> playback. If Flash is supported and present on a device, Player uses Flash. On mobile devices if Flash is not present or supported, the player uses HTML5. The Ooyala player not only enables you to take advantage of the benefits of HTML5, it also continues to support Flash players. Essentially, Player makes the best choice of player depending upon your device capabilities. You use the new embed style for both types of players. COMPARING EMBED CODE STYLES Before migrating from prior player versions, it will help to understand the difference between the embed code models. ELEMENTS OF THE EMBED CODE Before starting, it might help to review the elements of an embed code that you get from Backlot. Typically, your embed code is a URL that looks something like the following: <script src=" <div id='playercontainer'></div> The embed code is constructed of the following segments: This segment... protocol and domain player branding id div id Contains... You can use either http or https protocols. To use the player, you need to specify the /v3/ directory. You must add a valid player branding id after the protocol and domain. You need to do this as there is no single player; it is compiled specifically for the player id that you provide. This segment enables you to identify a specific named and styled player. When you specify a new player in Backlot and assign it some attributes, the named player is comprised of the player branding id and any additional assigned attributes. For more information see the topic Creating a Player in the Ooyala Support Center Backlot User Documentation and Creating a Player in the Ooyala Support Center Backlot Developer Documentation. The div id enables you to specify a unique id for the div tag. You can use this id to reference the player container in CSS or JavaScript files. Your id must be unique so that the reference to the div is correct. PLAYER DEVELOPER GUIDE MIGRATING TO PLAYER V3 89

90 CONSTRUCT AN EMBED CODE You can cut and paste your embed code from Backlot. For information about how to do this, see support.ooyala.com/users/documentation/tasks/publishing_manual_embed.html, If you are not be able to cut-and-paste your embed snippet into your web page, can construct the embed snippet manually. To do this: Start by providing the protocol and domain: Get the player-branding-id from Backlot. For example: <script src=' <'replace_with_player_branding_id'>'></script> Get the embed code from Backlot or you can get it via the getembedcode/setembedcode> API request. Before you begin migrating from prior player versions, it will help to understand the difference between the embed code models. The following examples show the difference between legacy player embed code and the current Player embed code. SIMPLE LEGACY PLAYER EMBED CODE With legacy Ooyala players, you referenced the player by providing a playerid parameter to the player. For example, you might specify 'myplayer' for the playerid. You then reference the player using the DOM element lookup $('#myplayer'). In these legacy players you reference the player object (player.js) and specify some customization attributes such as width and height using Ooyala query string parameters. In the following example this is followed by the actual embed code string that you obtain from Backlot or create manually. <script src=" width=<width>&height=<height> &embedcode=replace_with_embed_code></script> SIMPLE PLAYER EMBED CODE In contrast with prior legacy players, the current Ooyala Player enables you to reference the player object directly. To reference the current Ooyala Player equivalent of the legacy player.js, you just call the object returned from the OO.Player.create(). This object can be safely stored anywhere for future use. The following example illustrates the way that you create of a simple Ooyala Player. Note: To work, the URL " always requires a valid player branding id. <script src=" <div id='playercontainer'></div> <script> var myplayer = OO.Player.create('playerContainer', 'replace_with_embed_code', { width: <width>, height: <height> ); </script> PLAYER DEVELOPER GUIDE MIGRATING TO PLAYER V3 90

91 MIGRATING AN EXISTING EMBED CODE Migrating an existing embed code is straightforward in Player V3. To get started, you can copy an existing web page to test out the migration process. If you have many web pages or a site with multiple players, you may want to script the migration. To start migrating from a web page, you need to do the following: 1. Insert the correct DOCTYPE in your web page. 2. Set up your head tags and include the script tags around your existing load player statements. For example: <script src=" &embedcode=replace_with_embed_code"> </script> 3. Then add the <head> tags and the v3 path. Instead of the embed code information, you insert the player branding id (get this from Backlot). If your player is a Flash player, it will continue to work as always. The Player V3 will wrap the Flash player and playback continues to work as it normally does. <head> <!-- Load Ooyala Player --> <script src=' replace_with_player_branding_id'></script> </head> 4. Within the <body> tags, you will place the player in the <div> container and include your embed code information. In the following example, we have taken the size parameters and specified them in the <div> container. However, you can also specify the <div> container as one size and the actual video another size by adding additional parameters. <body> <!-- Player Placement --> <div id='playerwrapper' style='width:750px;height:312px;'></div> <script> var videoplayer = OO.Player.create('playerwrapper','replace_with_embed_code'); videoplayer.play(); </script> </body> 5. That is all you need to do to migrate to the new embed style. MIGRATION FAQ Frequently asked questions and answers about migrating to Player V3. The Ooyala Player introduces a new, more flexible and performant way to embed video in web pages. This means you will need to change your web page embed. This change affects all JavaScript embeds (regardless of whether you still use a Flash player or the HTML5 player). PLAYER DEVELOPER GUIDE MIGRATING TO PLAYER V3 91

92 Q: What is the new embed style? A: We are moving to an object-based embed style, similar to how other object-oriented frameworks (like jquery) work. Q: Why did we change the embed style? A: The new embed style is designed to provide better performance and cacheability. It supports multiple embeds on a page -- the player is not required to be separately loaded for each embed. It is more developer-friendly -- It conforms to the patterns that developers are used to and works better with typical website design. Q: Will the Player APIs change? A: The player APIs stay the same, but the way in which they are called will change based on the new embeds. We also added Backlot API v2s for HTML5 to bring them closer in parity to the current Flash Player APIs. Q: Will the event model change? A: Yes, we provide a message bus so that publishers / 3rd-party module creators can react and/or customize the player as much as needed. Q: Can I use my Flash Player with the current Ooyala Player? A: Yes. You can continue to use Flash. Player V3 provides a fallback mechanism such that if Flash is not available or is not supported on the device the HTML5 player is used. Otherwise Flash is used. Q: Can I continue to use ActionScript even if I embed my Flash player using the new Player? A: While your Flash player will continue to work, ActionScript calls are not supported. You interact with the Flash player object through JavaScript API requests. Q: What APIs can I use? A: The Ooyala Player features a set of JavaScript APIs that you can use to customize the player experience. These are described later in this document. PLAYER DEVELOPER GUIDE MIGRATING TO PLAYER V3 92