Embedded Parameters for Player V4

You can pass embedded parameters to the OO.Player.create() method. These parameters include CSS style settings such as width and height, and other parameters such as tags from your ad server or ad network account used for advanced ad tracking and targeting.

Required Parameters
Note: To specify ad embedded parameters for Ooyala Pulse, Google IMA, VAST, VPAID, and FreeWheel, see Configuring Ad Parameters.

As you can see in the example below, you will add embedded parameters at the page level when you create a player.

<!DOCTYPE html>
<html>
    <head>
        <title>My Test Player V4 Web Page</title>
        <!-- V4 JS core is required. Plugins such as skin, 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>
    <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"
              }

             // Add Optional Embedded Parameters Here

            };
            OO.ready(function() {
              window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
            });
        </script>
    </body>
</html>

Syntax for Embedded Parameters

  • Enclose parameter names in double quotes ("). Example: "autoplay"
  • Enclose string values in double quotes. Example: "pcode": "YOUR_PCODE"
  • Omit quotes for Boolean values and numbers. Example: "autoplay": false
  • For non-string parameter values, refer to the parameter example. Example: "initialTime": 10

Required Parameters

The following are required embedded parameters, represented as key value pairs, that you must use when creating a V4 player.

pcode

The pcode is your account identifier. This is an alphanumeric string that precedes the period in your API key. You can get your pcode from your API keys. If you do not include your pcode, the player will not load.

Example:

<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>

playerBrandingId

The player branding ID is a reference to your player. You can get your player branding ID (referred to as the Player ID in Backlot) by going to the MANAGE tab > Embed subtab in Backlot. If you do not include your player branding ID, the player will not load.

Example:

<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>

skin.config

The skin parameter (always required if you want to use the Ooyala default player skin) references the skin.json config file. This loads the player skin.

Example:

<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>

Optional Parameters

The following are optional embedded parameters, represented as key value pairs, that you may use with the OO.Player.create() method.

adManagerLoadTimeout

Specify the timeout (in seconds) for the loading of the Ad Manager module. The default is 3 seconds. To assist with ad-fill rate issues related to timeout settings, you can increase this value (for example, 4 or 5 seconds, depending on your page setup and load time).

Type: number

Example:

<div id="container" style="width:640px; height:360px;"></div>
<script>
    var playerParam = {
        "pcode": "YOUR_PCODE",
        "playerBrandingId": "YOUR_PLAYER_ID",
        "adManagerLoadTimeout": 5,
        "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>

autoplay

Enables the automatic playing of an asset (video or audio) upon loading. This is useful for UIs that do not have play/pause controls or conditions where you want the content to play immediately.

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 user-generated 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.

Type: Boolean

Example:

<div id="container" style="width:640px; height:360px;"></div>
<script>
    var playerParam = {
        "pcode": "YOUR_PCODE",
        "playerBrandingId": "YOUR_PLAYER_ID",
        "autoplay": true,
        "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>

encodingPriority

Use this parameter to define the video encoding priority in a series of encodings separated by commas. The highest priority encoding that is available and can be decoded by the player will be selected. Any encoding that you do not specify will be appended to the end of the array in pseudo-random order.

Note: Use akamai_hd2_hds for Live streams and akamai_hd2_hds for VOD content.
The following are best practices for setting encoding priority and using video streams:
  • The default encoding priority is ["dash_drm", "hls_drm", "hls", "dash", "mp4", "hds"]. We strongly recommend that you use the default encoding unless you have other streaming needs.
  • With DASH, you should always prioritize an alternate stream (do not set the encoding priority to only DASH).
  • For DASH video, you must use the AAC or mp4a.40.2 audio codecs.

Type: string

Valid Values:
  • "hls"
  • "dash"
  • "mp4"
  • "hds"
  • "ima"
  • "akamai_hd2_hds"
  • "akamai_hd2_vod_hds"
  • "dash_drm"
  • "dash_hls"
  • "AKAMAI_HD2_VOD_HLS"

Default: ["dash_drm", "hls_drm", "hls", "dash", "mp4", "hds"]

Example:

<div id="container" style="width:640px; height:360px;"></div>
<script>
    var playerParam = {
        "pcode": "YOUR_PCODE",
        "playerBrandingId": "YOUR_PLAYER_ID",
        "encodingPriority": ["hls", "dash", "mp4", "hds"],
        "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>

initialBitrate

Use this parameter to set the initial minimum bitrate level (immediately after video playback) and to sustain that level for a specific period of time. Once the duration is reached, the bitrate level changes to the video plugin's automatic bitrate level.

Settings:

You can specify two child parameters:
Name Type Valid Values Description
level string One of the following:
  • "auto" (default)
  • number between 0 (zero) and 1, inclusive
  • Specify "auto" to defer to the default bitrate set by the video plug-in's ABR logic. The behavior is equivalent to omitting initialBitrate entirely.
  • Specify a number if you want to set a particular level between zero and 1, inclusive.
If you specify a number:
  • Specify 0 (zero) to select the lowest bitrate first for the associated video plugin
  • Specify 1 to select the highest bitrate (MAX_BITRATE) for the associated video plug-in.
  • Specify a number between 0 and 1 to indicate which stream to use. From the array of available bitrates, the player selects the maximum value that is less than or equal to the preferred bitrate factor. For example, if your available bitrates were 0.1, 0.75, and 1.0mbps, then a value of 0.5 would select the lowest bitrate (0.1), a value of 0.8 would select the middle bitrate (0.75), and so on.
To determine the level, consider such factors as the approximate network speed of the end user, the type of device (desktop or mobile), and so on.
duration number a number greater than zero Represents the number of seconds to sustain the initial bitrate level.
Note: The following APIs also override the initialBitRate and automatic bitrate, starting from when they are called and for the remainder of the playback session:
  • SET_TARGET_BITRATE
  • setTargetBitrate()

Example:

<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"
         },
         // Set the initial bitrate to 80% of the maximum bitrate for 30 seconds
         "initialBitrate": {"level": 0.8, "duration": 30}
      };
      OO.ready(function() {
         window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
         });
</script>         

initialTime

Use this parameter to 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.

Type: integer

Valid Values: time in seconds

Example:

<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"
        },
        "initialTime": 10
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

initialVolume

Use this parameter to set an initial volume for a video.

Type: number

Valid Values: 0-1

Example:

<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"
        },
        "initialVolume": 1.0
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

loop

Use this parameter to enable continuous play. With loop set to true, once the playback has started it continues until the user stops playback or closes the browser. Also the behavior is the same when the ASSET_ID is set using setEmbedCode. As soon as the ASSET_ID is set, if autoplay is true, the playback starts immediately regardless of the previous state of the player (video playing/paused/stopped). If autoplay and loop parameters are not passed in through setEmbedCode, the existing values are used (which may have been set via a previous call to setEmbedCode).

Type: Boolean

Example:

<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"
        },
        "loop": true
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

platform

If you are using the bit_wrapper plugin for DASH and HLS (bit_wrapper.min.js), you can set "platform"="html5" to play HLS using the HTML5 standard (and Media Source Extensions), enabling HLS on web browsers without the use of Flash. HTML5 MSE also supports playback of MPEG-DASH (clear and DRM-protected content). For details, see Using Flash-free Playback with Player V4.

Example

<script>
   var playerParam = {
      "pcode": "YOUR_PCODE",
      "playerBrandingId": "YOUR_PLAYER_ID",
      "platform": "html5",
      "skin": {
         // Config contains the configuration setting for player
         // skin. Change to your local config when necessary.
         "config": "url_where_hosted/skin.json"
         }                
         // Add Optional Embedded Parameters Here
       };
   OO.ready(function() {
   window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
   });
</script>                 

onCreate

Use this parameter to listen to an event message and perform an action. This parameter enables you to subscribe to event messages from the message bus before the player is fully created. It allows you to modify the player prior to its complete creation.

When called, onCreate: function(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 third-party modules are not connected to the message bus and are not initialized.

Example

<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"
        },
       "onCreate": function(player) {
        player.mb.subscribe("*", "myPage", function(eventName) {});
        }
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

onCreate and the Player Callback

To handle events in Player V4, you provide an onCreate function to the OO.Player.create() call, and then register for all the messages.

preload

Use this parameter to specify if you want to preload the video.
Note: The player will never preload on Chrome or devices. We are working on a plugin that will allow preload behavior on devices for a future release.

Type: Boolean

Example:

<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"
        },
        "preload": true
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

skin.inline

Use this parameter to specify inline skin modifications. skin.inline will overwrite any settings in the skin.json config file. The JSON object within inline must have the same structure as skin.json (all parent objects going all the way back to the root object). For example, if you want to overwrite the start screen play button color using inline, you need to include the start screen object, playIconStyle object, and color (as shown in the following example).

Example:

<div id="container" style="width:640px; height:360px;"></div>
        <script>
            var playerParam = {
              "pcode": "YOUR_PCODE",
              "playerBrandingId": "YOUR_PLAYER_ID",
              "skin": {
                  "config": "url_where_hosted/skin.json",
                  "inline": {
                      // Put your player customizations here
                      // to override settings in skin.json. 
                      // The JSON object must match the structure of skin.json.
                      "startScreen": {"showDescription": false, "playIconStyle": {"color": "blue"}}
                  }
              }
            };
            OO.ready(function() {
              window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
            });
        </script>

Was this article helpful?