Universal Web Player SDK Version 3

Introduction

With the upcoming Chrome 55 release Adobe Flash Player plugin support will be phased out based on a gradually increasing threshold of user’s site engagement metric. As a response to this phasing out, we have re-architectured the core media playback related parts of the SDK.

Now with version 3 SDK, the player evaluates browser capabilities needed for playing the media formats provided. Prioritizing streaming formats (HLS and MPEG-DASH) over progressive formats (MP4), the player SDK now plays media using MSE (Media Source Extensions) on browsers supporting MSE specification. For those lacking the support, HTML5 Video (prioritized over Flash Player) or Flash Player is used as part of the fallback media module.

This change in architecture does not require any change in publishers’ player integration workflows other than changing the player SDK URL since the player SDK services, events, API methods and errors are still the same.

What is new in version 3?

The player SDK Version 3 together with increased customizability and performance brings the following new features:

Playback

MSE based HLS playback is now supported on desktop and mobile browsers. Adobe Flash Player plugin is not needed anymore.

Timed metadata extraction is now available on Android browsers which was the only platform lacking this feature due to the dependency on native support. This feature is useful for more timely schedule information and more accurate analytics services across all platforms.

Closed captions

Embedded closed captions are now supported for HLS stream on Android browsers.

360 view

360 view feature is now available on desktop and Android browsers. In order to enable this feature a source video created using equirectangular view format must be published and provided to the SDK. And the embed parameter 360 must be set to true to enable the renderer on the player SDK. Safari browsers are currently not supported due to their lacking the WebGL CORS support which is necessary for 360 view.

Mobile autoplay and inline playback

Previously playback could be initiated only with user gesture on mobile browsers. Now that recent mobile browsers allow muted autoplay, the player SDK now honors the usual autoplay embed parameter for VOD content and default desktop autoplay behavior for live content on mobile browsers (those on iOS 10+ and Chrome for Android 53+).

Inline playback is now the default playback mode for mobile devices. It is possible to override this feature by setting the inlinePlayback embed parameter.

Ads

All client-side ad plugins (DFP, FreeWheel) are now only JS based. Flash based ad libraries not supported anymore.

Server-side stitched ad features are now fully available on desktop and mobile browsers.

Even if the player SDK falls back to use Flash media module (due to the browser's lacking MSE support), the ad services are still provided via JS library and plugins thank to the latest architecture.

Analytics

Even if the player SDK falls back to use Flash media module (due to the browser's lacking MSE support), the analytics services are still provided via JS library and plugins thank to the latest architecture.

Requirements for publishers

Make sure that CORS headers are set for media assets (master, rendition and ts segments -applies to the publishers managing the CDN themselves- )

Remove Android intent player parameter from configuration since it is not needed anymore.

Player Files

This file contains the modules needed for dynamic IFRAME generation, player initialization, parsing the parameters and establishing communication between the client page and the player instance.

anvplayer.min.js

This file contains the main player modules and player manager module which detects the browser capabilities and invokes the suitable HTML5/MSE/DASH media modules.

anvload.html

Starter page utilized for IFRAME embed option.

anvhtml5.css

HTML5 player style sheet.

Browser Support

Universal Web Player SDK Version 3 provides HLS playback using the MSE (Media Source Extensions) on the following supported browsers:

IE 11 on Windows 8+

Edge 12+

Firefox 42+

Chrome 31+

Safari 8+ on MacOS

Android Browser 4.4.4 and 53+

Chrome 55+ for Android

Firefox for Android 50+

All Safari browser versions on iOS and Safari browser versions less than 8 on MacOS provide native HLS support while lacking the MSE support. This means limited access to the fine tuned bitrate switch.

On remaining browsers which lack native HLS support and MSE support, the player SDK apply the following fallback evaluation:
If the content is VoD and there exists MP4 format in the source, the MP4 asset is played using HTML5 video based media module.

The browsers that support MPEG-4/H.264 video format while lacking the above MSE/native HLS support are:

IE 9-11 (IE 11 on Windows version less than 8)

Firefox 35-42

Chrome 5-30

Android Browser 4.4

In the absence of MP4 format in the source or MP4 support on the desktop browser, the HLS asset is played using Flash based media module. These browsers are similar to above:

IE 9-11 (IE 11 on Windows version less than 8)

Firefox 35-42

Chrome 5-30

Features

Entitlement: The SDK works hand-in-hand with major authentication/authorization services such as Adobe Pass, common in-house subscription and authorization APIs.

Analytics: The SDK is integrated with the majority of analytics services in the industry such as Adobe Analytics, Comscore, Nielsen, Google Analytics and Anvato Analytics.

Ad integration: The SDK provides full support for server-side ad insertion and client side ads. Major ad servers such as FreeWheel and Google DFP are pre-integrated.

Closed captions: Multi-language FCC compliant subtitles are supported on all desktop and the mobile platforms. Your viewers can display, style and manage closed captions in multiple languages with no extra effort. Additionally, the viewers can search the captions and seek to the matching time location instantly.

Social share: The viewers can share your content via wide range range of social networks/platforms and simply sending an email on the player.

video: video ID (This is provided by MCP once you save a video there).

Playing a playlist

Player provides multiple options for playing a playlist.

Playlist from MCP

MCP provides options to create automatically generated feeds based on categories or manual feeds generated by adding multiple videos. Either feed/playlist is identified by a playlist ID. In order to play such a feed providing the following parameters is sufficient:

pInstance: player instance ID. This parameter is used for mapping the player with the configuration entered in data-anvp attribute to the placeholder id,

url: URL for the external video.

live: Live flag for the external video.

format: Video container format (mp4, m3u8, etc.),

Some features such as scrubber preview, poster image and metadata will not be available for external video files. Among them poster image, title and description can be provided as embed parameters optionally.

title: The video title that will be displayed on the splash, pause and hover screen,

Setting the player size

The width and height of the player can be set using the embed parameters width and height. The values must be in pixel and specified with "px" suffix, e.g. "width": "720px". If not specified, the player will use 640 x 360 default size.

Dynamic Resizing

Dynamic resizing is available by setting the width with a value in percent. For instance; "width":"80%" will automatically adjust the height using the aspect ratio on window resize/orientation change events.

A comprehensive list of parameters are provided in IFRAMED JS Embed Option section.

Development Guide

Embed Options

Embedding with the SCRIPT tag

This is the embed option we will be covering in this development guide. Publishers are supposed to use this option to use entitlement services, companion ads, dynamic resizing (keeping the aspect ratio) and get the maximum performance in terms of page load time.

The SDK embeds the player inside a dynamically generated IFRAME. The SDK accesses the player instance using API methods and events from the parent page in which the player is embedded.

Embedding with the IFRAME tag

This embed option is available for the viewers of your content as an IFRAME embed code from the social share view of the player. Additionally, the publishers making use of AMP pages can use this option to embed a player on their AMP compliant pages.

Configuration

Common configuration

In order to enter the plugin configuration, first create an anvp object which will be used a namespace for the Anvato Universal Player objects and configuration. If you need multiple players on the same page with some common configuration and some separate configuration, create a common object under the anvp namespace. Write the common configuration under the config object of anvp.common.

The common configuration can be overridden inside player specific configuration.

Player Specific Configuration

Each player needs to have an instance name represented with pInstance. Create a config object under an empty object named with player instance using anvp namespace. Plugin information can be entered in plugins entry using the format on the right.

Remote Configuration

Instead of entering comprehensive parameters for common work flows, the SDK user may prefer using the remote configuration. This remote configuration is activated using the embed parameter accessKey. While using the remote config, the parameters in remote configuration can be overridden using the common or player specific configuration.

Previously, it was sufficient to remove an entry of a feature to disable it. While using accessKey, the features such as preview must be explicitly set to false in order to disable it.

Generating a token

The token provides security for the media assets and it must be included in the player init config in order to play media from MCP. While the token can be obtained from MCP in the embed code generated, common workflows will require implementing a token generator for a backend service and generating asset specific tokens.

Generating Token in JSON Web Token (JWT) Format

This token is generated in accordance with the standard JSON Web Token (JWT) format. JWT is an open standard (RFC 7519) that defines a compact and self-contained way for authenticating information between parties as a JSON object.

Time-to-live for the token in seconds. A value of 3600 means the token expires 1 hour after creation

No

ip

String

The client IP to associate the token to. This is an extra layer of security but it may also prevent legitimate clients from playing the content if they are NAT'ed and obtain different IPs for different requests.

Embedding Player

You can determine the location of player optionally by creating a div element and assigning it the player instance id.

Now write the following script tag in which you can enter player configuration and define player instance id (pInstance).

Configuration Priority

Values defined inside data-anvp attribute can also be defined inside player specific configuration or common configuration instead. However, pInstance must be always defined inside data-anvp attribute. These configurations will be used by the player after being merged using the following precedence:

Used to prevent the player from starting the main content before a client-side preroll is loaded. Default is false.

expectPrerollTimeout

Number

Max number of seconds to wait for a client-side preroll before starting the main content. Only used when expectPreroll is true. Default is 5.

companions

Array of Objects

Used for registering companion containers with their width and height. Each object has the following format: {width:160, height:600, containers:["companion-holder-1"]}

logo

Object

Used for setting a logo overlay. Logo can be set using the API method: setLogo(). Logo object must have the following format: { url:”LOGO_URL”, targetURL:”YOUR_TARGET_URL” , location: “BR”, margin: “3%”, sizeFactor:.8 }

recom

Boolean or Object

Used for enabling recommendation window. Providing true will use recommendations from MCP. Providing false will disable recommendations. To use custom recommendations, provide an object of the form { items: [...] } where the items array has the same format as the vList argument in the Player.setRecommendations(vList) API function. To use a feed from MCP for recommendations, provide an object of the form { type: "feed", id: FEED_ID }. Default is false.

maxRecomPages

Number

Used to determine the maximum number of recommendation pages to show at the end of a playlist. Default is 3.

share

Boolean

Used for disabling the share feature. Default is true.

shareLink

String

Used for overriding the share link detected by the player

clientSideAdTracking

Boolean

Used for pinging the tracking URL specified in VAST to demonstrate ad progress. Default value is true.

trackTimePeriod

Integer

Used for setting the TIME_UPDATED event period. This value must be to at least 1 (in second). TIME_UPDATED event will not be dispatched if this value is not set to a valid value.

control

Boolean

This flag is used for removing the player controls.

info

Boolean

This flag is used for removing the components providing info about the content such as title, description, poster image, etc.

360

Boolean

Used for enabling 360 view feature

styleNativeCaptions

Boolean

For videos that would normally use the browser's native caption settings and styling, setting this flag to true will cause the captions to use the Anvato player's caption settings and styles instead.

preferredCdn

String

Used for setting a priority of streams based on CDN name where SDK has multiple equivalent best options such as multi-bitrate HLS streams. Case insenstive and regular expressions are allowed.

nativeHlsOnSafari

Boolean

Used for forcing native HTML5 video playback for HLS on Safari instead of Anvato's MSE player. Note that when this is true, the player is no longer able to track server-side ads. Default is false.

nativeHlsOnSafariForVod

Boolean

Similar to nativeHlsOnSafari, but only applies to VOD and not live streams. Default is false.

nativeHlsOnSafariForLive

Boolean

Similar to nativeHlsOnSafari, but only applies to live streams and not VOD. Default is false.

learnMore

Object

Used for styling the Learn More button displayed during DFP client-side ads on mobile devices. Learn More object must have the following format: { text:"YOUR_TEXT", sizeFactor:.8, ... } where the rest of the parameters correspond to CSS styles.

initialBitrate

Number

Used for overriding the initial rendition the SDK will select. The value must be specified in kbps. The SDK chooses the rendition with bitrate value closest to specified initialBitrate

autoBitrateSwitch

Boolean

Used for disabling the SDK's default auto bitrate switch. Once disabled the SDK will use the initial bitrate value (either SDK default or specified value with initialBitrate).

disableAutoBitrateSwitchCap

Boolean

By default, the player caps the maximum bitrate that it will select for automatic bitrate switches based on the player size. Setting this parameter to true will disable this cap. Default is false.

autoBitrateSwitchCapScale

Number

A value used to scale the automatic bitrate switch cap that is based on the player size. For example, 0 will force the player to automatically use the lowest bitrate rendition, 1 will use the default bitrate switch cap, 2 will double the bitrate switch cap, etc.

pauseOnClick

Boolean

Allows the user to pause the video when clicking on the video instead of the pause button specifically. Default is false.

Preview parameters are used for providing temporary access to the protected content. These parameters must be entered inside accessControl property in entitlement parameters.

Entry

Parameters

Definition

preview

long

MVPD Id used for the initial long preview (available with Adobe Temp Pass).

short

MVPD Id used for the short preview (available with Adobe Temp Pass).

checkPeriod

Period between the two authorization checks to determine the expiration of a preview.

Entering these parameters will initiate the internal preview flow whose state diagram is shown below. The state transitions are notified with PREVIEW_STATUS and PREVIEW_EXPIRED events provided in the events section.

Accessing Player Instances

anvp.p1.onReady = function(playerInstance) {
// ACCESS API FUNCTIONS ON THE PLAYER INSTANCE HERE
// ACCESS API EVENTS ON THE PLAYER INSTANCE HERE
// playerInstance AND anvp.p1 CAN BE USED INTERCHANGABLY
}

Each player instance can be accessed using the onReady callback function. This callback will be called once the instance is ready to accept API calls and fire API events.

API methods from which we are planning to retrieve a return value must be called using a callback function as the first argument. The referenced arguments of the API method must be given in an array if there are more than one arguments. One argument can be entered without array brackets.

Preparing the view

The view is a partial HTML that is injected to the player SDK during runtime. The view shall include one parent element <anvato-controller>. The view content must be written inside this custom element as shown in the sample.

Implementing the controller

In order to implement the controller, we will be implementing the interfaces provided by the player SDK. These interfaces are available from internal anvp namespace which becomes available during the run time. This namespace shall not be confused with the public anvp namespace which was used for entering the player config and accessing API methods in the earlier versions of the player.

AnvatoCustomUIInterface

This interface provides access to:

the custom UI container using container property

mediator instance using mediator property

static data using staticData needed for environment specific values and preset values such as caption properties

The implementation of this interface must provide readyCallback and finally UI sub-components must be registered using their respective variables:

control,

splash,

captionSetting,

preview,

share,

recommendation

In case you are not planning to provide all of these compoents, you are supposed to either provide an empty implementation for the provided sub-component interfaces or simply set related sub-component's showUIComponents value to true as shown above.

Subcomponent Interfaces

ControlInterface

SplashInterface

CaptionSettingInterface

PreviewInterface

ShareInterface

RecommendationInterface

These interfaces only include a not implemented warning mimicking pure virtual functions. The player SDK calls a comprehensive list of API methods implemented on these sub-component interfaces. However, not all of them are needed for customizing the player SDK. So you shall implement these methods based on your usecase. 'not implemented' warning can be supressed by setting the var notImplamentedWarning_ to false. A comprehensive list of these methods are provided in the sub-components reference.

These methods are the handles the player SDK uses to ask for an action, set some value or get information about the component. This covers the communication from the player SDK to the UI components.

When it comes to the communication from UI component to the player SDK, mediator instance provided by AnvatoCustomUIInterface is used. Mediator instance provides publish method for sending the topics with related payload. Comprehensive list of mediator topics is given in mediator topics.

As you can see in the sample code for the implementation of AnvatoCustomUIInterface, control, splash and recommendation variables are populated with the implementation of anvp.ControlInterface, anvp.SplashInterface and anvp.RecommendationInterface.

A sample implementation for these sub-components is given in the sample code pane.

playRequest

The flag indicating if the play request is initial play request to include load first

recommendationSelected

recommendationSelected topic

Arguments:

Name

Type

Description

video

object

An object containing metadata for the selected recommendation video. Must include either a video url and format ('m3u8', 'mp4', etc.) or an id for the current MCP. Should also include a title, description, poster image URL, and video duration in seconds

isManual

boolean

indicates if recommendation item is selected manually or as a result of count down/auto advance

recommendationsReady

recommendationsReady topic

seekRequest

seekRequest topic

Arguments:

Name

Type

Description

timeIndex

number

New time index for seeking

origin

string

The component the topic is published from

splashModeUpdated

splashModeUpdated topic

Arguments:

Name

Type

Description

mode

string

Splash mode

toggleCaptionSet

toggleCaptionSet topic

toggleSharePanel

toggleSharePanel topic

volumeUpdate

volumeUpdate topic

Arguments:

Name

Type

Description

volume

number

Audio level

Sub-components reference

This section includes the API nethods the UI sub-compoenents interfaces provide:

control.updateDuration(index)

control.updateLanguage()

Update all of the user-facing text for this module to use the
current language

control.setDuration(duration)

Sets the duration of the content

Param

Type

Description

duration

Number

Total duration

control.setVisibilityMode(mode)

Changes the visibility behavior of the control bar. There are three
modes in which the control bar can be: 'visible', 'hidden',
'responsive'. In visible mode, the control bar is always visible.
In hidden mode, the control bar is never visible. In responsive
mode, the control bar is temporarily visible in response to the
mouse moving over the video.

Param

Type

Description

mode

String

The visibility mode to use ('visible', 'hidden', or 'responsive')

control.showTemporarily()

If visibilityMode is set to 'responsive', then this makes the
control bar temporarily visible

control.hide()

Hides the control bar

control.setPaused(flag)

Sets the play/pause button to show the play or pause icon according
to the given flag

Param

Type

Description

flag

Boolean

If true, then the play/pause button will be set to show the play icon

control.setFullscreen(flag)

Sets the fullscreen button to show the enlarge or shrink icon
according to the given flag

Param

Type

Description

flag

Boolean

If true, then the fullscreen button will be set to show the shrink icon

control.setFullscreenButton(state)

Shows or hides the fullscreen button. Fullscreen must also be supported by the
user's device in order to be shown

Param

Type

Description

flag

Boolean

If true, then show the fullscreen button

control.toggleCaptionSettingbutton(flag)

Shows the caption 'Settings' option when the flag is true, hides the option when
the flag is false

Param

Type

Description

flag

Boolean

If true, then the captions 'Settings' option will be shown. If false, then the option will be hidden

control.setAvailableCaptionLanguages(languages, currentLanguage)

Updates the list of available caption languages that the user can
choose from, and disables the entry for the language that is
currently in use

Param

Type

Description

languages

Array.<String>

The languages that captions are available for

currentLanguage

String | null

The caption language that is currently being used or null if captions are off

control.setAvailableBitrates(bitrates, currentBitrate)

Sets the array of available bitrates in the stream

Param

Type

Description

bitrates

Array.<Number>

Available bitrates

currentBitrate

Number

Currently streaming/loaded bitrate

bitratesToLabel

Object

Mapping from bitrates to custom labels

control.setPlaylistReady(flag)

Indicates the playlist is ready or not to hide/display a playlist button

Param

Type

Description

flag

Boolean

Flag for playlist readiness

control.showRecallLabel(timeIndex)

Used for displaying the current time before a preview enabled seek is initiated

Param

Type

Description

timeIndex

Number

Current time index before seek

control.hideRecallLabel()

Used for hiding the current time after a preview enabled seek is initiated

control.setLive(flag)

Sets the live flag so that the control bar can adapt its view to live or vod mode

Param

Type

Description

flag

Boolean

Live flag

control.setLiveCatch()

Indicates live is caught and view can be updated for live sync

control.setAdMode(flag, counterAvailable)

Sets ad mode (ad or content) so that the control bar can update its view
accordingly

Param

Type

Description

flag

Boolean

Ad flag

counterAvailable

Boolean

Flag for indicating another UI element will be displaying a countdown

control.setVolume(volume)

Sets the audio volume

Param

Type

Description

volume

Number

The volume level to use from 0.0 to 1.0

control.toggleVolume()

Toggles the volume on and off. When toggled back on, the volume returns to the
value it was at before being toggled off

control.setDownload(url)

Indicates that the video is downloadable and a button needs to be displayed

Recommendation

Recommendation API Methods

recommendation.init()

Initializes the recommendation instance

recommendation.setRecommendations(vList, countDownTime)

Sets the list of recommended videos to be displayed

Param

Type

Description

vList

Object

A list of video objects. Each object must include either a video url and format ('m3u8', 'mp4', etc.) or an id for the current MCP. Should also include a title, description, poster image URL, and video duration in seconds

countDownTime

Number

The time in seconds to countdown before autoplaying the first recommendation

Returns: Boolean - True if there are recommendations to display, false otherwise

recommendation.show(title)

Displays the recommendations

Param

Type

Description

title

String

The title to display above the grid of recommendations

recommendation.hide()

Hides the recommendations

recommendation.rescale(width)

Resizes the recommendation UI components

Param

Type

Description

width

Number

Width of the player in pixels

Plugins

Plugins are activated only if their configurations are entered correctly.

While most parameters in plugins are static that can be entered by the developer integrating the player SDK into their page, some others may require dynamic information that changes with each content. To support this use case the following macros are available when used under keyValues entry for ad plugins and under comscore for Comscore Analytics plugin. These macros must be wrapped with double square brackets and passed as string.

YOUR_KEY_1: "[[VIDEO_ID]]"

Available macros:

MCP_ID,

VIDEO_ID,

OWNER_ID,

CATEGORIES,

TITLE,

DESCRIPTION,

DURATION,

PROGRAM_NAME,

IS_OFFSITE

DFP Parameters (Client-side)

Like all other plugins, client-side DFP configuration can be entered on either application side or remote configuration. Additionally, the player SDK allows the following options:

If true, the entire ad will be clickable on mobile instead of just the "Learn More" button (Optional, default false)

iosCustomPlayback

If true, then custom playback will be used for DFP ads on Safari for iOS 10+. This means prerolls can be viewed in fullscreen mode with the caveat that users cannot clickthrough to visit advertisers' sites in fullscreen mode. Skippable ads are also not supported using custom playback (Optional, default false)

disableCustomClickTracking

If true, then the player will not use its own "Learn More" button for client-side DFP ads on mobile web. Instead, the IMA SDK will handle the click tracking and clickthroughs (Optional, default false)

enablePreloading

If true, then the IMA SDK will attempt to preload the video ad assets in advance. See the IMA SDK documentation for limitations (Optional, default false)

FreeWheel prefers providing different renditions with specific configurations. In accordance with that, flash configuration must be written under flash namespace while html5 configuration is written under html5 namespace as shown below and in the sample code. Similar to the DFP client-side plugin, the onBeforeVideoLoad hook can be used to modify the existing ad configuration before each video.

Plugin Name

Namespace

Parameters

Definition

freewheel

clientSide

networkId

Network ID provided by FreeWheel

serverURL

FreeWheel ad server URL provided by FreeWheel

profileId

Profile ID provided by FreeWheel

videoAssetId

Video Asset ID provided by FreeWheel

keyValues

Key-value pairs sent to the FreeWheel (Optional)

siteSectionId

Site Section ID provided by FreeWheel

source

Url location of the Freewheel library (AdManager.js). The source cannot be overriden using the onBeforeVideoLoad hook. (Optional)

Object/String specifying the details of the Google Analytics event. When the value is a string type, the string will be used as the value of eventAction in the Google Analytics request along with default values "Videos" in eventCategory and Title of the current video in the eventLabel. Users can overwrite those values by providing an object to specify the event alias, category and label as well as adding metric to the request. When this field is not specified, all SDK events will be sent.

dimensions

Optional

Object specifying the list of custom dimensions. If this parameter is set, Web Player SDK will attach the custom dimensions with their values to each event request sends to Google Analytics.

This parameter is used for specifying the servers processing the custom metadata (Typically Adobe Visitor and AppMeasurement servers). Multiple tracking servers seperated by comma can be entered.

trackingServer

Tracking server for Heartbeat provided by Adobe.

jobId

Job ID provided by Adobe.

account

account ID provided by Adobe.

publisherId

publisher ID provided by Adobe.

version

must be set to "1.5" to use the current latest stable Adobe Heartbeat Library or a later version for an early adoption (availability is subject to the coordination with Anvato).

chapterTracking

Used for toggling chapter tracking. When chapterTracking is not set to false (default is true), the chapter boundaries are VIDEO_STARTED and AD_STARTED/VIDEO_COMPLETED events for VOD, and PROGRAM_CHANGED event for Live. Also for live stream, the chapter tracking causes name and friendlyName to be based on static metadata since the schedule based dynamic metadata is passed to the each chapterInfo.

Heartbeat integrations relying on page level metadata not available to the SDK can use the config parameter customMetadata to provide metadata mapping as shown in the sample code. The plugin macros listed at the beginning of this section can be used to populate the custom metadata values.

Alternatively, the Heartbeat plugin configuration may use derived metadata to populate the custom metadata values. In this case, provide the useDerivedMetadata flag and the mapping section. The mapping section includes mandatory Heartbeat fields on the top level, and custom metadata within the context object. The enabled flag is used to enable derived metadata within the mapping section. Whenever a value in the mapping section matches a key in the derived metadata, the value is replaced with the corresponding derived metadata value. In the second example to the right, the custom yourLabel field will be sent with the value 'YOUR_VALUE' since 'yourKey' is a key in the derived metadata. The custom 'anotherLabel' field will be sent with the value 'ANOTHER_VALUE' since 'ANOTHER_VALUE' is not a key in the derived metadata.

Object specifying the location of the button displaying the opt-out notification and the period of making this button visible again after toggling on the notification (default is Infinity, and setting -1 will make it always show up)

Offsite Plugin Configurations

A plugin configuration provided to the offsitePlugins parameter will override the plugins configuration if the player is one of the following:

An iframe embed instance from a share link.

An iframe embed on an AMP page.

In combination with the IS_OFFSITE macro, the offsitePlugins configuration enables you to change or toggle on/off plugin configurations depending on where the player is embedded.

Derived Metadata

Certain plugins that require video metadata may also take advantage of derived metadata. Derived metadata consists of key-value pairs that are derived from custom metadata in MCP based on rules in the access key configurations.

Derived metadata may also be set at the application level as an embed parameter, in the play() API call, or in each item of a dynamic playlist. Since there are multiple possible sources of derived metadata, the following list of sources are ordered from highest to lowest priority:

Dynamic playlist items and the play() API call.

Embed parameter.

MCP-configured custom metadata.

Access key remote configuration.

Reference Guide

API Functions

getTitle()

anvp.p0.getTitle(YOUR_CALLBACK_FUNCTION);

Provides the title of current item

Returns

Type

Video title

String

getDescription()

anvp.p0.getDescription(YOUR_CALLBACK_FUNCTION);

Provides the description of current item

Returns

Type

Video description

String

getDuration()

anvp.p0.getDuration(YOUR_CALLBACK_FUNCTION);

Provides the duration of current item

Returns

Type

Video duration

Number

getState()

anvp.p0.getState(YOUR_CALLBACK_FUNCTION);

Returns the player state

Returns

Type

Player state

(States provided in state diagram)

getEmbedCode()

anvp.p0.getEmbedCode(YOUR_CALLBACK_FUNCTION);

Provides the embed code (described in iframed embed option) for the current video item

Returns

Type

Embed code

String

getShareLink()

anvp.p0.getShareLink(YOUR_CALLBACK_FUNCTION);

Provides the share link for the current video item

Returns

Type

Share link

String

getBitrates()

anvp.p0.getBitrates(YOUR_CALLBACK_FUNCTION);

Provides available bitrates in kbps

Returns

Type

Array of available bitrates in kbps

Array

getCaptionLanguages()

anvp.p0.getCaptionLanguages(YOUR_CALLBACK_FUNCTION);

Provides available caption languages

Returns

Type

Array of available languages

Array

getCurrentTime()

anvp.p0.getCurrentTime(YOUR_CALLBACK_FUNCTION);

Provides the current time/playhead time

Returns

Type

Current time in milliseconds

Number

getPlayerLanguages()

anvp.p0.getPlayerLanguages(YOUR_CALLBACK_FUNCTION);

Provides available player languages (for labels and notifications)

Returns

Type

Array of available languages

Array

getVolume()

anvp.p0.getVolume(YOUR_CALLBACK_FUNCTION);

Provides the player volume level

Returns

Type

Volume level between 0 and 1

Number

isFullscreen()

anvp.p0.isFullscreen(YOUR_CALLBACK_FUNCTION);

Gives player fullscreen mode

Returns

Type

True indicates fullscreen

Boolean

getPreviewState()

anvp.p0.getPreviewState(YOUR_CALLBACK_FUNCTION);

Provides preview state (available when Temp Pass is activated)

Returns

Type

Preview state either PASSIVE, LONG, SHORT or ENTITLEMENT

String

getViewStatus()

anvp.p0.getViewStatus(YOUR_CALLBACK_FUNCTION);

Used for getting the player’s viewability in the active window/tab (available for private beta clients)

play()

anvp.p0.play();

Plays the video content. Note that some browsers block programmatic play attempts for videos until the user manually initiates playback. As a result, this API method should not be used to autoplay videos. Instead pass in the autoplayembed parameter with the value true when initializing the player.

play(mediaInfo)

anvp.p0.play({id: VIDEO_ID});

Plays another video content associated with the accessKey. This API method is the recommended way for playing another video as opposed to reloading the player SDK.

A list of objects describing the metadata for each video recommendation. Each object must contain either a video id for the current MCP or a video url and format ('m3u8', 'mp4', etc.). The objects should also contain a title, description, poster image URL, and video duration in seconds. Optionally, the objects may contain a live property stating whether the video is a live stream or not

event Idupid (another identifier used as a key for metadata lookup)metadata object with properties:titledescriptionratingmvpdAuthenticationNeededtveCheckNeeded

NEXT_PROGRAM

Next program information has arrived

event Idupid (another identifier used as a key for metadata lookup)metadata object with properties:titledescriptionratingmvpdAuthenticationNeededtveCheckNeeded

METADATA_LOADED

Program metadata has changed

event Idupid (another identifier used as a key for metadata lookup)metadata object with properties:titledescriptionratingownerIdtagscategories

AUTHENTICATION_STATUS

Authentication status has changed

isAuthenticatedauthenticator

AUTHORIZATION_STATUS

Authorization status has changed

isAuthorizedauthorizertokenerror code (if failed)

HOMEZIP_DETECTED

User’s home zip detected

home zip

ENCRYPTED_HOMEZIP_DETECTED

User’s home zip detected

encrypted home zip

MAX_RATING_DETECTED

User’s allowed max rating detected

max rating

PROVIDER_LIST_SET

Provider list is available

Provider look-up table

PROVIDER_SELECTED

User selected a provider/previously selected provider has been set

provider ID

PICKER_REQUESTED

MVPD picker has been requested. (This event can be used as an opportunity to display custom MVPD picker dialogs if the default picker is disabled.)

None

PICKER_DISPLAYED

MVPD picker has been displayed

None

POPUP_BLOCKED

Browser has blocked the popup

None

POPUP_DISPLAYED

Browser has allowed the popup

None

GEOLOCATION_STATUS

User’s geolocation information updated

longitudelatitudeerror code (if failed)

AD_IMMINENT

There will be an ad break in given seconds

startsIn (seconds)

SEGMENT_TYPE_CHANGED

Stream segment type has changed (applies to the ad stitched streams)

Segment type (“master”, “ad” or “slate”)

PROVIDER_IFRAME_INJECTED

Provider IFrame has been injected

Provider IdIFramed Login Placeholder Id

PROVIDER_IFRAME_REMOVED

Provider IFrame has been removed

IFramed Login Placeholder Id

VIEW_STATUS

The player is viewable in active window/tab (available for private beta clients)

isViewable (Boolean)

LOADER_READY

Loader is ready

None

SUBSCRIBER_AUTHORIZATION_STATUS

Subscriber authorization status has changed

authZ status

PLAYLIST_CHUNK_AVAILABLE

Playlist chunk is available

Array of playlist items

TIME_DELTA

Time difference between client and server detected

Difference between server time and browser time

CHROMECAST_STATUS

Chromecast status has changed

chromecast status

VERIFICATION_STATUS

Chromecast verification status has changed

verification satatus

CLIENT_BANDWIDTH

Client bandwidth estimated

Bandwidth in kbps

PLAYER_ERROR

Player has thrown an error

Error information (Explained in Error Messages section)

USER_PLAY

User has started the playback

None

USER_RESUME

User has resumed the content

None

USER_GOLIVE

User has selected golive

None

USER_PAUSE

User has paused the playback

None

USER_MUTE

User has muted the audio

None

USER_UNMUTE

User has unmuted the audio

None

USER_SHARE

User has shared a content

None

USER_FORWARD_SEEK

User has seeked forwards

Current time target time

USER_BACKWARD_SEEK

User has seeked backwards

Current time target time

USER_FULLSCREEN

User has toggled on Fullscreen mode

None

USER_CANCEL_FULLSCREEN

User has toggled off Fullscreen mode

None

BUFFER_LIMIT_UPDATED

Buffer limit has been updated

Buffer limit

PRESENTATION_UPDATED

Current time, total time or content type has changed. For ads, time index and duration correspond to the ad break with the exception of client-side DFP ads where time index and duration correspond to the current ad.

time index duration presentation content type adIndex total ads in the ad break

BUFFER_START

Buffering has started

None

BUFFER_END

Buffering has completed

None

ID3

ID3 tag detected

Timed metadata payload publisher

POSTER_LOADED

Poster image has been loaded

None

COMPONENTS_INITIALIZED

Player UI components have been initialized

None

BITRATE_CHANGED

Bitrate value has been updated

Current bitrate

BITRATE_CHANGE_IN_PROGRESS

There is a pending birate change

Target bitrate

TIME_DELTA

Time difference between client and server detected

time delta (msec)

MEDIA_URLS_SET

Published media URLs are available

Media URL objects array

BEFORE_VIDEO_LOAD

Player has notified the check point before video load

Video information object Embed configuration

PLAYLIST_ITEM_CHANGED

Playlist item index has been updated

playlist item index media Id

CAPTION_DETECTED

The player has detected closed captions

Array of available languages

AUTOPLAY_STATUS

The player's autoplay capability for the current video based on the browser's autoplay policy. The status value is NONE if there is no intent of autoplay, BLOCKED if the browser completely blocks autoplay, MUTED if muted autoplay is allowed, or UNMUTED if unmuted autoplay is allowed.

autoplay status

Playback Origins

Enum for playback origins exposed with PLAYING_START event

Properties

Name

Type

Default

INITIAL

number

0

PLAYLIST_MANUAL

number

1

PLAYLIST_AUTO_ADVANCE

number

2

RECOMMENDATION_MANUAL

number

3

RECOMMENDATION_AUTO_ADVANCE

number

4

PLAY_API_METHOD

number

5

Ad Detail

AdDetail : object

AdDetail : object

.tracking : Object

.clickThrough : Array.<String>

.clickTracking : Array.<String>

AdDetail.tracking : Object

AdDetail.tracking : Object

.clickThrough : Array.<String>

.clickTracking : Array.<String>

tracking.clickThrough : Array.<String> | null

Click through URI for application layer rendering their own UI to display a page when user clicks on ad video

tracking.clickTracking : Array.<String> | null

Click tracking URIs for application layer rendering their own UI to track when the user clicks on the ad video

API Hooks

onBeforeVideoLoad

SDK calls this hook before loading the media and ads. Application layer can modify the initConfig inside this hook and return modified initConfig (typically client-side ad settings are modified).

onBeforeVideoLoad

anvp.p0.onBeforeVideoLoad = function(mediaInfo, initConfig) {
// mediaInfo.id can be used for identifying the asset
// config can be modified based on mediaInfo.id
return initConfig; // finally modified config is returned
};

Parameters:

Name

Type

Description

mediaInfo

Object

Media info object in which media is identified with id entry. For external URLs id is populated with the md5 of the media url

initConfig

Object

Init configuration that is generated by merging application side and remote configuration. Plugins entry is often the point of interest for this hook

Error Messages

The player errors are thrown using the events channel using the event format.

Error Format

Error payload is passed with the args property as shown below. isCritical flag is used for providing the SDK user with the information about whether the playback will stop/not start at all or the error is recoverable.

Error List

Error Code

Error definition

isCritical

ACTRL001

Failed to retrieve the metadata

false

ACTRL002

Failed to retrieve the video metadata

false

ACTRL010

Failed to retrieve the TVE rights

false

ACTRL020

The user’s maximum allowed rating is smaller than program’s rating

true

ACTRL021

Provided rating string does not have the standard format

false

ACTRL030

Adobe Pass authentication failed

true

ACTRL031

Adobe Pass authorization failed

true

ACTRL040

The user’s geo-station doesn’t match the streaming station

true

ACTRL041

The user doesn’t have home station rights.

true

ACTRL042

The user doesn’t have geo station rights.

true

ACTRL043

The user doesn't have TVE rights.

true

ACTRL050

Adobe Pass failed to respond within the specified time out limit.

true

ACTRL051

Adobe Pass failed to check authentication within the specified time out limit.

true

ACTRL052

Adobe Pass failed to check authorization within the specified time out limit.

This option is the suggested and easiest option for placing the companions on your page. The programmer is only supposed to register the companion placeholders with their ids and dimensions. The player will populate the companions in an appropriate placeholder.

When the player detects a server side-stitched or client-side companion ad, it fires the event COMPANION_AVAILABLE. This event contains all data needed for processing the companion payload and finally placing in the placeholder:

payload type: This value is either static, html or iframe.

creative type: This only applies to the static payload. Possible values are image/jpeg, application/x-shockwave-flash, etc. When this value is populated the payload will have an url as data for the creative. Additionally, the clickTarget and creativeView urls in the payload must be used appropriately by the programmer to make the companion fully functional.

width: companion width

height: companion height

payload: This attribute is populated with an object with the following attributes:

data: URI encoded payload to be injected into the appropriate placeholder or a url to a static/iframe typed resource.

clickTarget: Only applies to static payloads with an image resource.

creativeView: This is only available when the companion requires view tracking; mostly used with static payload and image creative types.

In this option placeholders should not be registered using the companions embed parameter.

Anvato Video Player Plugin for WordPress

Introduction

Anvato WordPress plugin enables Anvato Media Content Platform (MCP) customers to embed a video player into their posts with a single click.

Installation

To get the Anvato WordPress plugin working with your WordPress account, please follow the steps below:

Note: You can test this url by opening the URL on your browser. Given that the iFrame is hosted in a secure URL, make sure that your CDN supports secure connections (https cert) to avoid mixed content or certification errors.

4. Use the following template to create the Facebook Instant Article embedded video using the prepared URL from the previous step:

5. The tag is now ready to be embedded in a Facebook Instant Article. For more information regarding third party embeds please refer to FBIA documentation.

Facebook Instant Articles (WordPress)

Facebook Instant Articles are also supported through the Anvato Video Player Plugin for WordPress. To get the Anvato WordPress plugin working with your WordPress account, please follow the steps on Anvato Video Player Plugin for WordPress

In some cases, you may want to pause video content when the user switches tabs or pause audio content on mobile when returning to the home screen. This can be accomplished using the Page Visibility API.

See the sample code for a basic implementation of pausing when the tab is inactive and playing when the user returns to the tab. Note that this example applies to both desktop and mobile. You may need to detect the user's device or browser first in order to apply this behavior for particular user environments.

Release Notes

Anvato Universal Web Player SDK Version 3 includes major changes to support HLS playback on desktop and mobile browsers which implement MSE (Media Source Extensions) specification. Adobe Flash Player Plugin is no more needed on these browsers for video playback. Please refer to the SDK Version 3 Introduction section for details.

Version 3.1.6 (01/24/2018)

Enabled dynamic autoplay capability detection to handle new autoplay policies enforced by browsers such as Chrome 64+, Safari 11+. This detection provides three suggestions and the player SDK takes the actions in the order listed below:

Unmuted playback is allowed: Player SDK proceeds with unmuted autoplay

Muted playback is allowed: Player SDK proceeds with muted autoplay and stays muted until the user unmutes the video.

None of them is allowed: Player SDK waits for the user's tap/click on play button to start playback.

Exposed a callback onBeforeVideoLoad and event beforeVideoLoad which provides a way for those callbacks/listeners to return a modified config blocking the video load. Using these changes one can change the dfp config before each load.

Added support for getting video projection mode from MCP

Fairplay drm is now available for native hls playback on MacOS Safari browser. This blocks MSE capability in the presence of drm config while loadinf HLS on MacOS Safari

Enhancements in 360 feature

Send comscore pause during ad

Elapsed time is now available for analytics plugins

Waived the need for passing a profile for heartbeat plugin when a config is provided via page level config or remote config

Additional play tracking for nielsen per up-to-date documentation

Added xUrl support to cast sender

Version 3.0.7

Enhancements in Nielsen plugin

Provided a timeout between dfp plugin loaded and started event with
default 5 seconds and configurable with startTimeout embed parameter under
dfp->clientSide

Stitched Ad UI support to detect and display ad breaks for HTML5 player

The following events are introduced/standardized across mobile/desktop browsers:

AD_BREAKS, “Ad breaks detected in the content”

AD_BREAK_STARTED, “Ad break has started”

AD_STARTED, “Ad has started”

AD_COMPLETED, “Ad has completed”

AD_BREAK_COMPLETED, “Ad break has completed”

BUFFER_LIMIT_UPDATED, “Buffer limit has been updated”. This event is enabled with revealBufferBufferInfo embed parameter. Enabled with revealAdBreaks embed parameter for ad stitched playback on HTML5 player

PRESENTATION_UPDATED, “Current time, total time or content type has changed”

Subscription based entitlement flow is enabled with the Login interface in the player; the event SUBSCRIBER_AUTHORIZATION_STATUS is introduced to get the status updates.

Any ad duration mismatch affecting the quartile tracking for DAI (Digital Ad Insertion) is now handled by the player.

Version 2.138.0

The scrollbar bug appearing on IE9 is fixed.

Mobile/Tablet playlist now has fallback image in case of a missing thumbnail or image load error.

Playlist button is displayed only if there are more than 1 videos and embed parameter playlistMode not set to “external”.

Desktop player playlist selection issue is fixed.

Version 2.137.4

Debug value for the duration between Long Preview and Short Preview has been replaced with the production value (24 hours).

Version 2.137.3

Control bar now has configurable remaining color (on Tablet).

Display and hide API methods for main components are provided (on Tablet/Mobile).

Auto-switch to next item while playing a playlist is now the default behavior.

Event updates on iOS 8.x affecting seek and pause upon a tap on a preroll are addressed.

Bug related to 1 item playlist is fixed.

Maximum item amount in playlist is increased to 30.

injectStyle api method added for testing a custom stylesheet.

Version 2.137.2

The entries about the live event restriction, mvpdAuthenticationNeeded and tveCheckNeeded, are added to the metadata provided by PROGRAM_CHANGED event.

USER_INTERACTION event is enabled for goLive API method.

The bug related to the messaging encountered while embedding multiple players is fixed.

Version 2.137.1

Encrypted zips provided by MVPDs (with the encrypted flag set to true on setMetadataStatus) are handled as hzip in post data and fired with HOME_ZIP_DETECTED event.

zipDecryption embed parameter is introduced to maintain decryption request sent by player (needed for entitlement flows at which decryption is handled by player side request); default is false.

POPUP_BLOCKED and POPUP_DISPLAYED events are activated for provider login window handled by Flash based Adobe Pass (needed for only Safari Browsers due to its user interaction context detection for Flash). JavaScript based Adobe already has these events enabled.

Version 2.137.0

Fail over logic is implemented for supported live streams. The event FAILOVER_STATION_LOADED is fired with the first argument as the failover channel upon a successful switch to failover channel.

Social and e-mail share link is detected using the followings in order:

User override with shareLink embed parameter,

Facebook open graph tags,

SEO canonical URL,

Parent page URL.

Share at is enabled to cover emailed share links. This feature works by using anvt URL parameter and startAt embed parameter.

E-mail share is now using HTML based template.

“Skip Ad” button’s location is now configurable using the embed parameter skip. A sample configuration is similar to that of rating and logo widgets: {location:”TR”,margin:”10px”}.

Version 2.136.18

baseURL is deprecated; providing a valid source URL is sufficient for switching the environments. The usage of ‘//’ in script source for adapting to the protocol http or https is still supported.

The event PROGRAM_CHANGED is now more accurate using additional parameters.

The event COMPANION_INJECTED is introduced to notify the SDK user about the companion. For server-side stitched ads this event is fired always after AD_STARTED event.

Resource for events with no rating is passed to the Comcast SSO as a blank string as opposed to “TV-Y”.

The event SEGMENT_TYPE_CHANGED is introduced for distinguishing the type of the segment (master, ad, slate) for server-side ad stitched streams.

Error LOAD010 is now thrown by the player to indicate that browser is blocking the third party cookies.

The event AUTHORIZATION_STATUS contains an additional parameter, the detailed error provided by the provider.

Player now performs a timeout check against Adobe Pass service failure / intential blocking. Time-out period is by default 60 seconds. This value can be overridden by setting the timeOut parameter with a value not less than 60 under accessControl namespace.

Error ACTRL050 is introduced to indicate that Adobe Pass failed to respond within the specified time out limit.

Error ACTRL052 is introduced to indicate that Adobe Pass failed to check authorization within the specified time out limit.

Version 2.136.8

Error ACTRL031 now includes the provider specific authorization failure message.

The bug related to the pInstance encountered while loading the player script along with others dynamically is fixed.

MRSS sent as resource to Comcast is modified to activate parental control.

Player normalizes various formats of rating such as “TVPG”, “TV-PG” or “PG” including lowercases.

debug embed parameter is now bound to the debug mode of Flash based Adobe Pass.

Meaures taken to decrease the latency while using Flash based Adobe Pass.

New environments are deployed: Development, Staging and Production. Activating these environments are possible with the following settings:

Version 2.136.3

Embed parameter passive is introduced for toggling on/off PASSIVE state for preview. This parameter must be used under preview namespace.

Embed parameter refreshless is introduced for choosing between opening a new login tab/window and doing a full page redirection. This parameter must be used under accessControl namespace.

The latency issue encountered in Chrome/Webkit based browsers caused by Flash based Adobe Pass is resolved.

The player now throws the error ACTRL041 for the users with no service zip while switching to the ENTITLEMENT state.

Version 2.136.0

Server-side ad stitching log corresponding to the session specified with sessionId is accessible with Ctrl + Shift + F9 (Additionally Fn may be needed for keyboards defaulting to the multimedia options).

Error codes ACTRL041 and ACTRL042 are available for detailing the authorization failure due to the user’s TVE rights.

Flash based Adobe Pass support is now available in addition to the JavaScript based Adobe Pass support (default). Switching to the Flash based Adobe Pass is possible with useFlash embed parameter under accessControl namespace.

Version 2.135.23

API method getPreviewState() is introduced to retrieve the preview state (while the Temp Pass is activated)

Player’s merged configuration generated using all other configs mentioned in IFRAMED JS embed option is exposed with anvp.{PLAYER_INSTANCE}.mergedConfig

Option to inject the IFRAMED Provider Login to a custom HTML element is introduced. This option is activated by assigning the HTML element id to the iFramedLoginPlaceholderId property under accessControl object. The events PROVIDER_IFRAME_INJECTED and PROVIDER_IFRAME_REMOVED are also provided to notify the SDK user about the opportunity to display/hide the placeholder.