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.

ParameterDefaultDescriptionType
videoundefinedThe ID of the video to loadString
playlistundefinedThe ID of the playlist to loadString
customConfigundefinedDefine advertising configuration by passing in keys and values.
More details

E.g. customConfig[key]=values
Object
scaleModefitTo adjust the player’s video focus

Possible values: fit, fill, fillLeft, fillRight, fillTop & fillBottom
Enum
mutefalseWhether 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
startTime0Specify the time (in seconds) from which the video should start playingNumber
loopfalseTo 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

MethodInfo
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 videoplaylist 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.

MethodInfoTypes
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 availableString
setQuality()To set the video’s quality to the specified quality

Possible values: [240380480720108014402160 default]
String
seek()To seek to the specified time in video playback in secondsNumber
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 fileObject
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.

Dailymotion Events
Note:

The above image highlights the event sequence triggered by a Player visible after scrolling with the ‘autoStart’ value set to ‘firstTimeViewable’ and using a pre-roll advertisement. The event sequence may change depending on the configuration and integration of the Player.

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

Player Events

Player EventInfo
PLAYER_ASPECTRATIOCHANGESent when the aspect ratio of the player changes after calling setAspectRatio('4:3'))
PLAYER_CRITICALPATHREADYSent 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_ENDSent when the playback of the content video, and eventual post-roll ad video is completed
PLAYER_ERRORSent when the player triggers an error. Error code available in the Player State object
PLAYER_HEAVYADSINTERVENTIONSent when the player is unloaded from the page due to Chrome browser’s heavy ads intervention policies
PLAYER_PIPEXPANDEDCHANGESent when the Picture-in-Picture expanded mode changes, only on small viewports
PLAYER_PLAYBACKPERMISSIONSent each time any playback request has failed or if the initial playback attempt has succeeded
PLAYER_PRESENTATIONMODECHANGESent 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_RECODISPLAYSent 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_SCALEMODECHANGESent when the scale mode of the player changes after using setScaleMode()
PLAYER_STARTSent 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_VIDEOCHANGESent when a new video has been loaded in the player. (e.g. after calling loadContent({ video: 'xID' }), or at player start-up)
PLAYER_VIEWABILITYCHANGESent when the player viewability values changes (50% of the player is within the user’s viewport)
PLAYER_VOLUMECHANGESent when the volume level or mute state changes

Video Events

Video EventInfo
VIDEO_BUFFERINGSent when the player has to temporarily stop video playback for further buffering of content
VIDEO_DURATIONCHANGESent when the duration property of the video becomes available or changes after a new video load
VIDEO_ENDSent when the player completes playback of the content video
VIDEO_PAUSESent when the video playback has paused
VIDEO_PLAYSent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute
PLAYER_PLAYBACKSPEEDCHANGESent when the playback speed changes
VIDEO_PLAYINGSent when the content video starts playing, after the play or waiting event
VIDEO_PROGRESSSent when the browser is fetching the media data
VIDEO_QUALITIESREADYSent when video qualities are available
VIDEO_QUALITYCHANGESent when the video quality changes
VIDEO_SEEKENDSent when the player has completed a seeking operation
VIDEO_SEEKSTARTSent when the player starts to seek to another position in the video timeline
VIDEO_SUBTITLESCHANGESent when the current subtitle changes
VIDEO_SUBTITLESREADYSent when subtitles are available
VIDEO_STARTSent when the player begins playback of the content video
VIDEO_TIMECHANGESent when the playback position changes

Ad Events

Ad EventInfo
AD_COMPANIONSREADYSent 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_DURATIONCHANGESent when the duration property of the video advertisement becomes available or changes after a new video load
AD_ENDSent when the player completes playback of an ad
AD_IMPRESSIONSent when the first ad frame is displayed
AD_LOADEDSent 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_PAUSESent when the player pauses an ad
AD_PLAYSent when the ad playback starts or continues after being in a paused state
AD_READYTOFETCHSent 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_STARTSent when the player begins playback of an ad video
AD_TIMECHANGESent when the playback position of an ad changes
AD_CLICKSent 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.

NameTypeInfo
adAdvertiserNameStringThe advertiser name or null
adCompanionArrayAn array of parsed companion ad creatives
adCreativeAdIdStringThe universal ad id node from the VAST or the ad id of the creative node from the VAST
adCreativeIdStringThe id of the creative node from the VAST
adDescriptionStringThe description of the ad or null
adDurationNumberThe duration time of the ad resource in seconds
adEndedReasonStringThe reason why the last ad ended

Possible values: errorstoppedskipped, interrupted or null
adErrorObjectContains information about the last ad error that occurred in the Player, including message and code
adIdStringThe id of the ad
adIsPlayingBooleanIf an ad resource is running

Possible values: true or false
adIsSkippableBooleanIf the ad can be skipped by the user at this moment

Possible values: true or false
adPositionStringThe position of the ad in the video, or null if no ad is running

Possible values: prerollmidrollpostroll or null
adSkipOffsetNumberThe remaining time before the ad can be skipped or -1 if no ad is running
adTimeNumberThe current playback position of an ad in seconds
adTitleStringThe title of the ad or null
playerAspectRatioStringThe player current aspect ratio

Possible values: inherit16:94:31:13:49:16
playerErrorObjectContains information about the last error that occurred in the player, including titlemessage and code
playerInstanceIdStringContains 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
playerIsAlertDialogDisplayedBooleanIf the player has the alert dialog displayed

Possible values: true or false
playerIsBufferingBooleanIf the player is loading the media resource

Possible values: true or false
playerIsCriticalPathReadyBooleanIf the player is ready to play

Possible values: true or false
playerIsMutedBooleanIf the player is muted

Possible values: true or false
playerIsNavigationEnabledBooleanIf the next and previous controls in the PiP are enabled

Possible values: true or false
playerIsPipNativeSupportedBooleanIf the player does support the native PiP

Possible values: true or false
playerIsPlaybackAllowedBooleanIf the player is allowed to play, depending on the browser permissions

Possible values: true or false
playerIsPlayingBooleanIf the player is currently playing video or ad content

Possible values: true or false
playerIsStartScreenBooleanIf the player is in start screen

Possible values: true or false
playerIsReplayScreenBooleanIf the player is in replay screen

Possible values: true or false
playerIsViewableBooleanIf the player is within the viewability threshold

Possible values: true or false
playerNextVideoStringThe ID of the next video in the queue
playerPipDisplayStringThe current display mode of PiP, whether it is displayed on a larger/smaller screen

Possible values: largeViewport or smallViewport
playerPipStatusStringThe current PiP feature status

Possible values: enabled ,disabled or closed
playerPipIsExpandedBooleanIf the mobile sticky PiP is expanded

Possible values: true or false
playerPlaybackPermissionReasonStringThe reason why the playback has been allowed or not

Possible values: allowedFallbackMutedallowedrejectedInactiveTab or rejectedByBrowser
playerPresentationModeStringThe current mode where the player is displayed

Possible values: inlinenativePippip or fullscreen
playerPrevVideoStringThe id of the previously played video
playerScaleModeStringThe player’s current scale mode

Possible values: fitfillfillLeftfillRightfillTop or fillBottom
playerVolumeNumberThe 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
playerPlaybackSpeedNumberThe player current playback speed

Possible values: [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2]
recommendedVideoDisplayedObjectInformation about the recommended videos currently displayed

Example:[{index: 0, xid: 'xid1'}, {index: 1, xid: 'xid2'}]
videoCreatedTimeNumberThe timestamp that corresponds to the creation of the video
videoDurationNumberThe duration time of the video resource in seconds
videoIdStringThe unique Id of the video
videoIsCreatedForKidsBooleanIf the video is created for Children

Possible values: true or false
videoIsPasswordRequiredBooleanIf the video required a password to be read

Possible values: true or false
videoLoadedFromStringThe 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
videoOwnerAvatarsObjectContains the avatar of the video owner, including the height of the image in pixels and its URL
videoOwnerIdStringThe id of the owner of the video
videoOwnerScreennameStringThe screen name of the owner of the video
videoOwnerUsernameStringThe user name of the owner of the video
videoPostersObjectContains the thumbnail of the video, including the height of the image in pixels and its URL
videoQualitiesListArrayThe video qualities that are available
videoQualityStringThe quality value of the video loaded
videoSubtitlesStringThe language code of the subtitle track that is currently enabled
videoSubtitlesListArrayThe language codes of the subtitle tracks which are available for the current media resource
videoTimeNumberThe current playback position of the video in seconds
videoTitleStringThe title of the video loaded
videoViewIdStringContains 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:


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


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

2022-12-05

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

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

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

2022-0413
  • 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