Configuration API

Configuration

For a user guide and examples on configuring advertisements in THEOplayer, take a look at our Advertising Guide.

For an example of how to use the slow motion and high speed playback, take a look at our Slow Motion and High Speed Playback support page.

The configuration object can have the following properties:

Property	Type	Optional	Description
ads	AdsConfiguration	yes	An AdsConfiguration object that configures the advertisements for the player instance.
chromecast	boolean OR ChromecastConfiguration	yes	'true' or 'false' to use the standard Chromecast app. A ChromecastConfiguration to configure a custom Chromecast app. Default value is 'false'.
enableKeyboardShortcuts	boolean	yes	Enables keyboard shortcuts for the player. Default value is 'true'.
initialRendition	'default' OR 'high' OR 'low' OR 'first'	yes	Sets the starting rendition of the player. This rendition is active until the Adaptive Bitrate algorithm has gathered sufficient data to control the rendition behaviour. high will pick the highest bitrate available, low will pick the lowest available bitrate, first will pick the first bitrate listed in the manifest, default uses the browser/device default starting rendition. Default value is 'default'.
isEmbeddable	boolean	yes	Sets whether the THEOplayer instance can be used for playback inside iframes on unlicensed domains.
playbackRates	number[] OR {value : number , label : string}[]	yes	Provides the player with an array of playback rates, 1 being the equivalent of normal playback speed. Value-label pairs give the player a value as a playback rate and a user-readable title when displaying the available rates. By default a playback rate of 1 is selected.
playlist	Playlist	yes	A Playlist object that provides THEOplayer with a list of sources and their metadata and configurations.
socialSharing	string OR SocialSharingConfiguration	yes	Configures the player to send authentication cookies with http requests. Default value is 'false'.
withCredentials	boolean	yes	Configures the player to send authentication cookies with http requests. Default value is 'false'.

SourceConfiguration

When using a SourceDescription object to set source of a THEOplayer instance, the SourceConfiguration object can be included with the SourceDescription to configure the THEOplayer instance.

For an example of how to use the startFrame and endFrame properties, take a look at our Frame Accurate Clipping support page.

The SourceConfiguration object has the following properties:

Property	Type	Optional	Description
ads	AdsConfiguration	yes	An AdsConfiguration object that configures the advertisements for the player instance.
crossOrigin	string	yes	This optional property can be used to configure the cross-origin requests for this source. Values are "" (empty string), "anonymous" or "use-credentials". Default is "".
endFrame	number	yes	The ending frame where the source will be clipped.
endTime	number	yes	The ending time where the source will be clipped.
initialRendition	'default' OR 'high' OR 'low' OR 'first'	yes	Sets the starting rendition of the player. This rendition is active until the Adaptive Bitrate algorithm has gathered sufficient data to control the rendition behaviour. high will pick the highest bitrate available, low will pick the lowest available bitrate, first will pick the first bitrate listed in the manifest, default uses the browser/device default starting rendition. Default value is 'default'.
metadata	Configuration Metadata	yes	Configuration metadata for the media item. This metadata will be used for communication with external applications/platforms, eg. Google Chromecast
nielsen	NielsenConfiguration	yes	A NielsenConfiguration object that allows THEOplayer to interface with the Nielsen DTVR Browser SDK.
startFrame	number	yes	The starting frame where the source will be clipped.
startTime	number	yes	The starting time where the source will be clipped.
withCredentials	boolean	yes	Configures the player to send authentication cookies with http requests. Default value is false.

Configuration Metadata

You can find an example of how to use the metadata object on our Chromecast support page.

The configuration metadata contains the following properties:

Property	Type	Optional	Description
images	{ src : string , width? : number , height? : number }[]	yes	An array of images that describe the media item. Constructed as an object with a URI to the image and optionally a width and height of the image.
releaseDate	string	yes	The release date of the media item.
releaseYear	number	yes	The release year of the media item.
subtitle	string	yes	The subtitle of the media item.
title	string	yes	The title of the media item.
type	'MOVIE' OR 'AUDIO' OR 'TV_SHOW' OR 'GENERIC'	yes	The content type of the media item.

AdsConfiguration

For the full user guide, go to our Advertising Guide.

The AdsConfiguration object contains the following properties:

Property	Type	Optional	Description
banners	BannerConfiguration OR BannerConfiguration[]	yes	A BannerConfiguration object or array of BannerConfiguration objects to configure the banners that will be shown on the player instance.
blockOnAdBlock	boolean	yes	Whether or not the player should block playback when the user has an AdBlocker active. Default value is false.
vast	VASTConfiguration OR VASTConfiguration[]	yes	A VASTConfiguration object or array of VASTConfiguration objects to configure the VAST ads that will be shown in the player instance.
vmap	VMAPConfiguration	yes	A VMAPConfiguration object to configure the VMAP ads that will be shown in the player instance.

BannerConfiguration

A BannerConfiguration object contains the following properties:

Property	Type	Optional	Description
clickURL	string	yes	The target URI when a player clicks the banner.
closable	boolean	yes	Defines whether or not the banner can be closed before its endtime.
endTime	number OR string	yes	The time (in seconds) or percentage of video done when the banner should appear.
imageURL	string	no	A URI to the banner image.
maxHeight	string	yes	The maximum height of the banner on the video.
opacity	number	yes	Value from 0.0 to 1.0 that specifies the opacity/transparency of the banner image.
startTime	number OR string	yes	The time (in seconds) or percentage of video done when the banner should appear.

VASTConfiguration

A VASTConfiguration object contains the following properties:

Property	Type	Optional	Description
addCompanionRequest	callback function	yes	A hook for a callback function that handles the requests for companion ads on your web page.
offset	number OR string OR 'pre' OR 'post'	yes	The timing when the ad should play. Can be  time (in seconds), percentage of video done, 'pre' for preroll or 'post' for postroll.
skip	number	yes	The time (in seconds) when the ad becomes skippable. 0 makes the ad unskippable.
url	string	no	A url to the VAST configuration xml file.

VMAPConfiguration

A VMAPConfiguration object contains the following properties:

Property	Type	Optional	Description
addCompanionRequest	callback function	yes	A hook for a callback function that handles the requests for companion ads on your web page.
skip	number	yes	The time (in seconds) when the ad becomes skippable. 0 makes the ad unskippable.
url	string	no	A url to the VMAP configuration xml file.

NielsenConfiguration

A NielsenConfiguration object contains the following properties:

Property	Type	Optional	Description
apid	string	no	Unique ID assigned to the player/site and configured by product.
apn	string	no	Access Point Name.
metadata	NielsenMetadata	no	Metadata that will be passed to the Nielsen DTVR Browser SDK.
sfcode	'cert' OR 'us'	no	Location of collection environment.

NielsenMetadata

A NielsenMetadata object contains the following properties:

Property	Type	Optional	Description
channelName	string	no	Channel name of the ID3 Feed.

Playlist

For an example of how to use the Playlist feature, go to our Playlist support page.

A Playlist object contains the following property:

Property	Type	Optional	Description
sources	PlaylistSource[]	no	A list of source entries for the playlist.

PlaylistSource

A PlaylistSource object contains the following properties:

Property	Type	Optional	Description
ads	AdsConfiguration	yes	An AdsConfiguration object that configures the advertisements for the player instance.
description	PlaylistSource[]	yes	A list of source entries for the playlist.
endFrame	number	yes	The ending frame where the source will be clipped.
endTime	number	yes	The ending time where the source will be clipped.
poster	string	yes	URI to the content poster of the media item.
src	string	no	URI to the media item's master manifest.
startFrame	number	yes	The starting frame where the source will be clipped.
startTime	number	yes	The starting time where the source will be clipped.
title	string	yes	The title of the media item.

ChromecastConfiguration

A ChromecastConfiguration object contains the following properties:

Property	Type	Optional	Description
appID	string	no	The application ID of your registered custom Chromecast application.
namespace	string	no	The namespace that identifies the protocol that the custom Chromecast application uses to send messages.

SocialSharingConfiguration

A SocialSharingConfiguration object contains the following properties:

Property	Type	Optional	Description
facebook	SocialSharingFacebookConfiguration	yes	The configuration object that defines all the parameters for sharing to Facebook.
mail	SocialSharingMailConfiguration	yes	The configuration object that defines all the parameters for sharing through an email message.
permalink	SocialSharingPermalinkConfiguration	yes	The configuration object that defines all the parameters for sharing a permalink.
tumblr	SocialSharingTumblrConfiguration	yes	The configuration object that defines all the parameters for sharing to Tumblr.
twitter	SocialSharingTwitterConfiguration	yes	The configuration object that defines all the parameters for sharing to Twitter.

SocialSharingFacebookConfiguration

A SocialSharingFacebookConfiguration object contains the following properties:

Property	Type	Optional	Description
app_id	string	no	Your app's unique identifier.
display	string	yes	Determines how the dialog is rendered. If you are using the URL redirect dialog implementation, then this will be a full page display, shown within Facebook.com. This display type is called page. If you are using one of our iOS or Android SDKs to invoke the dialog, this is automatically specified and chooses an appropriate display type for the device. If you are using the Facebook SDK for JavaScript, this will default to a modal iframe type for people logged into your app or async when using within a game on Facebook.com, and a popup window for everyone else. You can also force the popup type when when you use the Facebook SDK for JavaScript, if necessary. Mobile web apps will always default to the touch display type.
href	string	no	The link attached to this post. Required when using method share. Include open graph meta tags in the page at this URL to customize the story that is shared.
redirect_uri	string	yes/no	The URL to redirect to after a person clicks a button on the dialog. Required when using URL redirection.

SocialSharingMailConfiguration

A SocialSharingMailConfiguration object contains the following properties:

Property	Type	Optional	Description
body	string	no	The body of your social sharing email message.
subject	string	yes	The subject line of your social sharing email message.

SocialSharingPermalinkConfiguration

A SocialSharingPermalinkConfiguration object contains the following properties:

Property	Type	Optional	Description
url	string	no	The URL that will serve as the permalink to the video.

SocialSharingTumblrConfiguration

A SocialSharingTumblrConfiguration object contains the following properties:

Property	Type	Optional	Description
caption	string	no	The caption that you want to add to the video on Tumblr.
url	string	no	The URL to the video.

SocialSharingTwitterConfiguration

A SocialSharingTwitterConfiguration object contains the following properties:

Property	Type	Optional	Description
hashtags	string	no	All the hashtags you want to add to the video, as a comma-separated list.
url	string	no	The URL to the video.
text	string	no	The text of your tweet.