PLAYER DEVELOPER GUIDE

Transcription

1 PLAYER DEVELOPER GUIDE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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