Player API Reference - Ooyala Support for Users

PLAYER API REFERENCE
CONTENTS
PLAYER APIS OVERVIEW
4
PLAYER API FUNCTIONS
5
PLAYER API PARAMETERS
Player Query String Parameters
Embedded Parameters
Custom Module Embedded Parameters
Ads Embedded Parameters Overview
In-Stream Ads Embedded Parameter
FreeWheel Ads Embedded Parameter
Google IMA Ads Embedded Parameters
LiveRail Ads Embedded Parameters
VAST Ads Embedded Parameters
VPAID Ads Embedded Parameters
11
11
12
18
20
21
21
22
26
28
29
PLAYER MESSAGE BUS EVENTS
31
PLAYER AUTHORIZATION API
38
FLASH-BASED PLAYER ERROR MESSAGES
42
PLAYER API REFERENCE | TOC | 2
WWW.OOYALA.COM вЂў [email protected] вЂў 1-877-3-OOYALA
COPYRIGHT NOTICE
Copyright Ooyala 2008-2014
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
2008-2014. 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: http://www.ooyala.com/tos
All other trademarks are the property of their respective companies.
This content was last updated on 2014-11-10.
PLAYER API REFERENCE | COPYRIGHT NOTICE | 3
PLAYER APIS OVERVIEW
Welcome to the Ooyala Player API Reference. Ooyala offers a customizable, feature-rich Player used to
provide a top-notch video experience across industries and across multiple devices.
As consumers leverage the freedom that mobile devices provide, they expect video to match what they
have come to expect on their desktops and to be available across devices. Increasingly, HTML5 is
becoming the primary and only standard for this type of mobile video experience. Ooyala offers the Player
to make it easier to give your customers this kind of video experience. The following topics describe the
Player APIs.
PLAYER API REFERENCE | PLAYER APIS OVERVIEW | 4
PLAYER API FUNCTIONS
Player JavaScript functions can be used to customize the player behavior and appearance.
PLAYER FUNCTIONS
The following table describes the primary Player JavaScript functions.
Function
Description
destroy()
This function can be used in two ways:
вЂў
Destroy item. When called, the player is
removed, all activity is stopped, and any video is
unloaded.
ooplayer.destroy();
вЂў
Note: The following parameter is optional, and is
only supported for HTML5.
You can specify a function callback of your
choice to the 'destroy' API so that the web page
gets notified when the 'destroy' API is completely
through destroying the HTML5 player. For
example:
ooplayer.destroy(function()
{ alert("Alert me once the player
is completely destroyed"); });
pause()
Pause the current video playback.
play()
Playback the current video.
seek()
Seek to the specified parameter in seconds.
Type: Number
Valid Value: time in seconds
seek()
Seek to the specified parameter in seconds.
Type: Number
Valid Value: time in seconds
shouldDisplayCuePointMarkers()
When called on the console log while a player
is playing, this Boolean function shows or hides
cue point markers on the scrubber bar during ad
playback. By default, cue point markers are hidden.
If shouldDisplayCuePointMarkers(True) is called,
and if there are active midroll and postroll ads
available, the Player will display any cue point
markers on the scrubber bar.
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 5
Note: This feature is currently available for Flash
desktop and FreeWheel ads only.
player.shouldDisplayCuePointMarkers(TRUE);
GET FUNCTIONS
The following table describes all of the Player JavaScript get functions.
Function
Description
getBitrateQualitiesAvailable()
Returns an array of strings. The size of the array is
dependent on the number of encodings available:
вЂў
вЂў
вЂў
вЂў
When only one encoding is available, the
function returns [вЂ�autoвЂ™]
When two encodings are available, the function
returns [вЂ�autoвЂ™,вЂ™lowвЂ™,вЂ™highвЂ™]
When three or more encodings are available, the
function returns [вЂ�autoвЂ™,вЂ™lowвЂ™, вЂ�mediumвЂ™, вЂ™highвЂ™]
When no bitrate quality information is available,
the function returns [вЂ�autoвЂ™]
Type: Array
getBitratesAvailable()
Returns an array with the total number of bitrates,
in kbps, or an empty array when the number of
encodings is not available.
Note: With a Flash player, you can get the target
bit rate, if you get the value upfront. However, this
is not true for Quicktime. There is no control over
QuicktimeвЂ™s ability to pickup the bitrate and the
default in this case is to use the suggested time on
a best effort basis.
Example: [250, 500, 1000] indicates that three
bitrates are available: 250 kbps, 500 kbps and 1000
kbps. For a Flash-based Ooyala Player, a publisher
can use this API to get a list of available bitrates
they use for the setTargetBitrate() API.
getBufferLength()
Returns the current size of the buffer in seconds,
when buffer length is supported, or 0 otherwise.
Note: Currently, YouTube Assets and Remote
Assets do not support buffer length.
Type: Number
Return Values: Time in seconds | 0
getCurrentItemClosedCaptionsLanguages() Get a list of supported closed captions languages
for the currently playing item. This list is derived
from the closed captions XML (DFXP [now TTML])
file for this content, uploaded via Backlot. For
more information about this file see Uploading
and Viewing a Closed Captions File. If there is no
DFXP (now TTML) file in place, this method returns
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 6
an empty list. In live streaming mode, the closed
caption languages will be derived from the stream
itself.
Type: List
Return Values: A list in the form of "language
code":"displayName".
Example: { "en": "English",... }.
Note: This method will throw an exception if no
Closed Captions file has been uploaded for the
current embed code.
getDescription()
Get the description of the current video from
Backlot. This function retrieves the description that
was set in the the Backlot Manage > Details tab or
equivalent manual setting.
Type: String
Return Values: Alphanumeric description of asset
Example: Season 22 Opening Game
getDuration()
Gets the total duration of the video in seconds.
Type: Number
Return Value: Duration in seconds
getEmbedCode()
Get the embedCode for the current player.
Type: String
Return Value: NodXQ5NTq0Y8Nw4GvIWBHlfirMiKy7P
getError()
Return the current error code, if the code exists and
if the current state is error.
Type: String
Return Value: Returns the error's localized error
message.
getErrorText()
Returns an error message string.
Type: String
Return Value: Error's localized error message.
Example: "This video is not authorized for this
domain. Please contact the administrator."
getItem()
Get an object describing the current video.
Type: Object
Return Value: Object, with the following attributes:
вЂў
вЂў
вЂў
вЂў
вЂў
embedCode
title
description
time (play length in seconds)
lineup
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 7
вЂў
вЂў
promo
hostedAtURL
Return the playhead location in seconds with
millisecond accuracy.
getPlayheadTime()
Type: Number
Return Value: Duration in seconds
Get current player state.
getState()
Type: String
Return Values: One of: LOADING :
вЂ�loadingвЂ™READY : вЂ�readyвЂ™PLAYING :
вЂ�playingвЂ™PAUSED : вЂ�pausedвЂ™BUFFERING :
вЂ�bufferingвЂ™ERROR : вЂ�errorвЂ™DESTROYED :
вЂ�destroyedвЂ™
getTargetBitrate()
Get the target bitrate, in kpbs, when target bitrate
was previously set, or -1 otherwise.
getTargetBitrateQuality()
Returns the quality of the target bitrate: One of
auto, low, medium or high.
Works only with Flash player.
Type: String
Get the title of the video.
getTitle()
Type: String
Return Value: Video title
Example: My Snowboarding Channel
getVolume()
Return the current volume on a best-effort basis
gated by underlying device limitations.
Type: Number
Return Value: A number between 0 and 1 inclusive
Returns true if in fullscreen mode, false if not.
Fullscreen implementation is done on a best-effort
basis due to or based upon underlying device
limitations.
isFullscreen()
Type: Boolean
Valid Values: true | false
SET FUNCTIONS
The following table describes all of the Player V3 JavaScript set functions.
Function
Description
setClosedCaptionsLanguage(language)
Sets the language of the closed captions (CC) that
will be shown in the player. If you do not upload
the Closed Captions file, the content will playback
without closed captions. In Live streaming mode,
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 8
the closed caption languages will be derived from
the stream itself. Note that because of the way that
closed captions are supported in iOS, we are not
able to add closed caption data for IOS web for
remote assets.
Parameter: language
Valid Values: Specify the ISO 639-1 language
code | none. For Chinese, you should use "zh-hans"
for Simplified Chinese and "zh-hant" for Traditional
Chinese. To show no closed captions, set the
language to "none".
Examples: en, de, ja.
setEmbedCode(embedcode, options)
Set the embedCode for the current player. The
setEmbedCode function also takes an option that
enables you to dynamically assign an ad set to an
embed code.
Type: String
Parameters: Takes an embed code and options
parameter.The options parameter must be an
object that is a hash of key value pairs representing
the unique ad code.
Example:The ad set code must belong to the same
provider as the embed code.
player.setEmbedCode(embedCode, {
adSetCode: 'foo'});
Note: This function requires that you associate
an ad set with a movie in Backlot. For more
information, see the topic, вЂњAssigning Ad Sets
DynamicallyвЂќ in the Player V3 Developer Guide.
setPlayheadTime(value)
Move the playhead to a location specified in the
parameter in seconds.
Type: Number
Valid Values: duration in seconds
setTargetBitrate(bitrate)
Set the target bitrate, in kbps. The input
needs to be an available bitrate. Available
bitrates can be determined by a call to
getBitratesAvailable().
No Bitrate Carry Over From Video to VideoThis
setting does not carry over from video to video.
For example, consider a channel with two videos,
the first with highest bitrate of 1000 kpbs, and
the second with medium bitrate of 1000 kpbs and
highest bitrate of 2000 kpbs. If you set bitrate to
1000 kpbs, we will convert this number to a bitrate
quality, which in this case in high. Since bitrate
quality carries over, the first video will play at 1000
kpbs, and the second video will play at 2000 kpbs,
which is its highest bitrate.
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 9
HDS Restriction on Setting BitRate
When you are using HDS, you need to know that
HDS does not expose to our APIs what is needed
to affect the bitrate. Thus even if you set a target
bitrate, it does not change.
setVolume(value)
Set the current volume on a best-effort basis due to
underlying device limitations.
Valid Values: a number between 0 and 1 inclusive
PLAYER API REFERENCE | PLAYER API FUNCTIONS | 10
PLAYER API PARAMETERS
Player parameters can be used to customize the player ads, behavior and to change player styles.
The following general types of parameters can be passed to the Player API:
1. Query string parameters
2. Embedded parameters
3. Custom Module Embedded parameters
PLAYER QUERY STRING PARAMETERS
You add these types of query string parameters to the URL that invokes the Player V3 library and the
video, like the name1=value1 &name2=value2... in the following example.
<script>http://player.ooyala.com/v3/player_branding_id?name1=value1
&name2=value2...
The following table describes these query string parameters.
Parameter
Description
namespace
The namespace parameter allows multiple independent copies of player code on the
same page, by renaming the default namespace OO to any other valid javascript id. For
example if you use this embed:
namespace=(unique javascript id)
You can later use:
MYPLAYER_1.Player.create(......)
MYPLAYER_2.Player.create(......)
platform
The platform parameter enables you to control the selection mechanism between flash
and html5 playback. The parameter format is:
platform=(flash-only|flash|html5-fallback|
html5-priority)
For Player V3, the default multimedia Default is flash. The parameter has the following
options:
вЂў
вЂў
вЂў
вЂў
flash - Enables default Adobe Flash playback only on desktop, on mobile and tablets.
This option sets the preference to Flash but also allows html5 fallback.
flash-only - Only allows Flash playback. If Flash is not detected it displays an error
message and requests that the viewer installs the Flash plug-in.
html5-fallback - Uses Flash but enables fallback to html5.
html5-priority - This parameter sets html5 as the preferred playback mechanism but
also allows Flash fallback.
PLAYER API REFERENCE | PLAYER API PARAMETERS | 11
Parameter
Description
Note: HTML5 playback only works for specific browser and OS/device configurations.
See the Support Center в†’ Documentation в†’ Player Developer Guide в†’ System
Requirements topic for more information.
tweaks=androidUse the tweaks parameter to enable HLS on your Android devices for the web. Although
enable-hls you can use this parameter to enable HLS on Android devices, certain limitations exist for
HLS playback on 4.x devices. For more information about operability on Android devices,
see "Enabling HLS on Android Web."
Note: As the use of the tweaks parameter can involve native playback issues, we cannot
guarantee optimal playback experience on every Android device and OS version.
Example
http://player.ooyala.com/v3/123fake6b6774f909c2fa6d23ce5334a?
tweaks=android-enable-hls
Note: The legacy Player API had query string parameters for passing tags of ad server and ad networks
to the Ooyala player. For Player V3, the supported ad servers/networks and the mechanisim for passing
related tags is detailed in Ads Embedded Parameters Overview on page 20.
EMBEDDED PARAMETERS
Note: For Ads embedded parameters for Google IMA, VAST, VPAID, FreeWheel, and Liverail, please see
Ads Embedded Parameters Overview on page 20 and follow the links for the desired ad manager or
module.
You add the following parameters to the player embed code within the DIV container, as shown in the
example for each parameter. These parameters include CSS style settings such as width and height and
embed code parameters that are tags from your ad server or ad network account and can be passed to
the Ooyala Player for advanced ad tracking and targeting. The following table describes these embed code
parameters.
The following table also describes the hash or key value pairs that you can use with the onCreate
function to change embedding behavior.
Table 1: Embedded Parameters
Parameter Key
Description
analytics
Enables the use of custom analytics tags in Player V3.
Example:
...
var ca_tags = [];
ca_tags[0] = "toolbar";
OO.ready(
function () {
OO.Player.create('ooyalaplayer',
'w3ZHc0Njr33Tdp-RRcwfZMjaOrmzOP82', {
analytics: {
"tags": ca_tags
}
});
PLAYER API REFERENCE | PLAYER API PARAMETERS | 12
Parameter Key
Description
});
...
Note: For additional information about custom analytic tags and using these tags
with the Backlot REST API, see Custom Analytics: Tagsand Custom Analytics:
Tags.
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.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height:100%,
width:100%,
autoplay:true,
....
});
enableChannels
Enables loading Flash videos in Channels mode. This parameter provides
backwards compatibility for channels. By default the flag is set to a value of false.
The embedChannels parameter handles HTML5 compatibility and ensures Flash
channel usability.
For HTML:
вЂў
вЂў
If enableChannels = true, play the first video of the channel or the first video of
the first channel of the channel set
If enableChannels = false, display an error screen.
For Flash:
вЂў
вЂў
If enableChannels = true, pass the channel embed to the player to run normally
(this may impact performance).
If enableChannels = false, display an error screen.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
enableChannels: true,
....
});
google
Use this parameter to pass Google IMA v3 ad server or network tags to the Ooyala
player. The parameter takes a key value pair representing a Google AdSense URL.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'google': {
tagUrl: 'some url',
PLAYER API REFERENCE | PLAYER API PARAMETERS | 13
Parameter Key
Description
....
},
});
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. You can also use this parameter with Cross-Device Resume to seek to a
specific user's position.
Type: integer
Valid Values: time in seconds
Example: initialTime: 10
OO.ready(function () {
window.pp = OO.Player.create('playerV3Container',
'embed_code', {
width: 480,
height: 360,
initialTime: 10
});
in-stream
Use this parameter to pass In-Stream ad server or network tags to the Ooyala
player. The parameter takes a key value pair representing an In-Stream URL.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'in-stream': {
tagUrl: 'some url',
....
},
});
locale
Use this parameter to set or override the language and closed caption options. In
the following example, the locale parameter is used to create a Hebrew localized
player. Note that because of the way that closed captions are supported in iOS, we
are not able to add closed caption data for IOS web for remote assets.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
locale: 'he_IL',
....
});
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 embed code is set using
setEmbedCode. As soon as the embed code is set, if autoplay is true, the playback
starts immediately regardless of the previous state of the player (video playing/
PLAYER API REFERENCE | PLAYER API PARAMETERS | 14
Parameter Key
Description
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).
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
loop: 'true',
....
});
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 need to 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
OO.Player.create('playerwrapper',embedCode, {
onCreate: function(player) {
player.subscribe('*','myPage', function(eventName) {});
}
});
onCreate and the Player V2 Callback
To handle events in Player V2, you can define a callback function, and then pass
its name to the embed tag using a callback parameter. However, to handle events
in Player V3, you provide an onCreate function to the OO.Player.create()
call, and then register for all the messages. For more information about Player V3
events, see Player Event Model. For information about Player V2 callbacks and
parameters, see the Player Query String Parameters (Player V2 Deprecated) topic.
Keep in mind that Player V2 is deprecated.
prebuffering
For HTML5 players, use this parameter to disable prebuffering of videos, which
happens by default. You might want to disable prebuffering for different reasons:
вЂў
вЂў
To decrease load time when loading multiple videos on the same page
To avoid the cost of loading when you expect a video to be played infrequently
The following example shows the use of the prebuffering parameter.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
PLAYER API REFERENCE | PLAYER API PARAMETERS | 15
Parameter Key
Description
width: 100%,
prebuffering: false,
....
});
showAdMarquee
Specifies whether to show or hide the ad marquee during ad playback. If
showAdMarquee is missing or set to true, the ad marquee will appear while an ad
is playing on your player. This global parameter works for all ad types supported by
Ooyala.
Valid Values: true | false
вЂў
вЂў
True: adMarquee will appear during ad playback.
False: adMarquee will be hidden during ad playback.
Default: True
Example:
var player = OO.Player.create('playerwrapper', embedCode, {
showAdMarquee: true
});
showInAdControlBar
Specifies whether to show or hide the control bar during ad playback. If
showInAdControlBar is missing or set to true, the control bar will appear while an ad
is playing on your player. This global parameter works for all ad types supported by
Ooyala.
Note: This parameter is only available for Flash desktop.
Valid Values: true | false
вЂў
вЂў
True: controlBar will appear during ad playback.
False: controlBar will be hidden during ad playback.
Default: True
Example:
var player = OO.Player.create('playerwrapper', embedCode, {
showInAdControlBar: false
});
tvRatingsPosition
Note: This parameter is for Flash desktop only.
This optional parameter specifies the position on the player where the TV rating
watermark will appear.
Valid Values: top-left | top-right | bottom-left | bottom-right
Default: top-left
Note: To apply a TV Rating watermark to an asset, you need to include custom
metadata in Backlot per asset you want given the TV Rating watermark. See
Adding a TV Rating Watermark to a Flash Player for detailed information on
applying a TV Rating watermark to an asset.
Example:
var player = OO.Player.create('playerwrapper', embedCode, {
PLAYER API REFERENCE | PLAYER API PARAMETERS | 16
Parameter Key
Description
tvRatingsPosition: "top-left"
});
tvRatingsTimer
Note: This parameter is for Flash desktop only.
Specifies the duration of the TV Rating watermark on the player (in seconds) on
initial play and every time the video resumes from Ad breaks. This parameter is
required if you want to apply a TV Rating watermark to an asset.
Valid Values: always | never | some_number
вЂў
вЂў
вЂў
always: The watermark appears for the duration of the video (but will not appear
during ad playback).
never: The watermark never appears.
some_number: You will replace some_number with the number of seconds you
want the TV rating to remain on the player.
Default: never
Note: To apply a TV Rating watermark to an asset, you need to include custom
metadata in Backlot per asset you want given the TV Rating watermark. See
Adding a TV Rating Watermark to a Flash Player for detailed information on
applying a TV Rating watermark to an asset.
Example:
var player = OO.Player.create('playerwrapper', embedCode, {
tvRatingsTimer: "15"
});
useFirstVideoFromPlaylist
Use this parameter to set the video in the player to the first video from the first
playlist.
Type: Boolean
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
useFirstVideoFromPlaylist: true,
....
};
ooyalaPlayer = OO.Player.create('playerContainer', '',
playerConfiguration);
});
Note:When a playlist is updated, after the caches expire, the first video in the first
playlist that useFirstVideoFromPlaylist uses is updated.
If you don't want the video in the player to be the first video from the first playlist
you can use another video by setting this parameter to "false" and specifying the
desired video's embed_code in the OO.Player.create function like so:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
PLAYER API REFERENCE | PLAYER API PARAMETERS | 17
Parameter Key
Description
useFirstVideoFromPlaylist: false,
....
};
ooyalaPlayer =
OO.Player.create('playerContainer', 'embed_code',
playerConfiguration);
});
CUSTOM MODULE EMBEDDED PARAMETERS
You can add custom module embedded parameters (key value pairs) to the onCreatefunction. The
following table describes these custom module parameters.
Parameter
Description
devModuleCategory
Used for the development of third party custom modules, you specify this
parameter in the "flashParams" subhash of the Player.create options hash.
Use this parameter to specify the custom module category such as 'universal'
or 'ads-manager.'
Type: string
Valid Values: category name such as 'universal' or 'adsmanager'
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'flashParams': {
devModuleCategory: 'universal',
....
},
});
devModuleURL
Used for the development of third party custom modules, you specify this
parameter in the "flashParams" subhash of the Player.create options hash.
You use this parameter to specify the URL of the location where the third
party module swf can be downloaded.
Type: string
Valid Values: download URL where the third party module swf
is located
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'flashParams': {
devModuleURL: 'someURL',
....
PLAYER API REFERENCE | PLAYER API PARAMETERS | 18
Parameter
Description
},
});
hide
Use this parameter to disable specific player functionality. The V3 HTML5
player does not display the controls by default and thus the hide parameter
does not work with the V3 player. However, if you have Flash fall-back
on your device, you can us use the hide parameter (see the platform
parameter listed earlier). In the case where you do have Flash fall-back, you
need to specify hide with flashParams in the hash.
Type: string
Valid Values: all | comma-separated list of options
where the values are:
вЂў
вЂў
all - to disable all controls
channels, fullscreen, embed, endscreen, info,
loadingindicator, sharing, or volume,
Example:
In the following example we specify 'flashParams' in the hash and add the
hide key value pair.
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'flashParams': {
hide: 'all',
....
},
});
If the player is in a chromeless layout, it is possible to disable the
loadingIndicator. The following example shows how to use this value
with the hide parameter.
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'flashParams': {
hide: 'loadingindicator',
....
},
});
layout
Use this platform parameter to control the UI layout. The parameter format is:
layout=(chromeless)
For Player V3, the parameter has the following option:
вЂў
chromeless - Toggles the default player controls on or off. If set to
chromeless, the parameter removes the chrome and the start screen. If
not specified, the player reverts to its default layout.
PLAYER API REFERENCE | PLAYER API PARAMETERS | 19
Parameter
Description
The chromeless parameter disables the controls in the player UI and plays
the video just through autoplay. To implement a chromeless layout on the
Ooyala V3 Player, you can add the layout='chromeless' parameter to
the <script ..../v3> tag. This disables the player controls so that the
viewer can playback a video without the controls being shown. By removing
the player's control bar, viewers will not be able to play the video as the
playback button is removed. You need to enable a video playback so that the
video will start automatically. Set the autoplay parameter to 1 to make the
video to start as soon as the player finishes loading the stream.
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
layout: 'chromeless'
});
thruParam_dev-other Used for the development of third-party custom modules. You specify this
parameter in the "flashParams" subhash of the Player.create options hash.
This parameter allows you to pass basic customizations to the Ooyala player.
Type: string
Valid Values: customization code
Example:
var videoPlayer = OO.Player.create('playerwrapper',
'embed_code', {
height: 100%,
width: 100%,
'flashParams': {
thruParam_dev-other: 'customization',
....
},
});
ADS EMBEDDED PARAMETERS OVERVIEW
Customize ads using embedded parameters.
You can pass ad-service-related tags to the Player with the embedded parameters listed in the following
table. For a full description of these parameters and their tags, see the individual topics for each of the ads
embedded parameters by selecting the parameter link. You can also see our Ads Integration developer
guide topics for step-by-step information about adding ads to your content and integrating an ad network
with your player.
Note: Ads positions behave somewhat differently on desktop and mobile devices:
вЂў
вЂў
Desktop platforms support all ad positions.
iOS-based devices support only pre- and post roll positions.
PLAYER API REFERENCE | PLAYER API PARAMETERS | 20
Parameter
Description
in-stream
Pass in-Stream ad server or network tags to the Ooyala player. The parameter
takes a key/value pair representing an In-Stream URL.
For more information see the In-Stream Ads Embeded Parameters reference topic.
freewheel-adsmanager
Pass FreeWheel ad server or network tags to the Ooyala player. The parameter
takes a key value pair representing a FreeWheel URL.
For more information, see the FreeWheel Embeded Parameters reference topic.
google-ima-ads- Pass Google IMA ad server or network tags to the Ooyala player. The parameter
manager
takes a key value pair representing the ad server or network URL. You can pass
google-ima-ads-manager ad tags to the Ooyala player.
For more information, see the Google IMA Ads Embeded Parameters reference
topic.
liverail-adsmanager
Pass certain LiveRail parameters (LR_ parameters) to communicate with LiveRail.
vast
Pass VAST ad server or network tags to the Ooyala player. VAST is an ad format
which uses xml to describe Linear ads (video ads), non-linear ads (overlay ads)
and companion ads.
For more information, see the LiveRail Ads Embeded Parameters reference topic.
For more information, see the VAST Ads Embeded Parameters reference topic.
vpaid-adsmanager
Pass VPAID Ad Manger tags to the Ooyala player.
For more information, see the VPAID Ads Embeded Parameters reference topic.
In-Stream Ads Embedded Parameter
Pass in-stream ads to the Ooyala player.
Use the in-stream embedded parameter to pass in-Stream ad server or network tags to the Ooyala player.
The parameter takes a key/value pair representing an In-Stream URL.
FreeWheel Ads Embedded Parameter
You can pass FreeWheel ad-service-related tags to the Player with the embedded parameters using the
freewheel-ads-manager parameter in your embed.
Note: Ads positions behave somewhat differently on desktop and mobile devices. At this time support for
pre-, mid-, and post-roll ads varies by platform. To see what ad position are supported for each platform,
see Ads Integration Overview.
FREEWHEEL PARAMETER
freewheel-ads-manager - Use this ads parameter to pass FreeWheel ad server or network tags to the
Ooyala player. The parameter takes a key value pair representing a FreeWheel URL.
The following sample web page shows a FreeWheel ad manager integration that passes additional pagelevel parameters in an HTTPS environment, for both Flash and HTML5.
Note: The values in the following non-working example are only used to illustrate how to use the
freewheel-ads-manager. You need to replace them with your own profiles, ids, and URLS.
<script src='http://player.ooyala.com/v3
PLAYER API REFERENCE | PLAYER API PARAMETERS | 21
/1234fake2b914bc58e425795abf3cd6c?
version=1234fake09bb8939e930f888b2b9e23627b20ea6&
platform=html5-priority'></script>
<script>
OO.ready(function () {
var videoPlayer = OO.Player.create('container',
'1234Fakeoi5Xv3Dav6uuEIeVJto9Ju7R', {
"freewheel-ads-manager": {
fw_ad_module_js: "http://adm.fwmrm.net/p/exampleprovider_live/
AdManager.js",
html5_ad_server: "https://1b656.v.fwmrm.net/ad/g/1",
html5_player_profile: "123400:exampleprovider_live_html5",
fw_player_profile: "123400:exampleprovider_live",
fw_mrm_network_id: 123400,
// Parameters that should be set on each page on the actual site
fw_site_section_id: "EXAMPLEVIDEO_EXAMPLEVIDEO_SHOWS",
fw_video_asset_id: 123FAKE
}
});
});
</script>
Google IMA Ads Embedded Parameters
You can pass Google IMA ad-service-related tags to the Player with the embedded parameters.
Note: To use OoyalaвЂ™s Google IMA ad manager, log into the Support Center and submit a ticket
requesting that this ad source be added to your account. Once itвЂ™s enabled, youвЂ™ll be able create adsets for
your player.
Ads positions behave somewhat differently on desktop and mobile devices. See Ads Integration Overview
for a comprehensive list of ad postion support by platform.
GOOGLE IMA PARAMETER
Use the google-ima-ads-manager parameter to pass Google IMA ad server or network tags to the
Ooyala player. The parameter is a container that takes a key value pair representing the ad server or
network URL along with the other parameters described below.
Set the adTagUrl Parameter to Override the Backlot URL
One of the parameters for the google-ima-ads-manager is a key value pair in the form adTagUrl:
"some url".
Valid Values: Any URL.
For example:
var videoPlayer = OO.Player.create("playerwrapper", "embed_code", {
height: "100%",
width: "100%",
"google-ima-ads-manager": {
adTagUrl: "some url",
...
},
});
PLAYER API REFERENCE | PLAYER API PARAMETERS | 22
You need to change the key value "some url" to the actual google-ima ad tag containing the response.
This URL value for the adTag key value pair represents the ad server or network URL. This adTag URL
overrides the one in Backlot. For example:
adTagUrl: "http://myAdServer.com/myGoogle-ima-ads-manager"
You can have additional adTag parameters appended to the end of the URL that you get from Backlot.
Use showInAdControlBar to Show or Hide the Player Controls Bar During Ad Playback
You can use showInAdControlBar to show/hide player controls bar during ad playback.
Valid Values: yes | true | no | false
Default: no
Note: There is a general player parameter also called 'showInAdControlBar'. You should not use both
showInAdControlBar parameters simultaneously. The preferred method is to use the general player
showInAdControlBar parameter outside of the 'google-ima-ads-manager' hash.
For example:
var videoPlayer = OO.Player.create("playerwrapper", "embed_code", {
height: "100%",
width: "100%",
"google-ima-ads-manager": {
showInAdControlBar: true,
... }
}
);
Use showAdMarquee to Show or Hide the Ad Marquee During Ad Playback
Use showAdMarquee to show or hide the ad marquee during ad playback. When set to false or no, the
adMarquee of an add will be hidden. If set to true, yes, or omitted the adMarquee will be displayed during
ad playback.
Valid Values: true | false
Default: true
For example:
var videoPlayer = OO.Player.create("playerwrapper", "embed_code", {
height: "100%",
width: "100%",
"google-ima-ads-manager": {
showAdMarquee: true ,
... }
}
);
Use playWhenAdClick to Set Ad Playback Behavior After Ad is Clicked
If playWhenAdClick is set to yes, ad playback will continue regardless of click.
Valid Values: yes | true | no | false
Default: no
Note: For Flash, if playWhenAdClick is set to false with no ad controls, after the user clicks on the ad and
is redirected, ad playback will continue when the user clicks on the ad the second time. We are aware that
PLAYER API REFERENCE | PLAYER API PARAMETERS | 23
this causes some undesired behavior where the ad url opens for both ad pause and ad play events. We
are working with the Google IMA team to fix this behavior. Otherwise, ad playback will pause.
For example:
var videoPlayer = OO.Player.create("playerwrapper", "embed_code", {
height: "100%",
width: "100%",
"google-ima-ads-manager": {
playWhenAdClick: true ,
... }
}
);
Set the additionalAdTagParameters to Append More Parameters
You can use additionalAdTagParameters to add functionality to your ad handling such as adding
demographic targeting for ads. These added ad tag parameters have a dependency on how the ad tag
is set up in Backlot. Also, the additional adTagUrl parameter key-value pairs are part of the adTagUrl
parameter and need to be in the form of a dictionary with key-value pairs. You can use any of the internal
key/value pairs that google-ima supports. Google IMA documentation lists these parameters at this site:
https://support.google.com/dfp_premium/answer/1068325?hl=en. When you use these parameters, we
append them to the end of the ad tag. Appended parameters do not override anything in the URL from
Backlot.
Note: The ad tag Url overrides the Url in Backlot.
To start using these parameters, you can specify something like the following:
additionalAdTagParameters: {
"parameter1": "value1",
"parameter2": "value2"
}
In Backlot, if you specify the ad tag URL as:http://www.example.com/example?param1=test,
the resulting request made with the following parameters would be: "www.example.com/
example?param1=test&cust_params=env%3Dmobilevcmshost%26siteview%3D1%26pth
%3Djsbin.com&vid=code&pod=2"
This request would look something like the following example:
"google-ima-ads-manager": {
additionalAdTagParameters: {
cust_params: "env%3Dmobilevcmshost%26siteview%3D1%26pth%3Djsbin.com",
vid: "code",
pod: "2"
}
}
adTagUrl Parameters from Google IMA Documentation
You use the key value pairs from the google-ima-ads-manager to append to the adTagUrl parameter.
You can find lists of these parameters in the Google IMA documentation. The following examples show
how to use some of these parameters as key-value pairs of the google-ima-ads-manager parameter:
cust_params
PLAYER API REFERENCE | PLAYER API PARAMETERS | 24
This value pair enables you to pass custom targeting parameters to the Ooyala player. You can put any
kind of key values for the cust_params. For example:
cust_params: "partner%3Dpartner_1%26gender%3Dfemale%26anotherKey
%3Dvalue1%2Cvalue2"
vid
This parameter is a unique identifier for the video assets and should take the value of your Ooyala video
asset ID (embed code). You can get your video embed code from Backlot.
Note: This value is required for using DFP to target against content metadata.
For example:
vid: "1234Fakeoi5Xv3Dav6uuEIeVJto9Ju7R"
vpos
You can use this value to specify the position of the ad in the video stream.
vpos: "preroll"
The following example demonstrates the use of the google-ima adTagUrl parameter on a client-side web
page.
<!doctype html>
<html>
<head>
<style rel="stylesheet" type="text/css">
html,
body {
margin: 0;
padding: 0;
}
#container {
width: 800px;
height: 500px;
margin: 0 auto;
}
</style>
<script src="http://player.ooyala.com/v3/123fake9ddb1446ea9bb7cad08711d36?
platform=html5-priority"></script>-->
<script>
OO.ready(function () {
OO.Player.create("container", "123fakeZpXSpOwupKby1s74Q8FQbRwPn", {
"google-ima-ads-manager": {
"showInAdControlBar": true,
"adTagUrl": "http://1fake4ads.g.doubleclick.net/gampad/ads?
sz=640x480&iu=%2F6376%2Fbr.
College_Football%2Fvideo&ciu_szs=300x250%2C728x90&impl=s
&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1
&url=[referrer_url]&correlator=[timestamp]",
"additionalAdTagParameters": {
"cust_params": "env%3Dmobilevcmshost%26siteview%3D1%26pth
%3Djsbin.com",
"vid": "code",
"vpos": "preroll"
}
}
});
PLAYER API REFERENCE | PLAYER API PARAMETERS | 25
});
</script>
</head>
<body>
<div id="container"></div>
</body>
</html>
In this example, we set the adTagUrl with several key value pairs such as ciu_szs, unviewed_position, url,
correlator and others.
ADREQUESTTIMEOUT PARAMETER
Set the adRequestTimeout to set the timeout before continuing video playback
Note: The parameter is for Flash only.
Use the key value pair in the form adRequestTimeout: "some integer" to customize the time taken,
in milliseconds, to make a timeout for the ad request and continue the video playback. We recommend
using whole milliseconds (e.g. 2001 milliseconds instead of 2000.5 milliseconds).
Valid Values: any integer greater than or equal to 1000.
Default: 3000
For example:
var videoPlayer = OO.Player.create("playerwrapper", "embed_code", {
height: "100%",
width: "100%",
adRequestTimeout: 1000
"google-ima-ads-manager": {
adTagUrl: "some url",
... },
}
);
GOOGLE IMA FOR MOBILE DEVICES
Ooyala supports Google IMA for both desktop and mobile. For information about working with Google IMA
for mobile devices, see the following mobile SDK Android and iOS topics.
вЂў
вЂў
Android - Integration with Google IMA on Android and See the IMA Sample App in Action on Android
iOS - Integration with Google IMA on iOS and See the IMA Sample App in Action on iOS
LiveRail Ads Embedded Parameters
You can pass LiveRail ad-service-related tags to the Player with the embedded parameters described in
the following table.
LIVERAIL-ADS-MANAGER PARAMETER
liverail-ads-manager - Use this parameter to pass certain LiveRail parameters (LR_ parameters) to
communicate with LiveRail. A direct translation of the LiveRail parameters from Backlot to Dynamic params
would be:
PLAYER API REFERENCE | PLAYER API PARAMETERS | 26
Backlot
LiveRail
Required
Details
Publisher ID
LR_PUBLISHER_ID
Yes
Unique identifier for your LiveRail
account.
Partner IDs
LR_PARTNERS
No
Revenue-sharing partner ID that has
been created in the LiveRail system.
Tags
LR_TAGS
No
Keywords or content tags to pass
to LiveRail's system for campaign
targeting or reporting.
Ad Map
LR_ADMAP
No
The standard way for defining when
ads should play in video stream. Full
details on the format for this key/value
pair are available in LiveRail's Support
Center.
By default the Ad Map configured in
your LiveRail account will be applied,
however if you specify an Ad Map
for your Ad Set it will over-ride the
default Ad Map configured in the
LiveRail system. The table below
explains the syntax and valid values for
LR_ADMAP.
LR_ADMAP
The syntax for LR_ADMAP is LR_ADMAP=Type:Inventory_scenario_id:Time.
Table 2: LR_ADMAP Valid Values
Variable
Input Based on Use Case
Type
For in-stream ads, set to "in".
For overlay ads, set to "ov".
Inventory_scenario_id
The id value associated with a specific scenario.
Time
For in-stream ads, set to "n", where n
is either the number of seconds or the
percentage of time into the content. Ex:
LR_ADMAP=in:test_scenario:100%. Ex:
LR_ADMAP=in::0
For overlay ads, set to "n,m", where n is either
the number of seconds into the content or
percentage of time to start into content and m
is either the number of seconds or percentage
of time into content to stop the overlay. Ex:
LR_ADMAP=ov::10%,100%
PLAYER API REFERENCE | PLAYER API PARAMETERS | 27
вЂў
The following JavaScript code example shows how the use of the liverail-ads-manager as a parameter
of the OO.Player.create function. The only required parameter to display LiveRail ads is the
Publisher ID, or LR_PUBLISHER_ID. The rest of the supported parameters are for targeting purposes.
var videoPlayer = OO.Player.create('playerwrapper', 'embed_code', {
height: '100%',
width: '100%',
'liverail-ads-manager': {
'LR_PUBLISHER_ID': '13517',
...
}
});
There is no integration of LiveRail ad manager and our Mobile SDKs. There is also no LiveRail midroll
support for iOS.
VAST Ads Embedded Parameters
Pass VAST ad server or network tags to the Ooyala player.
VAST is an ad format which uses xml to describe Linear ads (video ads), non-linear ads (overlay ads) and
companion ads. You can pass VAST ad-service-related tags to the Player with the embedded parameters.
Prerequisites
вЂў
вЂў
To use OoyalaвЂ™s VAST ad set, log into the Support Center and submit a ticket requesting that this ad
source be added to your account. Once itвЂ™s enabled, youвЂ™ll be able create ad sets for your player.
In order to use the VAST ad tag embedded parameter, an ad set must also be applied in Backlot and
the ad set must contain a valid VAST ad tag.
At this time support for pre-, mid-, and post-roll ads varies by platform. To see what ad position are
supported for each platform, see Ads Integration Overview.
VAST PARAMETER
Use the vast parameter to pass VAST ad server or network tags to the Ooyala player. The parameter
takes a key value pair representing the ad server or network URL. You can also use vast to change the
ad URL. If the ad URL is updated with the vast parameter, the ad will play when it was set up to play in
Backlot (pre-roll, mid-roll, or post-roll), but the ad content played will be overridden with the new ad URL.
The following example illustrates the use of the vast parameter.
var videoPlayer = OO.Player.create('playerwrapper', 'embed_code', {
height: '100%',
width: '100%',
'vast': {
tagUrl: 'some url',
...
}
});
VASTADS PARAMETER
Note: This parameter is for HTML5 only.
Use the vastAds parameter to programmatically override any VAST ads or ad sets applied in Backlot.
This feature allows you to add VAST ads to an asset or update the VAST ad content and position (pre-roll,
post-roll, and mid-roll) from the player embedded parameters. If ads are set with vastAds, ads and ad
sets associated with the player in Backlot will be completely ignored.
vastAds is a container, where you need to specify all the parameters that an ad uses:
PLAYER API REFERENCE | PLAYER API PARAMETERS | 28
вЂў
вЂў
вЂў
вЂў
вЂў
type: The ad type. Set to "vast".
url: The link to the VAST ad content.
frequency: How often to call the VAST ad. Set to any positive integer.
first_shown: How many videos need to play before the VAST ad is shown. Set to any positive integer.
time: The time (in milliseconds) into the video when the VAST ad will play. Set to any positive integer.
вЂў
вЂў
вЂў
To create a pre-roll ad, set time to 0.
To create a mid-roll ad, set time to any other number within the time of the asset.
To create a post-roll ad, set time to exactly 1000000000.
The following example demonstrates setting up a pre-roll ad and a mid-roll ad using vastAds.
var player = OO.Player.create('playerwrapper', embedCode, {
'vastAds': [{
type: "vast",
url: "http://pubads.g.doubleclick.net/gampad/ads?sz=640x360&iu=/6062/
iab_vast_samples/
skippable&ciu_szs=300x250,728x90&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_posi
frequency: 1,
first_shown: 0,
time: 0
},
{
type: "vast",
url: "http://pubads.g.doubleclick.net/gampad/ads?sz=640x360&iu=/6062/
iab_vast_samples/
skippable&ciu_szs=300x250,728x90&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_posi
frequency: 1,
first_shown: 0,
time: 10000
}]
});
VPAID Ads Embedded Parameters
You can pass VPAID ad-service-related tags to the Player with the embedded parameters.
Note: To use OoyalaвЂ™s VPAID ad module, log into the Support Center and submit a ticket requesting that
this ad source be added to your account. Once itвЂ™s enabled, youвЂ™ll be able create adsets for your player.
Ads positions behave somewhat differently on desktop and mobile devices:
вЂў
Flash Desktop supports all ad positions.
VPAID PARAMETERS
Use the vpaid-ads-manager parameter to pass VPAID Ad Manger tags to the Ooyala player.
Note: To use this parameter, you need to get the Ooyala OPF SDK (1.5.6 or later) and have Flash Builder
4.5 or later. To get the OPF SDK, contact your account manager.
The parameter takes the key value pairs listed in the following topic. adTag and 'some url' . You
need to change the key value pair 'some url' to the actual VPAID Ad Tag containing the response.
The following is an example of the vpaid-ads-manager parameter:
var videoPlayer = OO.Player.create('playerwrapper', 'embed_code', {
height: '100%',
width: '100%',
'vpaid-ads-manager': {
adTag: 'some url',
...
PLAYER API REFERENCE | PLAYER API PARAMETERS | 29
}
});
Key Value Pairs for vpaid-ads-manager
The key value pairs for the vpaid-ads-manager are as follows:
adLayout
When value equals to adjusted, the module will resize the ad, so that controls or marquee don't take space
from it. For example:
adLayout: 'adjusted'
adTag
This value will override the Ad tag for loading the VAST xml file. For example
adTag: 'http://myAdServer.com/myVast'
showInAdControlBar
This value shows the default player control bar. For example:
showInAdControlBar: 'true'
Note: This will not work with layout=chromeless or when the parameter "Always show scrubber bar" is
enabled for the player.
playWhenAdClick
When set to true this value will keep playing the video ads, even if the user clicks the ad and gets
redirected. For example:
playWhenAdClick: 'true'
showAdMarquee
This value will show a white marquee with the message: "Your video will resume in x seconds"
showAdMarquee: 'true'
PLAYER API REFERENCE | PLAYER API PARAMETERS | 30
PLAYER MESSAGE BUS EVENTS
Use message bus events to subscribe to or publish player events from video to ad playback.
The player standard events are shown in the following list. These are default events that are published by
the event bus. Your modules can subscribe to any and all of these events. To get a list of all these default
events that are published by the message bus, you can use the function: OOEvents = вЂњ*вЂќ
Note: You must use the Player APIs and Events for your players (both Flash and HTML5). If you have
existing legacy Ooyala player APIs, they can continue to work for the Ooyala Flash player that is вЂњwrappedвЂќ
by the current Ooyala V3 Player.
EVENTS
The following table describes all the message bus events associated with assets.
Many events return arguments to their callback functions; the meaning of these arguments is listed for
those events that have them.
Some of these events cause "data points" in Ooyala Analytics; that is, a datum is recorded in Analytics
when the event occurs. Some of these are known as "displays", "plays", and "video starts". For more
information, see the Backlot User Guide.
Events
Flash
Html5
Description
Arguments
returned
to callback
function
Analytics Data Point
or Behavior
X
AUTH_TOKEN_CHANGED
Event is triggered when an authorization New value for
auth token
token is issued by the Player
Authorization API.
(For example, in device registration,
an authorization token is issued, as
described in Device Registration.)
ADS_CLICK
X
ADS_FILTERED
An ad has been clicked.
Triggers an Ad
Analytics AD_CLICK
event
X Indicates that some ads may have been Depending on
filtered out
the context,
returns
Note: For VAST and Ooyala ads only
вЂў The current
embed code
вЂў The list of
valid ads
ADS_MANAGER_FINISHED_ADS
X Signals that the ad manager is done
playing ads in its ad slot
ADS_MANAGER_HANDLING_ADS
X Signals that the ad manager is still
playing ads in its ad slot
ADS_PLAYED X
A set of ads have played.
Depending on
context:
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 31
Events
Flash
Html5
Description
Arguments
Analytics Data Point
returned
or Behavior
to callback
function
1. Duration of
ad
2. ID of item to
play
AD_AUTHORIZATION_FETCHED
X Ad authorization data was received (the IDs of ads
authorization data is passed within this affected by
event).
authorization
AD_CONFIG_READY
X An ad set configuration is ready for
insertion and/or play.
Depending
on context, a
pointer to the
ad loader
AUTHORIZATION_FETCHED
X Playback was authorized.
ID of
authorization for
asset
The event returns an object which
returns the value of video_bitrate.
For more information on video_bitrate
see: Video Bit Rate
BITRATE_CHANGED
X
The currently playing bitrate has
changed.
BITRATE_INFO_AVAILABLE
X
Lists the available bitrates
videoBitrate
Depending on
the context,
returns:
вЂў
вЂў
вЂў
вЂў
BUFFERED
BUFFERING
X Play resumes because player has
completed buffering.
The bitrate
qualities
The bitrates
The target
bitrate's
quality
The target
bitrate
URL of stream
X X The player is buffering the data stream.
CHANGE_VOLUME
X X A request to change volume has been
made.
Volume level
CONTENT_TREE_FETCHED
X X A content tree was fetched.
Depending on
context:
1. ID of
current
asset
2. IDs of all
affected
assets
Records a "display".
For discussion, see
Displays, Plays, and
Play Starts.
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 32
Events
Flash
Html5
Description
Arguments
returned
to callback
function
Analytics Data Point
or Behavior
CONTROLS_HIDDEN
X Controls are hidden.
CONTROLS_SHOWNX Controls are shown.
DESTROY
X X The player is currently being destroyed
and anything created by your module
needs to be deleted as well. After the
destruction is complete, there is nothing
left to send an event.
DISABLE_PLAYBACK_CONTROLS
X Disables player controls
DOWNLOADING
X Player is downloading content (could be Time of event
playing while downloading).
EMBED_CODE_CHANGED
X X The playerвЂ™s embed code has changed.
ID (embed
code) of asset
with options
ENABLE_PLAYBACK_CONTROLS
X Enables player controls
ERROR
X X An error has occurred.
Error code
FIRST_AD_FETCHED
X X The first in a set of multiple ads was
fetched.
FULLSCREEN_CHANGED
X X The fullscreen state has changed.
Depending on
context:
1. "Is
fullscreen"
set either
true or false
2. "Is
fullscreen"
set either
true or
false and
"paused"
set either
true or false
GOOGLE_IMA_CAN_SEEK
X Allows seeking in the video
Note: For Google IMA only
GOOGLE_IMA_READY
X Unblocks PLAYBACK_READY event
Note: For Google IMA only
GOOGLE_RESUME_CONTENT
X Unblocks the PLAY event for main video
content
Note: For Google IMA only
GUID_SET
X Is called with the GUID is set
Returns the
GUID
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 33
Events
Flash
Html5
Description
INITIAL_PLAY
Arguments
returned
to callback
function
Analytics Data Point
or Behavior
X When the play is called for the very first
time
LOAD_ALL_VAST_ADS
X Loads all VAST ads
METADATA_FETCHED
X X The metadata (typically set in Backlot)
was retrieved
ID of asset
MIDROLL_PLAY_FAILED
X
An attempt to play a midroll ad has
failed.
The arguments
that were
passed in
MIDROLL_STREAM_PLAYED
X
A midroll stream was played.
PAGE_UNLOAD_REQUESTED
X When the window, document, and its
resources are about to be unloaded
PAUSE
X X A player pause request has been made.
PAUSED
X X The player was paused.
PAUSE_STREAM
PLAY
Returns either
true or false
X An attempt to pause a video stream has
occurred.
X X A playback request has been made.
PLAYBACK_READY
X X The player has indicated that it is in a
playback ready state. All preparations
are complete, and the player is ready to
receive playback commands (such as
play, seek, and so forth). The default UI
shows the Play button (it displays the
non-clickable spinner before this point).
PLAYED
X
The video was played.
PLAYER_CREATED
X X A player was created. This is the first
event that is sent after player creation.
It provides the opportunity for any other
modules to do their own initializations.
PLAYER_EMBEDDED
X
The arguments
that were
passed in
The query
string
parameters
The Flash player has been embedded
on the page
PLAYER_XML_FETCHED
X
The Player XML has been fetched
PLAYHEAD_TIME_CHANGED
X X The playhead time was changed.
Depending on
context:
вЂў
1. The current вЂў
time
2. The
duration
3. The name
of the buffer
First event is вЂњvideo
startвЂќ
Other instances of
event feed the вЂњ%
completedвЂќ data
points
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 34
Events
PLAYING
Flash
Html5
Description
Arguments
returned
to callback
function
4. The seek
range
Analytics Data Point
or Behavior
For discussion, see
Displays, Plays, and
Play Starts.
X X A video is playing.
PLAY_FAILED
X A request to play video has failed.
PLAY_MIDROLL_STREAM
A request to play a midroll stream was
made.
PLAY_STREAM
A notification occurred indicating that
a video stream playback request was
made.
PRELOAD_STREAMX A video stream is preloaded.
SEEK
SEEKED
SEEK_STREAM
The current
time
X A request to perform a seek has
occurred. The playhead is requested
to move to a specific location in
milliseconds. Valid Value: number in
milliseconds.
URL of stream
Seconds to
seek
This signifies that the player has
finished seeking to the requested
position.
X An attempt to move the playhead to a
Number of
position in a video stream has occurred. seconds
SET_EMBED_CODE
X X An attempt has been made to set an
embed code.
Depending on
context:
1. ID (embed
code) of
asset
2. ID (embed
code) of
asset with
options
SINGLE_AD_PLAYED
X Triggered after an individual ad (as
opposed to a group of ads) has played.
SIZE_CHANGED
X The screen size was changed. This
event can also be triggered by an
orientation change for handheld
devices.
STREAM_PAUSED X A video stream was paused.
1. Width of
player
2. Height of
player
Depending on
context:
1. The current
time
2. URL of
stream
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 35
Events
Flash
Html5
Description
Arguments
returned
to callback
function
STREAM_PLAYED X A video stream has played.
Analytics Data Point
or Behavior
Depending on
context:
1. The current
time
2. URL of
stream
STREAM_PLAYINGX An individual video stream is playing.
URL of stream
STREAM_PLAY_FAILED
X An attempt to play a video stream has
failed.
The arguments
that were
passed in
VOLUME_CHANGED
X X The volume has changed.
Current volume
level
WILL_CHANGE_FULLSCREEN
X Triggered before a change was made
to the full screen setting of the player
screen.
Depending on
context, either
true or false.
WILL_FETCH_ADSX Triggered before ads are fetched.
WILL_FETCH_AD_AUTHORIZATION
Triggered before the ad authorization is
fetched.
ID of requested
ad
WILL_FETCH_AUTHORIZATION
X Triggered before an authorization is
fetched.
ID of
authorization
request
WILL_FETCH_CONTENT_TREE
X Triggered before the content_tree is
retrieved.
Passed-in API
request
WILL_FETCH_METADATA
X Triggered before metadata is fetched for Passed-in API
a video.
request
WILL_PLAY
X Triggered before a video is played.
WILL_PLAY_ADS
X X Triggered before an ad is played.
Depending on
context:
1. Duration of
ad
2. ID of item to
play
WILL_PLAY_FROM_BEGINNING
X Triggered before a video is played from
the starting point.
Triggers an
Ad Analytics
AD_IMPRESSION
event
Records a "play".
For discussion, see
Displays, Plays, and
Play Starts.
WILL_PLAY_SINGLE_AD
X Triggered before an individual ad (as
opposed to a group of ads) is about to
be played.
WILL_PLAY_STREAM
X Triggered before an individual video
stream (one video, one ad).
URL of stream
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 36
Events
Flash
Html5
Description
Arguments
returned
to callback
function
Analytics Data Point
or Behavior
WILL_RESUME_MAIN_VIDEO
Triggered before the main video is
resumed.
WILL_SHOW_COMPANION_ADS
X
Triggered before the companion ads are Depending on
shown.
context:
1. ID of all
companions
ads
2. ID of a
single
companion
ad
PLAYER API REFERENCE | PLAYER MESSAGE BUS EVENTS | 37
PLAYER AUTHORIZATION API
The Authorization API request is the key element in Ooyala's content protection features.
A request to the Authorization API has the following syntax:
[GET] /sas/player_api/v1/authorization/
embed_code/pcode/ListOfCommaSeparatedEmbedCodes?query_string_paramters
Example:
http://player.ooyala.com/sas/player_api/v1/authorization/embed_code/
R0Y3Y6HtBEQtRUoC55GY8DTF4pGA/44azdwNDpSWUvfd8F30d55tXY0YH9njH?
device=html5&domain=www.ooyala.com&supportedFormats=m3u8%2Cmp4
ROUTE ATTRIBUTES
The following table describes all attributes of the route.
Attribute
Description
pcode
Your provider code
ListOfCommaSeparatedEmbedCodes
Embed codes (content IDs or asset IDs) must be
separated by commas in this list.
QUERY STRING PARAMETERS
The following table describes the query string parameters of the routes. The request can have several
optional query string parameters following in suit. The only required parameter is domain.
Parameter
Description
Required?
domain
Domain of the player embed.
Yes
timestamp
Timestamp in which the request
was made (epoch time).
No
Default: Time request received by
server
supported_formats
List of comma-separated values
indicating supported formats.
The value of this parameter is
normally tightly coupled with the
device type, since support for
formats is limited by device.
No
Valid Values: Shown in table
below
device
List of comma-separated devices
for playback.
No
PLAYER API REFERENCE | PLAYER AUTHORIZATION API | 38
Parameter
Description
Valid Values: See table below
Required?
jsonp
Value of this parameter will be
used as the wrapper in returning
JSONP.
No
Default: JSON
embed_token
Discussed in section "Ooyala
Player Token" in the Player
Developer Guide.
No
auth_token
Authorization token, discussed in
Enforcing Per-Viewer Limits on
Concurrent Streams
No
SUPPORTED FORMATS AND DEVICES
The supported_formats parameter can be a list of any of the following values, separated by commas.
Format
Value
HDS
hds
RTMP
RTMP
HLS
m3u8
MP4
mp4
Akamai HD
akamai_hd
Widevine HLS
wv_hls
Widevine MP4
wv_mp4
Widevine WVM
wv_wvm
Adobe Access HLS
faxs_hls
MicroSoft Smooth Streaming.
smooth
Note: For smooth streaming, device (see below)
must be GENERIC.
The device parameter can be a list of any of the following values, separated by commas:
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
IPHONE
IPAD
APPLE_TV
ANDROID_SDK
ANDROID_3PLUS_SDK
ANDROID_HLS_SDK
HTML5
GENERIC_FLASH
GENERIC
PLAYER API REFERENCE | PLAYER AUTHORIZATION API | 39
RESPONSE FROM THE AUTHORIZATION API
When the caller makes an authorization request, the Authorization API responds to the caller with a JSON
array indicating the authorization status for each of the embed codes included in the list in question. The
following is a sample response from the Authorization API:
{
"debug_data": {
"server_latency": "21.919",
"request_id": "domU-12-31-39-0B-D2-11_1346804527_57",
"user_info": {
"ip_address": "204.124.203.201",
"continent": "NORTH AMERICA",
"country": "US",
"request_timestamp": "1346804527",
"language": "en-us",
"device": "html5",
"timezone": -7,
"domain": "www.ooyala.com"
}
},
"signature": "0pobcTRSLoiSZchrMI7Aeoub05/OKRIavq36BgW74lU=\n",
"authorization_data": {
"44azdwNDpSWUvfd8F30d55tXY0YH9njH": {
"authorized": true,
"message": "authorized",
"code": "0",
"request_timestamp": "1346804527",
"retry": null,
"streams": [
{
"delivery_type": "hls",
"url": {
"data":
"aHR0cDovL3BsYXllci5vb3lhbGEuY29tL3BsYXllci9pcGhvbmUvNDRhemR3TkRwU1dVdmZkOEYzMGQ1NXRYWT
"format": "encoded"
}
}
]
}
}
}
ELEMENTS OF THE RESPONSE
The significant portions of the response are in boldface type in the sample. These parts of the response
are:
1. debug_data is used only for debugging data. It can change at any time.
2. signature in the response (discussed in the following section, How the Output Is Signed) is used to
ensure that the response has not been tampered with by a 3rd party. The most significant hash is
the вЂњauthorization-dataвЂќ hash, which includes the result of the authorization request. Below are all the
enumerations for possible codes:message pairs (authorized has a binary true/false value). This list can
continue to change as we add additional parameters to authorization, providing more system visibility
into the potential failure.
PLAYER API REFERENCE | PLAYER AUTHORIZATION API | 40
3. streams are included if the embed code was authorized, including the base64 encoded url to access
those streams. Each stream can return with an authorization result of:
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
вЂў
"authorized"
вЂњunauthorized parent"
"unauthorized domain"
"unauthorized location"
"unauthorized device"
вЂњcurrent time is before the flight start time" (before flight start time)
"current time is after the flight end time" (after flight end time)
"current time is outside any availability period" (outside recurring flight times)
"this is not a recognized embed code"
"invalid signature" (invalid signature in the request, potentially when using token based playback)
"missing parameters" (required parameters are missing)
"missing rule set" (when authorizing using a rule set rather than a syndication group)
вЂњunauthorizedвЂќ (this message rarely, if ever, used, in favor of more specific messages)
"missing pcode",
"invalid token" (error code for token based playback and Adobe Pass)
For response that includes a Widevine stream, the additional property widevine_server_path is
returned. This value should be passed along with the stream URL to the playback SDKs for obtaining the
Widevine license and decrypting the token.
{
"authorization_data":{
"huNWp2NjoCaCKrsV_wqBdcSw9P1XmlwW":{
...
"streams":[
{
"delivery_type":"wv_wvm",
"url":{
...
},
"widevine_server_path":"http://player.ooyala.com/sas/drm2/
lvcjAxOj82_rjlIAJ6Jr8ZZqGP-s/huNWp2NjoCaCKrsV_wqBdcSw9P1XmlwW/widevine/
ooyala"
}
]
}
},
"debug_data": ...,
"signature":"Fo6ewzq2tTrLJrFmjo5eQpeKUOoLvhSen7KLjrFU1YQ=\n"
}
For per-viewer concurrent stream limits, additional properties are returned, as detailed in Enforcing PerViewer Limits on Concurrent Streams.
PLAYER API REFERENCE | PLAYER AUTHORIZATION API | 41
FLASH-BASED PLAYER ERROR MESSAGES
Error messages are displayed to the video viewer or audio listener during playback. Errors can be
categorized as general errors, Flash-based errors and Pay-Per-View errors, which are prefixed with a PPV.
These error messages pertain to both V2 and V3 of the Flash player.
Error
Message Displayed to User
ACCOUNT_DISABLED
Account has been disabled.
ADOBE_PASS_ASSET_NOT_AUTHENTICATED
This asset is not authenticated by adobe pass
ADOBE_PASS_LIBARY_NOT_DEFINED Please include Adobe Pass Javascript Library
ADOBE_PASS_LIBARY_NOT_DEFINED Please include Adobe Pass Javascript Library
ADOBE_PASS_REQUIRE_JAVASCRIPT Please enable Javascript for your embed.
ADOBE_PASS_USER_NOT_AUTHORIZEDPlease login into your MVPD account!
Video no longer available
AFTER_FLIGHT_TIME
API_DYNAMIC_AD_SET_IS_NOT_ENABLED_FOR_PROVIDER
The dynamic ad sets feature is not enabled for this provider OR
Invalid API Usage.
API_EXPIRATION_IN_PAST
Expiration time must be ahead of current time OR Invalid API
Usage.
API_EXPIRATION_NOT_IN_WHOLE_HOURS
Expiration time must be rounded to the nearest hour OR Invalid
API Usage.
API_EXPIRATION_TOO_FAR_IN_FUTURE
Expiration time can be no more than {0} hours later than current
GMT time OR Invalid API Usage.
API_INVALID_DYNAMIC_AD_SET_ASSIGNMENT
The specified ad set code does not belong to the provider OR
Invalid API Usage.
API_INVALID_DYNAMIC_AD_SET_CODE
The specified ad set code is invalid OR Invalid API Usage.
API_STANDALONE_AD_SET_IS_EMPTYThe specified ad set does not have any instream ads. OR Invalid
API Usage.
Error generating player response.
BAD_RESPONSE
BAD_SECURE_STREAMING_RESPONSE Malformed streaming token.
BEFORE_FLIGHT_TIME
Available in {0} OR Video available soon
CANNOT_CONTACT_SAS
Cannot contact authorization server.
CANNOT_CONTACT_SERVER
Please check back later.
CANNOT_DOWNLOAD_THIRD_PARTY_MODULE
Problem downloading the third-party module {0}.
CANNOT_FETCH_PAY_PER_VIEW_STATUS
There was an error requesting the payment status.
CANNOT_FETCH_SECURE_STREAMING_TOKEN
Cannot initialize the stream securely.
CANNOT_PARSE_PAY_PER_VIEW_STATUS_RESPONSE
Bad payment status.
CANNOT_RETRIEVE_DOMAIN
Browser failed to report authentication info. Please make sure
that JavaScript is enabled.
CANNOT_SECURELY_STREAM_VIDEO
This video cannot be played securely.
CONTENT_OVER_CAP
This content has been disabled by the provider.
PLAYER API REFERENCE | FLASH-BASED PLAYER ERROR MESSAGES | 42
Error
Message Displayed to User
CONTENT_UNAVAILABLE
Content Unavailable.
CORRUPTED_NETSTREAM
Flash settings prohibit playing video.
DYNAMIC_AD_SET_IS_NOT_ENABLED_FOR_PROVIDER
The dynamic ad sets feature is not enabled for this provider.
EMPTY_CHANNEL
This channel is empty.
EMPTY_CHANNEL_SET
This channel set is empty.
EXPIRATION_IN_PAST
Expiration time must be ahead of current time.
EXPIRATION_NOT_IN_WHOLE_HOURS Expiration time must be rounded to the nearest hour.
EXPIRATION_TOO_FAR_IN_FUTURE
Expiration time can be no more than {0} hours later than current
GMT time.
FLASH_ACCESS_LICENSE_UNAVAILABLE
License server unavailable at this time. Please try again later.
INTERNAL_ERROR
Internal player error occurred.
INTERNAL_PLAYER_ERROR
Error generating player response.
INVALID_API_USAGE
Invalid API Usage.
INVALID_CONTENT
Invalid content specified.
INVALID_CONTENT_SEGMENT
Invalid content segment (not localized)
INVALID_DYNAMIC_AD_SET_ASSIGNMENT
The specified ad set code does not belong to the provider.
INVALID_DYNAMIC_AD_SET_CODE
The specified ad set code is invalid.
INVALID_DYNAMIC_CHANNEL_USAGE Invalid dynamic channel usage.
INVALID_FLASH_ACCESS_LICENSE
Content not authorized. Invalid license. NOTE: This first string
is NOT localized and currently unused.
INVALID_RESPONSE
Invalid server response.
INVALID_SAS_RESPONSE
Invalid authorization response.
INVALID_SERVER_RESPONSE
Invalid server response.
INVALID_TOKEN
You don't have a valid token to view this video.
LIVE_STREAM_FILE_NOT_FOUND
The requested bitrate for this live stream is not currently
available.
LIVE_STREAM_FINISHED
This live stream is over.
LIVE_STREAM_FINISHED_TITLE
Stream Over.
LIVE_STREAM_UNAVAILABLE
Live Stream is off-air.
LIVE_STREAM_UNAVAILABLE_AFTER_PAYMENT
Please come back later to watch your purchased content.
LONG_BEFORE_FLIGHT_TIME
Video available soon
LOST_CONNECTION
Lost Connection.
NO_CONNECTION_PLAYER
Problem downloading the player. Please check your Internet
connection.
NO_CONNECTION_VIDEO
Problem downloading the video. Please check your Internet
connection.
NO_MOVIE_SPECIFIED_FOR_LABELS No movie specified for labels.
PLAYER API REFERENCE | FLASH-BASED PLAYER ERROR MESSAGES | 43
Error
Message Displayed to User
NO_QUERY_STRING_CODE
No code specified in embed.
PPV_ALREADY_PAID
You have already paid for this {0}. Your account has not been
charged.
PPV_CANCEL_PURCHASE
Cancel purchase.
PPV_CHANGE_MIND
Change your mind?
PPV_CHECKOUT_ERROR
There was an error during the checkout process.
PPV_DEFAULT_MESSAGE
This {0} cannot play anymore.
PPV_IS_EXPIRED
This {0} has expired. To continue watching, please buy it again.
PPV_NEEDS_TO_PAY
To keep watching this {0}, buy it now for:
PPV_NEEDS_TO_PAY_AT_START
To start watching this {0}, buy it now for:
PPV_NO_MORE_PLAYS_TODAY
This {0} has reached the maximum amount of plays for today. To
continue watching, please buy it again.
PPV_NO_MORE_PLAYS_TOTAL
This {0} has reached the maximum amount of plays. To continue
watching, please buy it again.
PPV_PREPURCHASE
{0} has not started yet. You can pre-purchase it now for:
PPV_PREPURCHASE_THANK_YOU
Thank you for your purchase. Please come back later to watch
this {0}.
PPV_PURCHASE_IN_PROGRESS
Purchase in progress...
PPV_SUPPORT_MESSAGE
For assistance you can visit the <u><a target '_blank' href ' http://
support.ooyala.com/t5/Ooyala-Support-Center/Why-can-I-notview-the-video-I-purchased/ta-p/975 '>support page</a></u> or
try to repurchase the {0}.
PPV_VIEW_UNAUTHORIZED
This {0} cannot be authorized to play.
PPV_WATCH_VIDEO
Watch video.
PROCESSING_CONTENT
The requested content is being processed.
PROXY_CLASSES_DONT_WORK
Proxy classes aren't properly initialized in the root SWF. Check
the Ooyala Player API documentation for the correct way to
initialize proxy classes when you embed the Ooyala Player
REMOVED_CONTENT
The requested content has been removed.
SAS_AUTH_FAILED
Cannot authorize video.
SAS_HEARTBEAT_FAILED
Authorization failed
SAS_TOO_MANY_ACTIVE_STREAMS
Too many open videos
SECURE_STREAMING_AUTH_FAILED
Authorization to play this video has failed.
STANDALONE_AD_SET_IS_EMPTY
The specified ad set does not have any instream ads.
STREAM_FILE_NOT_FOUND
The requested bitrate is not currently available.
TOKEN_EXPIRED
Your authentication token expired. Try reloading your page.
UNAUTHORIZED_DEVICE
This video is not authorized for playback on this device.
UNAUTHORIZED_DOMAIN
The video is not authorized for this domain ({0}). Please contact
the administrator.
PLAYER API REFERENCE | FLASH-BASED PLAYER ERROR MESSAGES | 44
Error
Message Displayed to User
UNAUTHORIZED_DYNAMIC_CHANNEL
You are not authorized to see the content. Please contact the
administrator.
UNAUTHORIZED_LOCATION
The video is not authorized for your location ({0}).
UNAUTHORIZED_PARENT
Sorry, there are no videos to view in this channel.
UNAUTHORIZED_PAY_PER_VIEW
Pay Per View Unavailable.
UNAUTHORIZED_USAGE
Unauthorized usage.
UNKNOWN_ACCOUNT
Unknown account specified.
UNKNOWN_CONTENT
Unknown content specified.
UNKNOWN_DOMAIN
To view this content you have to enable JavaScript in your
browser.
UNKNOWN_SAS_CONTENT
Unknown content specified.
VERSION
Flash player upgrade needed.
VERSION_NOT_SUPPORTED
Flash player {0} or above is required.
VERSION_UPGRADE_LINK
http://www.adobe.com/products/flashplayer/ .
VERSION_UPGRADE_TEXT
Click here to upgrade.
PLAYER API REFERENCE | FLASH-BASED PLAYER ERROR MESSAGES | 45

Download Report