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.