Table of content

Web SDK Reference

Introduction

Our Web SDK allows you to easily embed videos on your website.

In this article, you’ll find the exhaustive SDK Reference to help you tailor your unique video experience on web and explore the available runtime Player parameters, methods, events and states.

Getting started

If you’re new to our Web SDK, we recommend checking our Getting started guide to help you get familiar with the fundamentals and introduce you to the different embed methods available for web.

Runtime Player parameters

While the main Player experience is controlled using the settings defined in your Player configuration, additional runtime customization is achievable using client-side parameters.

Check the dedicated guide to see how to add runtime Player parameters with each embed method of the Web SDK.

Parameter	Default	Description	Type
`video`	undefined	The ID of the video to load	String
`playlist`	undefined	The ID of the playlist to load	String
`customConfig`	undefined	Define advertising configuration by passing in keys and values. More details E.g. `customConfig[key]=values`	Object
`scaleMode`	`fit`	To adjust the player’s video focus Possible values: `fit`, `fill`, `fillLeft`, `fillRight`, `fillTop` & `fillBottom`	Enum
`mute`	`false`	Whether to mute the video or not. To note, enabling mute may impact monetization. The Player provides smart mute behavior, it tries to automatically start the video playback with sound. If this isn’t possible due to browser prevention, there is a fallback mechanism and the Player reattempts to play the video but with the sound set to mute. Possible values: `true` or `false`	Boolean
`startTime`	`0`	Specify the time (in seconds) from which the video should start playing	Number
`loop`	`false`	To set the video to loop. More details Possible values: `true` or `false`	Boolean

Methods

The Player is loaded asynchronously using a Promise, which on resolve returns a player object. In order to get access to a Player, you can retrieve a Player using one of the below methods.

API commands can be called to programmatically create and control the Player.

Check the dedicated guide to see how to use methods.

Global methods

Method	Info
`dailymotion.createPlayer('source_id', {video:String, playlist:String, player:String, params:Object, referrerPolicy:String})`	On resolve the `Promise` will return a created player at the position of the `source_id` on the page. A `video`, `playlist` or `player` can by specified using their corresponding parameter and unique id. If you already have multiple player configurations embedded in your page, you must specify the `player` configuration to use, otherwise the default one will apply, see multiple player configurations. For additional customization you can add runtime `params` to the player, see runtime Player parameters
`dailymotion.getPlayer()`	On resolve the `Promise` will return a player, if there is a single player instance, otherwise it will be rejected if there are multiple player embeds
`dailymotion.getPlayer('source_id')`	On resolve the `Promise` will return the specified player, pass the container ID of the specific player as an argument into the `getPlayer()` method
`dailymotion.getAllPlayers()`	Returns an array of `Promises`. Each `Promise` returns one of the player of the page
`dailymotion.pipClose()`	To deactivate PiP, the method applies to the whole webpage Learn more
`dailymotion.pipResume()`	To resume PiP, the method applies to the whole webpage Learn more
`dailymotion.pipCollapse()`	To collapse the mobile sticky PiP, the method applies to the whole webpage Learn more
`dailymotion.pipExpand()`	To expand the mobile sticky PiP, the method applies to the whole webpage Learn more
`dailymotion.pipRepaint()`	To repaint PiP seamlessly when dynamic elements are changing the layout of a page Learn more
`onScriptLoaded()`	A callback function to reflect the loading of the Player Library Script which is triggered when the global variable is correctly initialized in the window object

Player methods

Once you’ve access to a Player on the page, you can then control that Player programmatically.

Method	Info	Types
`loadContent()`	To load a video or a playlist. You can play a specific video followed by a playlist by specifying both the video and playlist IDs Note that the loaded content playback is based on the `autostart` configuration defined in the PlayerID settings E.g. `({video:String, playlist:String, startTime:Number})`	Object
`play()`	To start or resume video playback	–
`pause()`	To pause video playback	–
`setVolume()`	To set the player’s volume to the specified level Possible values: Between `0` & `1`	Float
`setSubtitles()`	To activate a subtitles track to a specified language if available	String
`setQuality()`	To set the video’s quality to the specified quality Possible values: [`240`, `380`, `480`, `720`, `1080`, `1440`, `2160` `default`]	String
`seek()`	To seek to the specified time in video playback in seconds	Number
`setFullscreen()`	To enable or disable fullscreen mode Possible values: `true` or `false`	Boolean
`setPlaybackSpeed()`	To modify the playback speed, if the value passed does not match one from the list, the playback speed is rounded to the superior one. The playback speed is kept across videos. Possible values: `[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]`	Float
`setMute()`	To set the mute mode of the player Possible values: `true` or `false`	Boolean
`setCustomConfig()`	To set the config for ads, dynamically update the advertising parameter value, use the method to send a new value which then gets updated when the player loads the next video file	Object
`setScaleMode()`	To adjust the player view of the video screen Possible values: `fit` `fill` `fillLeft` `fillRight` `fillTop` & `fillBottom`	Enum
`setCustomRecommendations()`	To set custom recommendations in the Player, giving a list of video xIDs Example: `['xid1', 'xid2', 'xid3']` Note: `enable_custom_recommendations` has to be set to `true` to be able to use the method `setCustomRecommendations()`	Array
`updateParams()`	To change the following player config values at runtime: `aspectRatio`, `customConfig`, `loop`, `mute`, `scaleMode` & `volume`	Object
`getRootNode()`	Retrieve the node where the Player iFrame is contained E.g. `<div id="player1" class="dailymotion-player-root"></div>`	HTML Node
`destroy()`	To destroy a Player instance pass in specified Player ID	–
`on()`	To set up a `listener` function returning the player state that will be called whenever the specified `event` is dispatched by a player instance. An optional object can be passed as a 3rd parameter. The only available option is currently `once`, and expects a `Boolean` value indicating that the listener should be invoked at most once after being added. If `true`, the listener would be automatically removed when invoked E.g. `(event:String, listener:Function, [{once:Boolean}])`	–
`off()`	To remove a previously registered event `listener` from a player instance. If the `listener` is not specified, it will remove any existing listeners associated with the event E.g. `(event:String, [listener:Function])`	–
`getState()`	To retrieve the current state of the Player. See how to here	–
`getSettings()`	To retrieve the configuration of a Player as defined in your Dailymotion Studio. See available Player settings here	–

Events

The Player emits events related to the change of the Player state, video playback and ad content.

Check the dedicated guide to learn how to listen to events.

Player Events

Player Event	Info
`PLAYER_ASPECTRATIOCHANGE`	Sent when the aspect ratio of the player changes after calling `setAspectRatio('4:3')`)
`PLAYER_CRITICALPATHREADY`	Sent every time a video is ready to play, or started playing (depending on autoplay settings, and their resolution by the browser), or is unable to play (blocked, restricted, unavailable). Listen to this event if you want to defer doing network-heavy and JavaScript-heavy work, to allow the optimal delivery of the first frames of the video to the use
`PLAYER_END`	Sent when the playback of the content video, and eventual post-roll ad video is completed
`PLAYER_ERROR`	Sent when the player triggers an error. Error code available in the Player State object
`PLAYER_HEAVYADSINTERVENTION`	Sent when the player is unloaded from the page due to Chrome browser’s heavy ads intervention policies
`PLAYER_PIPEXPANDEDCHANGE`	Sent when the Picture-in-Picture expanded mode changes, only on small viewports
`PLAYER_PLAYBACKPERMISSION`	Sent each time any playback request has failed or if the initial playback attempt has succeeded
`PLAYER_PRESENTATIONMODECHANGE`	Sent when the player transitions to or from a Picture-in-Picture state, either native or the dailymotion version, or when the player enters or exits the fullscreen state
`PLAYER_RECODISPLAY`	Sent each time a recommended video thumbnail (from either automatic recommendation, custom recommendation or contextual recommendation) is displayed for the first time in the Player carousels
`PLAYER_SCALEMODECHANGE`	Sent when the scale mode of the player changes after using `setScaleMode()`
`PLAYER_START`	Sent the first time the player attempts to start the playback, either because of user interaction, an autoplay parameter or an API call (e.g `play()`, `loadContent()`, etc.)
`PLAYER_VIDEOCHANGE`	Sent when a new video has been loaded in the player. (e.g. after calling `loadContent({ video: 'xID' })`, or at player start-up)
`PLAYER_VIEWABILITYCHANGE`	Sent when the player viewability values changes (50% of the player is within the user’s viewport)
`PLAYER_VOLUMECHANGE`	Sent when the volume level or mute state changes

Video Events

Video Event	Info
`VIDEO_BUFFERING`	Sent when the player has to temporarily stop video playback for further buffering of content
`VIDEO_DURATIONCHANGE`	Sent when the duration property of the video becomes available or changes after a new video load
`VIDEO_END`	Sent when the player completes playback of the content video
`VIDEO_PAUSE`	Sent when the video playback has paused
`VIDEO_PLAY`	Sent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute
`PLAYER_PLAYBACKSPEEDCHANGE`	Sent when the playback speed changes
`VIDEO_PLAYING`	Sent when the content video starts playing, after the play or waiting event
`VIDEO_PROGRESS`	Sent when the browser is fetching the media data
`VIDEO_QUALITIESREADY`	Sent when video qualities are available
`VIDEO_QUALITYCHANGE`	Sent when the video quality changes
`VIDEO_SEEKEND`	Sent when the player has completed a seeking operation
`VIDEO_SEEKSTART`	Sent when the player starts to seek to another position in the video timeline
`VIDEO_SUBTITLESCHANGE`	Sent when the current subtitle changes
`VIDEO_SUBTITLESREADY`	Sent when subtitles are available
`VIDEO_START`	Sent when the player begins playback of the content video
`VIDEO_TIMECHANGE`	Sent when the playback position changes

Ad Events

Ad Event	Info
`AD_COMPANIONSREADY`	Sent when a companion ad is received. Companion ads should be played in sync with the main ad (linear/non-linear) by listening to events `AD_START` and `AD_END`
`AD_DURATIONCHANGE`	Sent when the duration property of the video advertisement becomes available or changes after a new video load
`AD_END`	Sent when the player completes playback of an ad
`AD_IMPRESSION`	Sent when the first ad frame is displayed
`AD_LOADED`	Sent when the player has loaded and buffered the creative’s media and assets either fully or to the extent that it is ready to play the media
`AD_PAUSE`	Sent when the player pauses an ad
`AD_PLAY`	Sent when the ad playback starts or continues after being in a paused state
`AD_READYTOFETCH`	Sent 6 seconds before an ad request is made. To customize this delay (between 1 and 10 seconds), please use `wait_for_custom_config_delay`. Important: Only sent when Player setting `enable_wait_for_custom_config` is `true`
`AD_START`	Sent when the player begins playback of an ad video
`AD_TIMECHANGE`	Sent when the playback position of an ad changes
`AD_CLICK`	Sent when a user clicks on a video ad

State

To access data state of the Player, video or advertising, use the getState() method: on resolve, it will return an object representation of the player state.

Name	Type	Info
`adAdvertiserName`	`String`	The advertiser name or `null`
`adCompanion`	`Array`	An array of parsed companion ad creatives
`adCreativeAdId`	`String`	The universal ad id node from the VAST or the ad id of the creative node from the VAST
`adCreativeId`	`String`	The id of the creative node from the VAST
`adDescription`	`String`	The description of the ad or `null`
`adDuration`	`Number`	The duration time of the ad resource in seconds
`adEndedReason`	`String`	The reason why the last ad ended Possible values: `error`, `stopped`, `skipped`, `interrupted` or `null`
`adError`	`Object`	Contains information about the last ad error that occurred in the Player, including `message` and `code`
`adId`	`String`	The id of the ad
`adIsPlaying`	`Boolean`	If an ad resource is running Possible values: `true` or `false`
`adIsSkippable`	`Boolean`	If the ad can be skipped by the user at this moment Possible values: `true` or `false`
`adPosition`	`String`	The position of the ad in the video, or `null` if no ad is running Possible values: `preroll`, `midroll`, `postroll` or `null`
`adSkipOffset`	`Number`	The remaining time before the ad can be skipped or -1 if no ad is running
`adTime`	`Number`	The current playback position of an ad in seconds
`adTitle`	`String`	The title of the ad or `null`
`playerAspectRatio`	`String`	The player current aspect ratio Possible values: `inherit`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`
`playerError`	`Object`	Contains information about the last error that occurred in the player, including `title`, `message` and `code`
`playerInstanceId`	`String`	Contains a unique identifier generated for each player instance. Format: uuid V4 A player instance is generated each time a player is created, with either `dailymotion.createPlayer` or the Player Embed Script. Player instance ≠ player configuration, i.e when loading on the same page 3 players using the same player configuration, 3 unique player instances will be generated
`playerIsAlertDialogDisplayed`	`Boolean`	If the player has the alert dialog displayed Possible values: `true` or `false`
`playerIsBuffering`	`Boolean`	If the player is loading the media resource Possible values: `true` or `false`
`playerIsCriticalPathReady`	`Boolean`	If the player is ready to play Possible values: `true` or `false`
`playerIsMuted`	`Boolean`	If the player is muted Possible values: `true` or `false`
`playerIsNavigationEnabled`	`Boolean`	If the next and previous controls in the PiP are enabled Possible values: `true` or `false`
`playerIsPipNativeSupported`	`Boolean`	If the player does support the native PiP Possible values: `true` or `false`
`playerIsPlaybackAllowed`	`Boolean`	If the player is allowed to play, depending on the browser permissions Possible values: `true` or `false`
`playerIsPlaying`	`Boolean`	If the player is currently playing video or ad content Possible values: `true` or `false`
`playerIsStartScreen`	`Boolean`	If the player is in start screen Possible values: `true` or `false`
`playerIsReplayScreen`	`Boolean`	If the player is in replay screen Possible values: `true` or `false`
`playerIsViewable`	`Boolean`	If the player is within the viewability threshold Possible values: `true` or `false`
`playerNextVideo`	`String`	The ID of the next video in the queue
`playerPipDisplay`	`String`	The current display mode of PiP, whether it is displayed on a larger/smaller screen Possible values: `largeViewport` or `smallViewport`
`playerPipStatus`	`String`	The current PiP feature status Possible values: `enabled` ,`disabled` or `closed`
`playerPipIsExpanded`	`Boolean`	If the mobile sticky PiP is expanded Possible values: `true` or `false`
`playerPlaybackPermissionReason`	`String`	The reason why the playback has been allowed or not Possible values: `allowedFallbackMuted`, `allowed`, `rejectedInactiveTab` or `rejectedByBrowser`
`playerPresentationMode`	`String`	The current mode where the player is displayed Possible values: `inline`, `nativePip`, `pip` or `fullscreen`
`playerPrevVideo`	`String`	The id of the previously played video
`playerScaleMode`	`String`	The player’s current scale mode Possible values: `fit`, `fill`, `fillLeft`, `fillRight`, `fillTop` or `fillBottom`
`playerVolume`	`Number`	The current volume level. The volume and mute params operate separately, therefore, you could have a player with full volume, but also muted Possible values: Between `0.0` to `1.0`
`playerPlaybackSpeed`	`Number`	The player current playback speed Possible values: `[0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]`
`recommendedVideoDisplayed`	`Object`	Information about the recommended videos currently displayed Example:`[{index: 0, xid: 'xid1'}, {index: 1, xid: 'xid2'}]`
`videoCreatedTime`	`Number`	The timestamp that corresponds to the creation of the video
`videoDuration`	`Number`	The duration time of the video resource in seconds
`videoId`	`String`	The unique Id of the video
`videoIsCreatedForKids`	`Boolean`	If the video is created for Children Possible values: `true` or `false`
`videoIsPasswordRequired`	`Boolean`	If the video required a password to be read Possible values: `true` or `false`
`videoLoadedFrom`	`String`	The origin of a video load. Possible values: `playback_button`, `replay_button`, `reload_button`, `previous_button`, `next_button`, `auto_skip`, `auto_next`, `carousel_card`, `password`, `api`, `programmatic`
`videoOwnerAvatars`	`Object`	Contains the avatar of the video owner, including the height of the image in pixels and its URL
`videoOwnerId`	`String`	The id of the owner of the video
`videoOwnerScreenname`	`String`	The screen name of the owner of the video
`videoOwnerUsername`	`String`	The user name of the owner of the video
`videoPosters`	`Object`	Contains the thumbnail of the video, including the height of the image in pixels and its URL
`videoQualitiesList`	`Array`	The video qualities that are available
`videoQuality`	`String`	The quality value of the video loaded
`videoSubtitles`	`String`	The language code of the subtitle track that is currently enabled
`videoSubtitlesList`	`Array`	The language codes of the subtitle tracks which are available for the current media resource
`videoTime`	`Number`	The current playback position of the video in seconds
`videoTitle`	`String`	The title of the video loaded
`videoViewId`	`String`	Contains a unique identifier generated each time a video is loaded in the player Format: 19 random characters based on timestamp

Example Player state


						


						


			{
  "adAdvertiserName": "Dailymotion advertiser",
  "adCompanion": null,
  "adCreativeAdId": null,
  "adCreativeId": "video",
  "adDescription": "Dailymotion ad",
  "adDuration": 15.07,
  "adEndedReason": null,
  "adError": null,
  "adId": "32251",
  "adIsPlaying": true,
  "adIsSkippable": true,
  "adPosition": "midroll",
  "adSkipOffset": 0,
  "adTime": 6.42,
  "adTitle": "Dailymotion_ad",
  "playerAspectRatio": "16:9",
  "playerError": null,
  "playerInstanceId": "e10b4d45-438f-065a-31f8-d1d6482cb34a",
  "playerIsAlertDialogDisplayed": false,
  "playerIsBuffering": false,
  "playerIsCriticalPathReady": true,
  "playerIsMuted": null,
  "playerIsNavigationEnabled": true,
  "playerIsPipNativeSupported": true,
  "playerIsPlaybackAllowed": true,
  "playerIsPlaying": true,
  "playerIsReplayScreen": false,
  "playerIsStartScreen": false,
  "playerIsViewable": true,
  "playerNextVideo": "x81ixxp",
  "playerPipDisplay": "largeViewport",
  "playerPipIsExpanded": false,
  "playerPipStatus": "enabled",
  "playerPlaybackPermissionReason": "allowed",
  "playerPresentationMode": "inline",
  "playerPrevVideo": null,
  "playerScaleMode": "fit",
  "playerVolume": 1,
  "recommendedVideosDisplayed": [{index: 0, xid: 'x8mubmn'}, {index: 1, xid: 'x84qh4y'}],
  "videoCreatedTime": 1551103337,
  "videoDuration": 214.06,
  "videoId": "x730nnd",
  "videoIsCreatedForKids": false,
  "videoIsPasswordRequired": false,
  "videoLoadedFrom": "carousel_card",
  "videoOwnerAvatars": {"60": "https://s1.dmcdn.net/u/4gS6x1bAn1J4XkTtz/60x60"},
  "videoOwnerId": "x23rwb7",
  "videoOwnerScreenname": "Player team",
  "videoOwnerUsername": "player-team",
  "videoPosters" : {
    "60": "https://s2.dmcdn.net/v/DZRrE1a-UY_P8Q4HG/x60",
    "120": "https://s2.dmcdn.net/v/DZRrE1a-UY_Llrtde/x120",
    "180": "https://s1.dmcdn.net/v/DZRrE1a-UY_YZWP_m/x180",
    "240": "https://s1.dmcdn.net/v/DZRrE1a-UY_lKqwAs/x240",
    "360": "https://s2.dmcdn.net/v/DZRrE1a-UY_vfzXEe/x360",
    "480": "https://s1.dmcdn.net/v/DZRrE1a-UY_MePtiX/x480",
    "720": "https://s2.dmcdn.net/v/DZRrE1a-UY_19B5cB/x720",
    "1080": "https://s1.dmcdn.net/v/DZRrE1a-UY_vvxuk3/x1080"
    },
  "videoQualitiesList": ["1080", "720", "480", "380", "240", "144"],
  "videoQuality": "Auto",
  "videoSubtitles": "en",
  "videoSubtitlesList": ["fr", "en"],
  "videoTime": 60.12,
  "videoTitle": "Dailymotion video",
  "videoViewId": "1h2fo92qc4qahuhdekq",
}

Changelog

2024-07-30

Introduction of new Player method, event and states linked to the different content recommendation features:

New Player method setCustomRecommendations() used to set up the “custom recommendation” feature enable_custom_recommendations
New Player event PLAYER_RECODISPLAY
New Player states recommendedVideosDisplayed and videoLoadedFrom

2024-02-13

In response to a recent browser update, it is now required to explicitly allow third-party iFrames embedded on a webpage to trigger the share action.

To comply with this requirement, add the value web-share in your iFrame’s allow attribute, as shown here.

Important: Existing iFrame integrations need to be updated

2023-07-17

New Player setting and ad event available to optimize the header bidding info passed via the setCustomConfig() method

New enable_wait_for_custom_config Player setting
New AD_READYTOFETCH ad event

2023-07-05

Deprecation: CPE Player integration method
After 2 years of progressive deprecation, our old CPE integration method has been turned off.
This deprecation doesn’t have any impact if you’re using our current integration methods for web and native apps.

2023-06-27

oEmbed new endpoint

The iFrame code delivered within the ‘HTML’ field of the oEmbed response has been updated to utilize the Geo player endpoint
autoplay param is now deprecated in our oEmbed Spec and is no longer available

2023-01 -23

The working with advertising section has been moved to a dedicated page with additional details, examples and code samples.

2022-12-05

After a few months of transition, the Legacy JavaScript Player API References linked to our JavaScript SDK have been removed from our official documentation.
Please use our latest integration methods for all your Player embeds, and refer to the dedicated API Reference for the Player object. Don’t hesitate to reach out to your Content Manager or our Support team if you need assistance.

2022-11-23

VIDEO_DURATIONCHANGE event within the Web SDK has been updated, it will only be sent during video content duration change and no longer for ad duration change. See full list of player events.

2022-11-03

New dailymotion.pipRepaint() method available to maintain PiP positioning on a page with dynamic elements (collapsing menu bar, shifting size header, …)

2022-10-27

Deprecation of setControls() method and the related PLAYER_CONTROLSCHANGE event and playerAreControlsEnabled state.
You can now decide to enable/disable your playback and ad controls independently with the two new toggles in your Player configurator: Player controls and Ads controls.

2022-10-13

PiP customization CSS codes have been updated with units allowing it to be dynamic.

2022-07-01

The playback speed is now set on a player level and this feature is now exposed on our API via a dedicated player method, player event, and player state.
You can now use the method getRootNode() to retrieve the node where the Player iFrame is wrapped in.

2022-05-22

The PiP customization has been updated to limit their impact on the CLS score. New CSS attributes have been introduced to control your PiP positioning.

2022-05-10

onScriptLoaded() now available to determine the loading of the player library.

2022-04–13

loadContent() Player method behavior has been fixed to match with the autostart settings defined on the Player settings.

2022-01-26

New property videoIsCreatedForKids added to the Player state.

2022-12-17

JavaScript Player API – Expose a new Player event PLAYER_HEAVYADSINTERVENTION

2021-12-02

New Player Embed global release