Page-level 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
Optional 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>
        <script src="//player.ooyala.com/core/YOUR_PLAYER_ID"></script>
    </head>
    <body>
        <div id="container" style="width:640px; height:360px;"></div>
        <script>
            var playerParam = {
             // 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>

Optional Parameters

Note: Make sure that page-level parameters are added at the base level of the player params and not somewhere deeper in your code.

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': false (default) - disables automatic playback of the main video.
  • 'autoplay': true - enables automatic playback for the main video.
Important: Autoplay on mobile browsers is not currently supported. Autoplay is set to false by default. If you enable autoplay and it is not supported on a particular platform, the setting will be ignored and the default behavior 'autoplay': false is used.
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>

autoPlayUpNextVideosOnly

Enables (default) or disables the automatic playing of Up Next or Discovery videos after the main video has played. Discovery will require users to initiate play events (no autoplay) if playerParams.autoPlay is false and playerParams.autoPlayUpNextVideosOnly is defined and is false. See Discovering Content in Player V4.
  • 'autoPlayUpNextVideosOnly': false - disables automatic playback of Up Next or Discovery videos.
  • 'autoPlayUpNextVideosOnly': true (default) - enables automatic playback. Up Next or Discovery videos will be played automatically after the main video has played - even if the main video does not automatically play ('autoplay': false).

Type: Boolean

Example:

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

dynamicFilters

One or more predefined filter names for generating a dynamic manifest. See Dynamic Manifests.

Type: String

Example:

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

iosPlayMode

Use this parameter to specify the initial playback mode for Safari Mobile on iOS devices (iOS 10 and later). By default, playback is initially in full screen mode ("iosPlayMode":"fullscreen" ). You can change this to inline playback (playing videos inline on the page rather than in full screen mode) by specifying "iosPlayMode":"inline" on the web page.
Note: Inline playback is required for skippable Google IMA ads.

location

Use this parameter (within a "bit-wrapper" object) to specify individual, custom paths for Bitmovin HTML5, CSS, and Flash files if any of those resources are stored in a location other than where the bit_wrapper.min.js plugin is stored.
Note: Use this parameter only if you are using the bit_wrapper.min.js plugin and only if you do any of the following:
  • You self-host player resources and you want to serve one or more of the associated resource files from a location that differs from where the bit_wrapper.min.js plugin is served.
  • You self-host player resources and you concatenate all of the Player V4 Javascript files into a single bundle.
  • You load the Player V4 files using a module loader library (most notably SystemJS) that bundles Javascript files. For SystemJS, this is true regardless of where the bitmovin resource files are located (custom or default).
Otherwise, this parameter is not needed.
Note: This parameter is identical to Bitmovin's Location parameter, which is described in Bitmovin's documentation. Player V4 currently uses only the html5, css, and flash options. Other options (vr, ctrls, or ctrls_css) are currently not used.

Type: object

Valid Values:

The following options are supported.
Status Description
html5 Location of bitmovinplayer-core.min.js. Path (fixed or relative) plus filename.
css Location of bitmovinplayer-core.min.css. Path (fixed or relative) plus filename.
flash Location of bitmovinplayer.swf. Path (fixed or relative) plus filename.
If not specified, then the default location is used (the location of the bit_wrapper.min.js plugin) or, if provided, the location specified by the locationBaseUrl parameter (described below).

Notes:

  • You can specify URLs using HTTP or HTTPS. However, to avoid mixed content issues, Ooyala recommends using the double slash instead ( // ).
  • When using both locationBaseUrl and location at the same time, location has priority over locationBaseUrl . Any values specified in location will override those generated with locationBaseUrl . Any files omitted from location will use the location generated with locationBaseUrl.

Example

{
  "bit-wrapper": {
    "locationBaseUrl": "//test.com",
     "location": {  
        "html5": "//my.custom.url/my-custom-file.js"
      }
   }
}  
The above settings would resolve to the following configuration:
      "location": {
        "html5": "//my.custom.url/my-custom-file.js",
        "css": "//test.com/bitmovinplayer-core.min.css",
        "flash": "//test.com/bitmovinplayer.swf",
        "vr": "//test.com/bitmovinplayer-vr.min.js",
        "ctrls": "//test.com/bitmovinplayer-controls.min.js",
        "ctrls_css": "//test.com/bitmovinplayer-controls.min.css"
      }              
Important: Player releases are associated with specific Bitmovin versions and are compatible only with those versions. When self-hosting, remember to download the Bitmovin files for the matching version using the exact static path for that version.

locationBaseUrl

Use this parameter (within a "bit-wrapper" object) to specify a custom path for the resources (Bitmovin HTML5, CSS, and Flash files) associated with the bit_wrapper.min.js plugin if they are not stored in the same location as the bit_wrapper.min.js plugin. Whereas the location parameter lets you specify an individual path for each resource file, the locationBaseUrl parameter allows you to specify a single path for all resource files (Bitmovin HTML5, CSS, and Flash files) at once.
Note: Use this parameter only if you are using the bit_wrapper.min.js plugin and only if you do any of the following:
  • You self-host player resources and you want to serve one or more of the associated resource files from a location that differs from where the bit_wrapper.min.js plugin is served.
  • You self-host player resources and you concatenate all of the Player V4 Javascript files into a single bundle.
  • You load the Player V4 files using a module loader library (most notably SystemJS) that bundles Javascript files. For SystemJS, this is true regardless of where the bitmovin resource files are located (custom or default).
Otherwise, this parameter is not needed.

Notes:

  • You can specify a fixed or relative path.
  • The url should be the full path without the filename and without a trailing slash.
  • The url can be set with either http or https, but Ooyala recommends using double slash instead ( // ).
  • If you specify this parameter, default file names will be used unless overridden with the location parameter.

Type: string

Example
{ "bit-wrapper": {
   "locationBaseUrl": "//test.com" 
   }
} 
The above settings would resolve to the following configuration:
     {
        "html5": "//test.com/bitmovinplayer-core.min.js", 
        "css": "//test.com/bitmovinplayer-core.min.css", 
        "flash": "//test.com/bitmovinplayer.swf",
        "vr": "//test.com/bitmovinplayer-vr.min.js", 
        "ctrls": "//test.com/bitmovinplayer-controls.min.js", 
        "ctrls_css": "//test.com/bitmovinplayer-controls.min.css" 
      }
Important: Player releases are associated with specific Bitmovin versions and are compatible only with those versions. When self-hosting, remember to download the Bitmovin files for the matching version using the exact static path for that version.

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>

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.

platform

This parameter applies only to the bit_wrapper.min.js plugin for DASH and HLS (bit_wrapper.min.js). As of Player v4.13.4, HTML5 playback is used as the default. However, if you prefer to lead with Flash-based playback, you need to add the following page-level parameter to playerParam: {"platform": "flash"}.
Note: If you specify "platform: "flash" to make Flash the priority, and Flash is disabled in a user's browser, then playback might fail for that user.

Example

<script>
   var playerParam = {
      "pcode": "YOUR_PCODE",
      "playerBrandingId": "YOUR_PLAYER_ID",
      "platform": "flash",                
         // Add Optional Embedded Parameters Here
       };
   OO.ready(function() {
   window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
   });
</script>

preload

Use this parameter to specify whether to start loading the video after the player is loaded and before the user starts playback (for non-autoplay settings) (true), or to wait until the user starts playback (false, the default). One of the following values:
  • 'preload': false (default)
  • 'preload': true - start preloading the video as soon as the player is loaded. Typically, a video will preload the stream up to filling the buffer, the size of which will vary by browser.
Preloading can significantly speed up the time-to-first-frame experience because the video has the opportunity to buffer before the viewer plays it.

Considerations:

  • Preloading is disabled if the initialTime parameter is used.
  • When using Google IMA with prerolls, preloading will be triggered at the start of the fourth quartile of the preroll ad or the last ad in a podded preroll. If ads are skipped before the fourth quartile of the ad is played, preloading of content will not occur.
  • Preloading is supported for the main_html5 and bit_wrapper video plugins.
  • Preloading is not yet supported for the Pulse or Freewheel ad managers.
  • Enabling content preloading can increase your overall video stream consumption because, for any given player embed, videos are preloaded even when playback is not initiated.

Type: Boolean

Example:

<div id="container" style="width:640px; height:360px;"></div>
<script>
    var playerParam = {
        "pcode": "YOUR_PCODE",
        "playerBrandingId": "YOUR_PLAYER_ID",
        "preload": true
    };
    OO.ready(function() {
        window.pp = OO.Player.create("container", "YOUR_ASSET_ID", playerParam);
    });
</script>

skin.config

The skin parameter references the skin.json config file. This loads the player skin. Use it if you want to use your own skin settings.

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

useFirstVideoFromPlaylist

Use this parameter to specify whether the player uses the first video from the playlist playlist (true) or not (false, the default). One of the following values:
  • 'useFirstVideoFromPlaylist': false (default)
  • 'useFirstVideoFromPlaylist': true - let the player set the first asset specified on the first item in a playlist.
Note: Before you set 'useFirstVideoFromPlaylist': true, contact Ooyala Tech Support to have your player plugin registered. If the plugin is not registered, playback will fail.
See Using Playlists in Player V4 for details.

Type: Boolean

해당 내용이 도움 되었습니까?