Basic Tutorial for Player V4

This tutorial helps you begin working with Ooyala Player V4. You will construct an HTML page and add tags containing the logic required to customize, manage, and use Player V4.

Recommended Structure

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.

Basic Steps

See Complete Basic Example to view the code for the entire web page.

Note: Wherever you see url_where_hosted in sample code, replace this (in your code) with the URL that points to where the resource is hosted. The URL can point to a location on the same host (internal link) or on a separate host (prefixed with http:// or https://). If you host resources yourself, be sure to check for any path dependencies within the files.

Prerequisites

This tutorial assumes that you already have:
  • the latest player code downloaded from https://github.com/ooyala/html5-skin/releases and hosted properly
  • a Backlot account (you will need your pcode from that account)
  • at least one player defined in your Backlot account (you will need its Player ID)
  • at least one video asset associated with the player (you will need its Content ID)
For details, see Basic Embedding Information.

Step 1: Configure Font and Image Resources

Although not directly embedded into the HTML page, Ooyala player skin CSS requires font and image assets to render the skin properly.

Default Fonts and Images

By default, font resources are located in html5-skin/assets/fonts and image resources are located in html5-skin/assets/images. If you are hosting your own player resources, you must host the image and font resources as well for the player skin to render properly.

Custom Fonts

You can change the default fonts to any standard or custom font you prefer. Please note that these files must follow the same hosting procedures as all other player files (they must be CORS-enabled, as described in Cross-Origin Resource Sharing (CORS)). The following table shows what files to modify if you are loading your own font.
To update... Modify...
The default font location ($font-path: "assets/fonts") html5-skin/scss/base_variables.scss
Pointers to the font resources to load html5-skin/scss/base/_type.scss
Icons to display on the player skin skin.json

Custom Images

You can change the default player images to any images you prefer. Please note that these files must follow the same hosting procedures as all other player files (they must be CORS-enabled, as described in Cross-Origin Resource Sharing (CORS)).

If you use different images than those specified in html5-skin/assets/image, be sure to update pointers to these images.

Step 2: Create a Simple Web Page

Start by creating an empty HTML5 web page. Be sure to specify the <!DOCTYPE html> declaration:
<!DOCTYPE html>
<html>

  <head>
    <title>My Test Player V4 Web Page</title>
  </head>
  
  <body>
      <!--My Player V4 Content-->
  </body>
  
</html>
Note: Use the <!DOCTYPE html> declaration on HTML5 pages to ensure that browsers can render the content correctly. Windows IE9 is particularly strict and might not render the page properly if this declaration is omitted.

Step 3: Load Required and Optional Plugins

The head tag is the section of the web page where you initialize the Ooyala Player, along with any custom plugins you would like to use (see Hosting Player V4 Resources for instructions on hosting Player resources) . The advantage to loading the player within the head tag is that the player loads before the rest of the web page loads, ensuring that 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. The following plugins are required for the player to load properly:
  • core.min.js
  • at least one video plugin (see Loading Video Plugins for details on how to load video plugins)
If you want to load the Ooyala player skin, you should also load main_html5.min.js, html5-skin.min.js, and html5-skin.min.css. All other plugins are optional (omitting plugins you don't need results in faster load times).

Within the head tag, create a <script> tag with a src attribute that makes the request to load the core.min.js, main_html5.min.js, html5-skin.min.js, and html5-skin.min.css files.

<head>
  <title>My Test Player V4 Web Page</title>

  <!-- V4 JS core is required. Plugins such as discovery and advertising need to be loaded separately -->
  <script src="url_where_hosted/core.min.js"></script>
  <!-- A Video Plugin is required. This example shows the Main Video Plugin -->
  <script src="url_where_hosted/main_html5.min.js"></script>
  
  <!-- Change these html5-skin.min.css and html5-skin.js to your local build if necessary -->
  <script src="url_where_hosted/html5-skin.min.js"></script>
  <link rel="stylesheet" href="url_where_hosted/html5-skin.min.css"/>
</head>

You may also specify any third-party or custom plugins that you would like to load by including additional <script> tags, each having a src attribute specifying a path to a custom plugin. Available plugins for this release include (but are not limited to) the Player skin, ad plugins, and Discovery.

Note: You must include the appropriate plugins in order for the player to have the desired functionality. For example, if you do not add the Discovery plugin here, the Discovery functionality will not work for your player. Similarly, if you do not add the FreeWheel plugin here, the FreeWheel ad functionality will not work for your player.
<head>
  <title>My Test Player V4 Web Page</title>

  <!-- Load Ooyala Player -->
  <script src="url_where_hosted/core.min.js"></script>

  <!-- A Video Plugin is required. This example shows the Main Video Plugin -->
  <script src="url_where_hosted/main_html5.min.js"></script>

  <!-- Change these html5-skin.min.css and html5-skin.js to your local build if necessary -->
  <script src="url_where_hosted/html5-skin.min.js"></script>
  <link rel="stylesheet" href="url_where_hosted/html5-skin.min.css"/>

  <!-- Load additional plugins -->
  <script src="url_where_hosted/discovery_api.min.js"></script>
</head>

Step 4: Set up the Player Layout in the UI

Next, you begin to work within the body element.

Start by specifying 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. The <div> element requires a unique DOM ID, which you specify in its id attribute (container in this example). You will use this div id later to reference the loaded player.

<body>
    <!--My Player V4 Content.-->
    <div id="container" style="width:640px; height:360px;"></div>
</body>
Note: The HTML standard requires that each div id must be unique.

Step 5: 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. 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 container.

Wrap the call to OO.Player.create() within the OO.ready() method to ensure that the script is initialized and loaded.

When you call OO.Player.create(), you will pass in the following parameters:
  • ID of the div element to which to attach the player object
  • Asset ID for the video. An asset ID is the same as a ContentID (in the Backlot UI) and an embed_code (in the Player V4 JavaScript API). See Basic Embedding Information for details.
  • pcode and Player branding ID for the player (required). See Basic Embedding Information for details. If you do not include these parameters, the player will not load. These parameters are used for Discovery and analytics purposes. In the example below, the pcode and Player ID are defined in the playerParam variable. We recommend that you use this approach to load these parameters.
  • skin parameter (always required if you want to use the Ooyala default player skin), which references the skin.json config file. This loads the player skin.
  • Embedded player parameters. Add these parameters in the playerParam variable. These can be used to customize player ads and behavior, and can determine player styles.
<script>
  var playerParam = {
    "pcode": "YOUR_PCODE",
    "playerBrandingId": "YOUR_PLAYER_ID",
    "skin": {
      // config contains the configuration setting for player skin. Change this path to your local config when necessary.
      "config": "url_where_hosted/skin.json"
    }
      // Add other embedded player parameters here.
  };
  // Surround everything with OO.ready to make sure the script has loaded and initialized.
  OO.ready(function() {
    window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
  });
</script>
Note: To destroy a player, call the OO.Player.destroy() method.

Complete Basic Example

You now have a complete working example of a basic web page that loads the Ooyala Player V4 with default settings, renders it according to the layout specified in the <div> container, and creates the player. In the example below, items in bold must be modified for the example to play a video.

Wherever you see url_where_hosted in sample code, replace this (in your code) with the URL that points to where the resource is hosted. The URL can point to a location on the same host (internal link) or on a separate host (prefixed with http:// or https://). If you host resources yourself, be sure to check for any path dependencies within the files.

<!DOCTYPE html>
<html>
    <head>
        <title>My Test Player V4 Web Page</title>
        
        <script src="url_where_hosted/core.min.js"></script>
        
        <script src="url_where_hosted/main_html5.min.js"></script>
        <script src="url_where_hosted/discovery_api.min.js"></script>
        
        <script src="url_where_hosted/html5-skin.min.js"></script>
        <link rel="stylesheet" href="url_where_hosted/html5-skin.min.css"/>
    </head>
    <body>
        <div id="container" style="width:640px; height:360px;"></div>
        <script>
            var playerParam = {
              "pcode": "YOUR_PCODE",
              "playerBrandingId": "YOUR_PLAYER_ID",
              "skin": {
                // Config contains the configuration setting for player skin. Change to your local config when necessary.
                "config": "url_where_hosted/skin.json"
              }
            };
            OO.ready(function() {
              window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
            });
        </script>
    </body>
</html> 

Was this article helpful?