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 settingsE.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 invokedE.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 eventE.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 runningPossible 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” featureenable_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
- 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 relatedPLAYER_CONTROLSCHANGE
event andplayerAreControlsEnabled
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 theautostart
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