PLAYER DEVELOPER GUIDE

Transcription

1 PLAYER DEVELOPER GUIDE

2 CONTENTS MANAGING PLAYERS IN BACKLOT 5 Player V3 Platform and Browser Support (Deprecated) 5 How Player V3 Works (Deprecated) 6 Setting up Players Using the Backlot REST API (Deprecated) 6 Creating a Player Using the Backlot REST API 7 Editing a Player Using the Backlot REST API 8 Deleting a Player Using the Backlot REST API 10 BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 12 Advanced Layout: Embedding Multiple Players (HTML5 Player V3) (Deprecated) 16 Creating an HTML5 Player 19 Creating an HTML5 Player with an External Id 20 Advanced: Destroying an HTML5 Player V3 (Deprecated) 21 DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 25 Customizing an HTML5 Player V3 With CSS (Deprecated) 25 CSS Class Names in Player V3 (Deprecated) 27 Overriding Default Styles with CSS in Player V3 (Deprecated) 29 Linking to the CSS in Player V3 (Deprecated) 30 Styling the DIV Container with External CSS in Player V3 (Deprecated) 30 Referencing the DIV Container by DIV Id in Player V3 (Deprecated) 31 Styling Player V3 with Inline CSS (Deprecated) 32 Embedding an HTML5 Player V3 in an HTML iframe (Deprecated) 33 PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 35 Advanced JavaScript Examples for Player V3 (Deprecated) 35 Loading the Player and Custom Modules in HEAD 35 Organizing the BODY 36 Event Model for HTML5 Player V3 (Deprecated) 39 Event Publish and Subscribe in Player V3 (Deprecated) 40 Message Bus API in Player V3 (Deprecated) 41 Listening to a Message Bus Event in Player V3 (Deprecated) 41 Writing to the Message Bus in Player V3 (Deprecated) 46 Listening to Multiple Message Bus Events in Player V3 (Deprecated) 51 Advanced Event Handling in Player V3 (Deprecated) 54 Integrating Ads in HTML5 Player V3 Using JavaScript (Deprecated) 54 Assigning Ad Sets Dynamically in Player V3 (Deprecated) 55 Assigning an Ad Set with OO.Player.create in Player V3 (Deprecated) 55 Assigning Ad Sets with setembedcode in Player V3 (Deprecated) 56 Ad-related Events in Player V3 (Deprecated) 56 Customizing Assets for HTML5 Player V3 Using JavaScript (Deprecated) 57 Programming Bitrates and Buffering for Flash Player V3 Using JavaScript (Deprecated) 58 Programming Closed Captioning in Player V3 Using JavaScript (Deprecated) 63 Handling Errors for an HTML5 Player V3 Using JavaScript (Deprecated) 64 Localizing a Flash or HTML5 Player V3 Using JavaScript (Deprecated) 66 Programming Parameters for Player V3 Using JavaScript (Deprecated) 68 PLAYER DEVELOPER GUIDE TOC 2 SALES@OOYALA.COM OOYALA

3 Query String Parameters in Player V3 (Deprecated) 68 Enabling HLS Playback on Android Web in Player V3 (Deprecated) 69 Setting Autoplay in a Parameter Hash Tag in Player V3 (Deprecated) 70 Setting the Default Video Platform with a Parameter in Player V3 (Deprecated) 71 Hiding the Control Bar for Ad Playback in a Parameter Hash Tag in Player V3 (Deprecated)71 Show or Hide Ad Marquee During Ad Playback in Player V3 (Deprecated) 72 Adding a TV Rating Watermark to a Flash Player V3 (Deprecated) 72 Toggling the Display of Cue Point Markers in Player V3 (Deprecated) 75 Embedded Parameters in Player V3 (Deprecated) 75 Player V3 Embedded Parameters for Ads (Deprecated) 76 DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 78 PLAYER V3 FEATURES AND APPS CUSTOMIZATION 83 Player V3 for Cross-Device Resume (XDR) 83 HTML5 Player V3 Apps for Microsoft Windows 8 (Deprecated) 83 Building a Player V3 App with Win 8 (Deprecated) 84 Using the Default HTML File in Player V3 (Deprecated) 84 Using the Default.js File in Player V3 (Deprecated) 85 Using the Player V3 HTML File (Deprecated) 86 DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME IN PLAYER V3 (DEPRECATE 89 MIGRATING FROM PLAYER V2 TO PLAYER V3 (DEPRECATED) 93 Differences Between Player V3 and Player V2 (Deprecated) 93 Why HTML5? (Deprecated) 94 Comparing Embed Code Styles in Player V3 and Player V2 (Deprecated) 94 Migrating an Existing Embed Code to Player V3 (Deprecated) 96 Player V3 Migration FAQs (Deprecated) 97 PLAYER DEVELOPER GUIDE TOC 3 SALES@OOYALA.COM OOYALA

4 COPYRIGHT NOTICE All contents of the Ooyala website and Services are: Copyright Ooyala, Inc All rights reserved. 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. Ooyala and Backlot are registered trademarks of Ooyala, Inc. in the United States, Japan, and European Community. For complete information on terms of service, see: All other trademarks are the property of their respective companies. This content was last updated on 2018-Jan-03. PLAYER DEVELOPER GUIDE COPYRIGHT NOTICE 4

5 MANAGING PLAYERS IN BACKLOT Describes how to create and configure Ooyala players using the Backlot UI. You can use the Backlot UI to create and configure an Ooyala player. PLAYER V3 PLATFORM AND BROWSER SUPPORT (DEPRECATED) Player V3 provides support for Flash playback, HTML5 playback, and Flash playback (with HTML5 fallback) for a number of platforms. HTML5 PLAYER V3 - SUPPORTED BROWSERS HTML5 Player V3 works with the following browsers on all Ooyala supported devices: Browser Chrome Player Support Flash and HTML5 playback (MP4) Firefox Firefox v 38+: Flash playback with HTML5 fallback (MP4) Prior Firefox versions: Flash playback only Internet Explorer (9+) Microsoft Edge (Windows 10) Safari Flash and HTML5 playback (MP4) Note: Internet Explorer v8-v10 does not support true fullscreen mode in JavaScript. Fullscreen support is enabled in IE11 and later. Flash and HTML5 playback (MP4). Flash and HTML5 playback (MP4 and HLS). Note: Per the Apple Support Team, Apple has blocked older versions of Flash Player (versions prior to and ) in Safari. HTML5 PLAYER V3 - SUPPORTED PLATFORMS Windows Desktop - Windows 10, Windows 8, Windows 7; Internet Explorer v9+, Microsoft Edge for Windows 10 OS X v10.5+ Android v2.3+ (recommend running in Chrome rather than in the pre-installed browser) ios v7+ Note: Support for the HTML5 player on Windows 8 phones and tablets will be available in a future release. PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 5

6 SUPPORTED PLATFORMS FOR FLASH PLAYER V3 (DESKTOP ONLY) Windows Desktop Microsoft Edge (Windows 10) Windows 8 (Internet Explorer 9+ only) - Metro Mode (if website is whitelisted), or Classic Mode Windows 7 Mac Desktop OS X 10.5 or greater Firefox, Chrome, Safari HOW PLAYER V3 WORKS (DEPRECATED) Player V3 provides a simple way to embed video in web pages. Player V3 uses an object-based embed style that works in a similar way as other object-oriented frameworks (like jquery). It differs from how you embed video in web pages using earlier versions of our player (see Comparing Embed Code Styles in Player V3 and Player V2 (Deprecated) on page 94). 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 REST API (DEPRECATED) You can use the Backlot API to perform changes to the Ooyala player. PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 6

7 CREATING A PLAYER WITH THE BACKLOT API Note: Topics related to creating and deleting players apply to the Player V4, HTML5 V3 Player, and the Flash V3 Player. PLAYER BRANDING WITH THE BACKLOT API Ooyala Backlot branding tools enable you to add or remove player functionality, add social sharing features, brand it with your logos, and change color schemes. Creating a Player Using the Backlot REST API You can create as many players as you like and assign them to videos, channels, or channel sets. Note: For more information about REST API commands for the Ooyala player, see the Backlot API Reference. 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. Note: Player sharing settings with the Backlot API are only valid for Ooyala Player V3. Customize Player V4 sharing settings by modifying skin.json or the player CSS. [POST]/v2/players{ "name":"social Player", "ooyala_branding":{ "show_share_button":true, "twitter_sharing":true, "facebook_sharing":true, "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, PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 7

8 "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. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. The player is successfully added. Editing a Player Using the Backlot 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. Note: For more information about REST API commands for the Ooyala player, see the Backlot API Reference. 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, PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 8

9 "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", "default_closed_caption_language":"" Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with 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":{ PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 9

10 "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":"", "watermark":{ "image_url":null, "click_url":null, "alpha":1.0 Note: Try out the code samples using your account credentials in the Ooyala Scratchpad. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. The player is successfully edited. Deleting a Player Using the Backlot 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. Note: For more information about REST API commands for the Ooyala player, see the Backlot API Reference. To delete a player: PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 10

11 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. To launch the Scratchpad, go to Ooyala API Scratchpad. For information about using the Scratchpad, see Practice Making Requests with the Scratchpad. The player is successfully deleted. PLAYER DEVELOPER GUIDE MANAGING PLAYERS IN BACKLOT 11

12 BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) Use this tutorial to get started using the HTML5 Player V3. This tutorial helps you begin working with the Ooyala HTML5 Player V3. 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 12 Step 2: Load Your Ooyala V3 Player on page 12 Step 3: Set up the Player Layout in the UI on page 14 Step 4: Create and Embed Your Player on page 14 See Complete Basic Example on page 15 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 PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 12

13 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. 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 Managing Players Using the Backlot REST API. 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=' PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 13

14 <!-- Load additional custom modules --> <script src='/custom_module_name.js'></script> </head> 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, the autoplay parameter to true so that the asset (video or audio) plays automatically upon loading. The width and height settings are set to 100% so that, in a responsive design environment, the player automatically resizes to fill the amount of space in the parent container. For more information, see Player V3 Embedded Parameters (Deprecated). You can also specify Player V3 Embedded Parameters for Custom Modules (Deprecated). <script> // Surround everything with OO.ready to make sure the script has // loaded and initialized. OO.ready(function() { PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 14

15 window.player = OO.Player.create( 'playerwrapper', 'hkbtd2czriyrs4-hnj9nvchsxta07fuk', { // add the embedded player parameters here autoplay: true height: 100% width: 100% ); ); </script> Note: To destroy a player, call the OO.Player.destroy() method. For examples and additional detail, see Advanced JavaScript Examples for Player V3 (Deprecated) on page 35. 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 height: 100% width: 100% ); ); </script> </body> </html> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 15

16 ADVANCED LAYOUT: EMBEDDING MULTIPLE PLAYERS (HTML5 PLAYER V3) (DEPRECATED) 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. Follow these steps to build your web page: Step 1: Load Multiple Player V3 Instances on page 16 Step 2: Set up the Layout in the UI on page 17 Step 3: Create the Players on page 17 See Complete Example on page 18 to view the code for the entire web page. STEP 1: LOAD MULTIPLE PLAYER V3 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 V3 (Deprecated) on page 12, 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> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 16

17 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 V3 Query String Parameters (Deprecated). 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 V3 (Deprecated) on page 12, 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 <!-- 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 V3 (Deprecated) on page 12, 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() { PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 17

18 // 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', {); ); </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 PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 18

19 <!-- 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> 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> PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 19

20 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... ); </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. PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 20

21 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> ADVANCED: DESTROYING AN HTML5 PLAYER V3 (DEPRECATED) 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 22 Step 2: Destroying the Player on page 22 See Complete Example on page 23 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 V3 (Deprecated) on page 12. To learn about event handling, see Event Model for HTML5 Player V3 (Deprecated) on page 39. For a list of all events, see the Player JavaScript API Reference. PLAYER DEVELOPER GUIDE BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 21

22 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 V3 (Deprecated) on page 39 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 BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 22

23 */ /* 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 BASIC TUTORIAL FOR THE HTML5 PLAYER V3 (DEPRECATED) 23

24 </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> 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 V3 (DEPRECATED) 24

25 DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) Ooyala provides many options for customizing the appearance and functionality of an HTML5 Player V3 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 V3 JavaScript API Reference (Deprecated). The HTML5 player gives you three options for customization: CUSTOMIZING AN HTML5 PLAYER V3 WITH CSS (DEPRECATED) You can customize your HTML5 Player V3 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: PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 25

26 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 V3 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 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. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 26

27 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. CSS CLASS NAMES IN PLAYER V3 (DEPRECATED) 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. For information about linking your styles when you embed the player, see Linking to the CSS in Player V3 (Deprecated) on page 30. 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 PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 27

28 CSS Class Name Ancilliary Classes Description.oo_controls.oo_currentTime.oo_timeToLive.oo_duration.oo_toolbar_item.oo_button_highlight.oo_playhead.live.oo_controls_inner.oo_label.oo_scrubber.oo_playhead.oo_scrubber_track 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 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.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 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) PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 28

29 CSS Class Name Ancilliary Classes Description.oo_fullscreen_off.oo_live_indicator.oo_live_message 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 OVERRIDING DEFAULT STYLES WITH CSS IN PLAYER V3 (DEPRECATED) 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 CSS Class Names in Player V3 (Deprecated) on page 27. 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: PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 29

30 To make your sure custom CSS file gets loaded in the player, see Linking to the CSS in Player V3 (Deprecated) on page 30 LINKING TO THE CSS IN PLAYER V3 (DEPRECATED) You can customize your Player V3 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: 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 IN PLAYER V3 (DEPRECATED) 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 PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 30

31 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> <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 IN PLAYER V3 (DEPRECATED) You can reference the DIV container by its DIV Id. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 31

32 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 PLAYER V3 WITH INLINE CSS (DEPRECATED) You can style Player V3 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. 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;', PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 32

33 EMBEDDING AN HTML5 PLAYER V3 IN AN HTML IFRAME (DEPRECATED) 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 docurl 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. 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. PLAYER DEVELOPER GUIDE DESIGNING THE SKIN FOR AN HTML5 PLAYER V3 (DEPRECATED) 33

34 Parameter platform options Description of Value Any of the defined values for the platform parameter detailed at Player V3 Query String Parameters (Deprecated), 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 V3 (DEPRECATED) 34

35 PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 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 V3 and the Flash Player V3. 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 V3 (DEPRECATED) 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 V3 and the Flash Player V3. This section provides quickstart tutorials with advanced Player JavaScript examples. For a more basic tutorial, see Basic Tutorial for the HTML5 Player V3 (Deprecated) on page 12. 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 in Player V3 (Deprecated) on page 68 to the Player initialization call, and load additional JavaScript modules within the <head> element.... <head> <title>my Test Player V3 Web Page </title> PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 35

36 <!-- 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> 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 37 for more information. 3. Asset information retrieved via listeners and method calls. See Information with Listeners and Method Calls on page 37 for more information. 4. The logic required for Playing the Video on page 38. 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 37).... <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> PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 36

37 <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>... 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 V3 Using JavaScript (Deprecated) 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.. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 37

38 .. // 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/>" 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 Player V3 Embedded Parameters (Deprecated). You can also specify Player V3 Embedded Parameters for Custom Modules (Deprecated). PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 38

39 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', { // 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 V3 (DEPRECATED) The HTML5 Player V3 incorporates the use of a message bus to handle events. Note: This section applies to the HTML5 Player V3 but not the Flash Player V3. 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 39

40 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. Event Publish and Subscribe in Player V3 (Deprecated) 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) {); PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 40

41 OO.Player.create('playerwrapper',embedCode, { oncreate: window.oncreate ); Message Bus API in Player V3 (Deprecated) 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 in Player V3 (Deprecated) 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. 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 V3 (Deprecated) on page 12. To learn about event handling, see Event Model for HTML5 Player V3 (Deprecated) on page 39. 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 41

42 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 V3 (Deprecated) on page 39 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: 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) PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 42

43 ); 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. * * 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(); PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 43

44 ); 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=" <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 DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 44

45 */ 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, '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..."); /* PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 45

46 * 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 in Player V3 (Deprecated) Use the publish() function to write to the message bus, setting parameters as needed. To write to the message bus, use the publish() function. 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 V3 (Deprecated) on page 12. To learn about event handling, see Event Model for HTML5 Player V3 (Deprecated) on page 39. 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 46

47 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 V3 (Deprecated) on page 39 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.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/> PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 47

48 <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> 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 48

49 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 (Deprecated). 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', '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> PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 49

50 </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', '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. --> PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 50

51 </body> </html> <button id="swapbutton">swap to Fullscreen</button> Listening to Multiple Message Bus Events in Player V3 (Deprecated) 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 V3 (Deprecated) on page 12. To learn about event handling, see Event Model for HTML5 Player V3 (Deprecated) on page 39. 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. 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 V3 (Deprecated) on page 39 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, PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 51

52 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) { */ /* 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 DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 52

53 */ 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> </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, PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 53

54 * 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 in Player V3 (Deprecated) 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. INTEGRATING ADS IN HTML5 PLAYER V3 USING JAVASCRIPT (DEPRECATED) 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 54

55 ios-based devices support only pre- and post roll positions. Assigning Ad Sets Dynamically in Player V3 (Deprecated) 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 in Player V3 (Deprecated) Player V3 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 set up 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. Note: The ad set code identifier is not available by default for security reasons. Please contact your Customer Success Manager or Technical Support to enable this feature for your account. 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 V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 55

56 width:'100%', adsetcode:'youradsetcode' ); <script> Assigning Ad Sets with setembedcode in Player V3 (Deprecated) 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 in Player V3 (Deprecated) on page 55. 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 in Player V3 (Deprecated) Several ad-related events are exposed on the Player V3 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 65 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 56

57 CUSTOMIZING ASSETS FOR HTML5 PLAYER V3 USING JAVASCRIPT (DEPRECATED) Customize assets using the Player V3 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. 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 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 57

58 Event METADATA_FETCHED AUTHORIZATION_FETCHED PLAYBACK_READY PLAYHEAD_TIME_CHANGED PLAYING PLAY_FAILED PAUSED PLAYED Published 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). 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 PLAYER V3 USING JAVASCRIPT (DEPRECATED) 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 Flash Player V3. See the example code in Information with Listeners and Method Calls on page 37. 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() set Methods settargetbitrate(bitrate) settargetbitratequality() PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 58

59 get Methods getbitrateinfo() set Methods 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) X <= 0 "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" "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() PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 59

60 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 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() PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 60

61 -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 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 61

62 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 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 62

63 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. PROGRAMMING CLOSED CAPTIONING IN PLAYER V3 USING JAVASCRIPT (DEPRECATED) 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: PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 63

64 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: 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 V3 USING JAVASCRIPT (DEPRECATED) Error Handling functions and events enable you to get information about Player V3 Player V3 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 64

65 Function Description LOADING READY PLAYING PAUSED BUFFERING ERROR DESTROYED PLAYER V3 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 V3 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: PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 65

66 <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.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 V3 (Deprecated) on page 35. LOCALIZING A FLASH OR HTML5 PLAYER V3 USING JAVASCRIPT (DEPRECATED) You can localize your player user interface using Ooyala Player V3 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; PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 66

67 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 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 67

68 Language String Player Support 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 PROGRAMMING PARAMETERS FOR PLAYER V3 USING JAVASCRIPT (DEPRECATED) 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 in Player V3 (Deprecated) 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 39. platform=( flash-only flash html5-fallback html5-priority ) Use the platform parameter to control the selection mechanism between Flash and HTML5 playback. See details in Setting the Default PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 68

69 Parameter tweaks=android-enablehls Description Video Platform with a Parameter in Player V3 (Deprecated) on page 71. 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 Player V3 Embedded Parameters for Ads (Deprecated) on page 76. Enabling HLS Playback on Android Web in Player V3 (Deprecated) 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 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. Playback as expected. Potential PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 69

70 Android Version Ooyala VoD Ooyala Live Streaming rendering issues with player controls. 4.1 Optimal playback experience. Some potential rendering issues with player controls 4.2 Optimal playback experience. 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 in Player V3 (Deprecated) 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 after an option hash tag. A usergenerated event should originate from the actual device user. On ios (iphone) it is not recommended to trigger autoplay since the video will immediately go into full screen mode in the native video player. It is recommended on mobile web to set autoplay to false (the default). Note: Facebook does not allow autoplay of videos by third party players inside the Facebook feed. Therefore, autoplay settings will be ignored when the player is embedded on Facebook. 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 PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 70

71 Setting the Default Video Platform with a Parameter in Player V3 (Deprecated) 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 in Player V3 (Deprecated) 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 V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 71

72 ); Show or Hide Ad Marquee During Ad Playback in Player V3 (Deprecated) 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 V3 (Deprecated) 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 V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 72

73 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 V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 73

74 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 V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 74

75 ); Toggling the Display of Cue Point Markers in Player V3 (Deprecated) 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, Embedded Parameters in Player V3 (Deprecated) 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 V3 Query String Parameters (Deprecated). Parameter enablechannels initialtime locale encodingpriority 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. Configuration parameter used to determine which of the supported plugins and encodings to use. Valid values are: hls mp4 webm rtmp audio smooth faxs_hls wv_hls wv_wvm PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 75

76 Parameter Player V3 Embedded Parameters for Ads (Deprecated) on page 76 Description wv_mp4 hds akamai_hd_vod akamai_hd2_vod_hls akamai_hd2_vod_hds dash Pass ad server tags to the Ooyala player. Player V3 Embedded Parameters for Ads (Deprecated) 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. Parameter in-stream 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. freewheel-adsmanager google-ima-adsmanager liverail-adsmanager vast 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. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 76

77 Parameter vpaid-adsmanager Description Pass VPAID Ad Manger tags to the Ooyala player. For more information, see the VPAID Ads Embedded Parameters reference topic. PLAYER DEVELOPER GUIDE PLAYER V3 JAVASCRIPT API PROGRAMMING (DEPRECATED) 77

78 DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 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. */ PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 78

79 // load jquery UI lib and css: var Sample = {; $('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), PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 79

80 , slide: _.bind(this.onslide, this) ); this.playbutton = this.rootelement.find('.playbutton'); 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"); PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 80

81 , if (this.playing) { this.pause(); 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> PLAYER DEVELOPER GUIDE DEVELOPING CUSTOM CLIENT MODULES FOR HTML5 PLAYER V3 (DEPRECATED) 81

82 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 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 V3 (DEPRECATED) 82

83 PLAYER V3 FEATURES AND APPS CUSTOMIZATION You can incorporate and customize many of the Player V3 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 V3 provides a number of additional features that you can use and customize to provide a rich and compelling video offering to your customers. PLAYER V3 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 V3 APPS FOR MICROSOFT WINDOWS 8 (DEPRECATED) 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. PLAYER DEVELOPER GUIDE PLAYER V3 FEATURES AND APPS CUSTOMIZATION 83

84 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 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 V3 App with Win 8 (Deprecated) 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 in Player V3 (Deprecated) 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: PLAYER DEVELOPER GUIDE PLAYER V3 FEATURES AND APPS CUSTOMIZATION 84

85 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> <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 in Player V3 (Deprecated) 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. PLAYER DEVELOPER GUIDE PLAYER V3 FEATURES AND APPS CUSTOMIZATION 85

86 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. 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 V3 HTML File (Deprecated) 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 PLAYER DEVELOPER GUIDE PLAYER V3 FEATURES AND APPS CUSTOMIZATION 86

87 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/ // 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%', PLAYER DEVELOPER GUIDE PLAYER V3 FEATURES AND APPS CUSTOMIZATION 87

88 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 V3 FEATURES AND APPS CUSTOMIZATION 88

89 DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME IN PLAYER V3 (DEPRECATED) 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 91. 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 90. 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 IN PLAYER V3 (DEPRECATED) 89

90 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 90. 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 V3 Error Messages (Deprecated) HTML5-based Player V3 Error Messages (Deprecated) 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 IN PLAYER V3 (DEPRECATED) 90

91 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. 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 90 and Filing a Ticket on page 90. PLAYER DEVELOPER GUIDE DEBUGGING/TROUBLESHOOTING EXTENSION FOR CHROME IN PLAYER V3 (DEPRECATED) 91

92 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. 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 IN PLAYER V3 (DEPRECATED) 92