To enjoy all our Developer Portal features, please switch to Microsoft Edge, Google Chrome or Mozilla Firefox browsers.

Video player documentation

Player


Overview

The Dailymotion Player is a state-of-the-art video player built with the latest web technologies (HTML5/ JavaScript) and video standards (HLS adaptive streaming).

It's easy to use, cross-platform friendly and enjoyed by millions of users every day, both on Dailymotion's properties and hundreds of premium Partners' websites and native applications.

The Player is fully customizable, consistent across all devices, delivered with picture-in-picture, extensive analytics and all the necessary advertising technologies out of the box.

To help testing we have opened a CodePen developer account to provide access to some code samples that will help you to discover the Dailymotion Player and its features. Check it out here.


Integration methods

Depending on your needs you can integrate the player using one of the methods outlined below. We recommend where possible to embed using one of the dedicated libraries in order to take full advantage of our player technology.

IntegrationInfoAccess to Player API
Player embed scriptEmbed using JavaScript, the player will load at the point where you add the script.Yes
Player library scriptAdd just the player library to create players programmaticallyYes
Player iframeThe iframe embed method is the most basic way to integrate the player. Advanced functionality such as 'PiP' and' firstTimeView' are not availableNo
Android SDKThe SDK is a thin wrapper around a WebView that allows to easily embed Dailymotion videos into your Android applicationYes
iOS SDKA swift wrapper around the WKWebView Class that allows developers to easily embed the Dailymotion Player in their appYes
AMPDailymotion AMP component is available to embed the player with the AMP frameworkNo

Embed the player on web

Embedding the player on your properties is simple. We've different methods available depending on your technical preference and environments. We recommend using one of the script embeds as it provides access to all player functionality and the Player API.

Embed typeInfo
Player embed scriptThe player will load at the point where you add the script. This also provides access to the Player API.
Player library scriptAdd just the library and create the player programmatically using the Player API
Player iframeEmbed the player without JavaScript to use a basic player configuration

Getting started

As a first step, you need to create a custom player configuration associated with your Dailymotion account and defined by a unique “player_configuration_ID”. This identifier is required to ensure accurate monetization, targeting and attribution.

Step 1) Create a custom player configuration

A custom player configuration can be created and managed either through the “Players” tab in the Partner Space or programmatically via the player REST API.

A player configuration is composed by several player settings. These settings can’t be modified or overridden at run time. They can only be updated via the player configurator in the Partner Space or the player REST API. For more information, please refer to the section “Working with player settings” in this documentation.

Step 2) Add the Player or Player library

Once a player configuration is correctly created, you can access to the corresponding scripts that can be embedded onto your properties. Embed scripts can be accessed either from the “Players” tab within the Partner Space or programmatically via the player REST API.

Embed typeInfo
Player embed scriptThe player will load at the point where you add the script. This also provides access to the Player API
Player library scriptAdd just the library and create the player programmatically using the Player API
Player iframeEmbed the player without JavaScript to use a basic player configuration

Player Embed Script

The Player Embed Script integration method is the easiest way to embed the player on your site while providing access to all features and the Player API. It is a single-line script the loads the player along with the player library. The player will be loaded exactly where the script is added into the <body> of the page.

Embed a video

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-video="x84sh87"></script>

Use the data-video attribute to specify which video ID to load. It should be added directly on the script tag that loads the pre-configured player. To ease integration it's already added to the embed script that can be copied via the Partner HQ and requires only a video Id to be specified.

Embed a playlist

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-playlist="x5zhzj"></script>

Use the data-playlist attribute to specify which playlist ID to load. It should be added directly on the script tag that loads the pre-configured player.

Please note, if you need to play a specific video on top of a playlist you can specify both the video and playlist IDs as in the embed script.

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-playlist="x79dlo" data-video="x7tgad0"></script>

Embed multiple players

In order to benefit from different player configurations on a single page it's possible to add multiple embed scripts with different Player IDs.

<!-- Player 1 -->
<script src="https://geo.dailymotion.com/player/{Player ID}.js"   data-video="x84sh87"></script>
<!-- Player 2 -->
<script src="https://geo.dailymotion.com/player/{Player ID}.js"   data-video="x84sh87"></script>

Please note, when using multiple player configurations its recommended to only embed one player configuration with PiP active, only one PiP will be launched per page. In the case of instant PiP the first player which will load on the page will launch in instant PiP.


Player Library Script

The Player library script integration method is available for developers who want to load just the library, the player needs to be then loaded programmatically via the Player API. The library URL can be either copied from the Partner HQ in the player's tab or retrieved from the REST API (see lib_script_url field).

Any player created with the Player API will carry over the configuration corresponding to the embedded Player library script. Additional player configurations can be specified in the createPlayer() method using the player parameter.

It takes only 3 steps to load our player using the JavaScript library.

Step 1) Add the library to your HTML page

Add the library script within the <head> section of the page. This provides access to the Player API and allows you to create a Player instance programmatically.

<head>
  <script src="https://geo.dailymotion.com/libs/player/{Player ID}"></script>
</head>

Step 2) Add the placeholder for the load players

Add a div placeholder(s) on the page where you want the player(s) to be loaded and assign an id to the container.

<div id="my-dailymotion-player">My Player placeholder</div>

Step 3) Create the Player using the Player API

Use the createPlayer() method and pass in the container id to initialize the player and specify the video or playlist to be loaded. You can also specify a player configuration to use with the player attribute in order to load a different player configuration, by default the configuration of the embedded library will be applied. It is recommended when adding only one single player on a page, allow for the player configuration to be specified in the lib_script_url rather than the createPlayer() method.

<head>
  <script src="https://geo.dailymotion.com/libs/player/{Player ID}"></script>
</head>

<div id="my-dailymotion-player">My Player placeholder</div>

<script>
  dailymotion
    .createPlayer("my-dailymotion-player", {
      video: "x84sh87",
  })
  .then((player) => console.log(player))
  .catch((e) => console.error(e));
</script>

Embed a video

After loading the Player Library script use the createPlayer() method and pass in the container id to initialize the player and specify the video to be loaded. The Player configuration of the embedded library will apply.

The video must be specified using the video attribute.

Embed a playlist

Use the createPlayer() method and pass in the container id to initialize the player as well as and the playlist Id to be loaded. The Player configuration of the embedded library will apply.

The playlist must be specified using the playlist attribute. If you need to play a specific video on top of a playlist you can specify both the video and playlist Ids.

Embed multiple players

Any player created with the Player API will carry over the configuration corresponding to the embedded Player library script.

If it is required to load multiple players with different configurations on a single page, other player IDs can be specified in the createPlayer() method using the 'player' parameter. Therefore any number of player configurations can be embedded with a single-player library URL.

It is recommended when adding only one single player on a page, allow for the player configuration to be specified in the lib_script_url rather than the createPlayer() method. Please see the example of specifying different configs in the createPlayer() method using the player param.

Please note, if the Player ID is incorrectly specified or does no longer exist, the configuration will fall back to the default library config. If multiple player scripts are loaded on a page but no player in the createPlayer() is specified an error will be logged and the created player will take a default config. It's not required to embed different lib_script_url for each player config, only a single library script is required and the other Player configs will be loaded on the fly.

When using multiple player configurations its recommended to only embed one player configuration with PiP active, only one PiP will be launched per page. In the case of instant PiP the first player which will load on the page will launch in instant PiP.


Player iFrame

Embed a partially configured player without JavaScript. Smart player functionality such as "Picture-in-Picture", "first time viewable" and "auto-sizing" along with access to the player API won't be available. The iFrame player will benefit only from any UI customizations specified in the player configurator UI or Rest API. We recommend partners to take full advantage of our player technology and use the player embed script.

<iframe frameborder="0" width="640" height="360" 
    src="https://geo.dailymotion.com/player/{Player ID}.html?video=x84sh87" 
    allowfullscreen 
    allow="autoplay; fullscreen; picture-in-picture">
</iframe>

The iFrame embed type will be appropriate for environments such as Facebook instant articles or other articles which limit the use of JavaScript and customization. We encourage all publishers if possible to embed the player via one of our provided scripts. Player parameters can be added for additional optimization, see available parameters from the list here.


Embed the player in native apps

We provide our publishers with the same tools we use to create our flagship Dailymotion applications: the same Player and the same SDKs. Check out our apps in the Apple App Store or Google Play Store which have over 50M+ downloads.

Our Mobile SDK provides access to the Player API and gives you full control of the player. Along with having a genuine native feel, it's possible to use our provided tools, to build a unique video solution in your app, benefiting from your own custom UI components and aligning it with the look and feel of your brand.

As our SDKs are open source, partners can make a pull request to update the iOS or Android SDK. Please check the source code, documentation and sample app on GitHub.

Please note, we recommend loading our player with our native SDKs in mobile applications. It can be loaded directly if required, please contact us so we can highlight what additional steps should be taken to make sure there is no impact on analytics or advertising.

IntegrationInfoAccess to Player API
Android SDKThe SDK is a thin wrapper around a WebView that allows you to easily embed Dailymotion videos into your Android applicationYes
iOS SDKA Swift wrapper around the WKWebView class that allows developers to easily embed the Dailymotion Player in their appYes

Android SDK

The SDK is a thin wrapper around a WebView that allows to easily embed Dailymotion videos into your Android application. We recommend using the SDK rather than the video URL in a standard webView, as it gives you more controls of the player and its better for tracking purposes. Our Android SDK is open source and you can get all the required information plus a sample app on our GitHub. The SDK supports Android 5.0.x (API level 21+) and It is fully in Kotlin, If your project is still in JAVA, please add the kotlin dependencies: https://developer.android.com/kotlin/add-kotlin.

How to use

  1. The easiest way to integrate the SDK is by adding it to your application build.gradle file. Please note the SDK requires the minSdkVersion of the app to be 21+.

    implementation 'com.dailymotion.dailymotion-sdk-android:sdk:0.2.10'
    
  2. The PlayerWebView is the main SDK component that allows you to load videos easily into your android environment. Add the component to the selected layout which will display the player. To load the video without autoplay, you can use the setPlayWhenReady(false) method.

    <com.dailymotion.android.player.sdk.PlayerWebView
    android:id="@+id/dm_player_web_view"
    android:layout_width="match_parent"
    android:layout_height="215dp">
    </com.dailymotion.android.player.sdk.PlayerWebView>
    
  3. Initialize the player in your selected activity, reference the PlayerWebView and use one of the load methods available. You can use the load() method, which will initialize a default player config, load the player and start playing the selected video. Or it is also possible to use the initialize() method to load the player with a custom config using any available player params.

    lateinit var playerWebView: PlayerWebView
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.screen_sample);
        playerWebView = findViewById(R.id.playerWebview)
        val params = mapOf("video" to "x84sh87")
        playerWebView.load(loadParams = params);
    }
    

Using player parameters

In order to customize the player, pass in player parameters to your player instance. Create a Map interface, add an entry of the chosen player parameters into the map along with its associated value, then pass the Map into the initialize() method. To load multiple videos while keeping the same player instance and config, use the load() method after player initialization.

val params = mapOf(
    "ui-highlight" to "fff",
    "logo" to "false"
)
dailymotionVideoPlayer.initialize("https://www.dailymotion.com/embed/", params = params, emptyMap())

Player Parameters for Android SDK

Use the below parameters to customize your player via the iframe or SDK embed.

ParameterInfoType
autoplayAutomatically attempt to start playback with sound, if it is blocked by the browser, the player will force the video muteBoolean
controlsWhether to display the player controls, true by defaultBoolean
idID of the player unique to the page to be passed back with all API messagesString
muteWhether to mute the videoBoolean
qualitySpecify the suggested playback quality for the videoNumber
sharing-enableWhether to display the sharing buttonBoolean
startSpecify the time (in seconds) from which the video should start playingNumber
subtitles-defaultSpecify the default selected subtitles languageString
syndicationPass your syndication key to the playerString
ui-highlightChange the default highlight color used in the controls (hex value without the leading #). Color set in the Partner HQ will override this paramString
ui-logoWhether to display the Dailymotion logoBoolean
ui-start-screen-infoWhether to show video information (title and owner) on the start screenBoolean
playlistSpecify a playlist ID to populate the Up Next Queue with videos from a playlistString
fullscreenWhether to display the fullscreen buttonBoolean
scaleModeSpecify the default focus of the player in order to reframe and refocus on a specific area in the video. To be used for scaling and repurposing of videos between different aspect ratios for example landscape to portrait. Values ( ‘fit’, ‘fill’, ‘fillLeft’, ‘fillRight’, ‘fillTop’, ’fillBottom’ )String
loopWhether to loop a video or an entire playlist. A video embed will start over again automatically. A playlist embed will start to play from the first item in the playlist after the entire playlist has finishedBoolean

Methods

Once the SDK is loaded, you can use the Player API to control the player. You have full access to all player methods and there are also methods supplied in the Android SDK that return specific player properties. When the player is ready to take API commands it will send ApiReadyEvent event.

dailyMotionVideoPlayer.pause();
NameInfo
load(String)Calls the initialize method, loads the player with a video associated with the video id (e.g. x7tgad0)
initialize(String, Map<String, String>, Map<String, String>)Loads the player with base string URL of player' https://dailymotion.com/embed/' accompanied by a MAP interface of required player parameter values
finishedInitialization (String, Map<String, String>, Map<String, String>)Loads the player with a given URL, parameters and advertising ID
play()Starts or resumes video playback
pause()Starts or resumes video playback
setFullScreenButton(Boolean)Enters fullscreen mode when true and controls player fullscreen button state. The method should be utilized in association with the native fullscreen functionality in app
setPlayerEventListener(Eventlistener)Add a listener which will be called when the Android system WebView can an error
unmute()Unmute the player
mute()Mute the player
callPlayermethod(String, Object)Call a method from the Js Player API, if not already exposed in the Android SDK
setPlayWhenReady(Boolean)Set the autoplay behavior of the player when video is loaded. Set to true, for autoplay enabled.
setQuality(String)Set player to play at a specified quality if available ['240', '380', '480', '720', '1080', '1440', '2160' 'default']
setSubtitle(String)Activate subtitles track to a specified language if available
setVolume(float)Set the player's volume to the specified level between 0 & 1. ie, 0.5 = 50%
release()Destroy the Player webView
seek(double)Seek to the specified time in video playback in seconds
setIsWebContentDebuggingEnabled()Enable the Android system WebView debug mode
setMinimizeProgress(float)Disable the player UI when set to 0, enables when 1
setWebViewErrorListener(WebViewErrorListener)Add a listener for Android system WebView error
showControls()Enable the display of the player UI
toggleControls()Turn on/off the player's UI components
togglePlay()Switch between player & pause

In order to make a developer's life easier, we created methods in our android SDK that will return the value of a specific player property. Not all player properties are returned by a set method, some are returned in the payload sent after the player event, please see here for more info about events.

NameInfo
getBufferedTime()Returns a Double Number. The part of the media resource that has been downloaded in seconds
getVideoPaused()Returns a boolean value for current pause state of the player
getVolume()Returns a float value for the volume property between 0 and 1
isEnded()Returns a boolean value for whether the media resource has ended
isSeeking()Returns a boolean value for whether the video resource is seeking
getDuration()Returns a double value for the length of a media resource in seconds
getPosition()Returns a long value of the current playback position in seconds

Player events

The player emits specific events about changes in its state. For specific player events, you can add event listeners. For certain events, it's possible to access the corresponding player property value using the payload method.

EventInfoPayload method
ApiReadyEventSent when the player is ready to accept API commands. Do not try to call functions before receiving this event
StartEventSent the first time the player attempts to start the playback
VideoChangeEventSent when a new video has been loaded in the playergetPayload() returns video id & video title
LoadedMetaDataEventSent when the video's metadata is loaded
AdStartEventSent when the player starts to play an ad media resource
AdTimeUpdateEventSent when the playback position of an ad changes
AdPlayEventSent when the player starts the playback of an ad
AdPauseEventSent when the player pauses an ad resource
AdEndEventSent when the player reaches the end of an ad media resource
VideoStartEventSent when the player starts to play the media resource
TimeUpdateEventSent when the playback position changes
SeekingEventSent when the player is starting to seek to another position in the videogetPayLoad() will return the position at which the seek method was triggered
SeekedEventSent when the player has completed a seeking operationgetPayLoad() will return the position at which the seek method seeks to
ProgressEventSent when the browser is fetching the media data
DurationChangeEventSent when the duration property of the video becomes available or changes after a new video loadgetPayload() returns the duration property of the video
PlayingEventSent when the content media resource playback has started
PauseEventSent when the content media resource playback has paused
VideoEndEventSent when the player reaches the end of the content media resource
PlaybackReadyEventSent when playback starts after the play method returns
QualitiesAvailableEventSent when qualities are availablegetPayload() returns qualities which are available
QualityChangeEventSent when the video quality changesgetPayload() returns the quality value
VolumeChangeEventSent when the volume or mute state changesgetPayload() returns volume state and muted state
FullScreenToggleRequestedEventSent when the fullscreen toggle button is requested
ControlChangeEventSent when the UI controls appear or disappeargetPayload() returns if player UI controls are visible

Below is an example of adding listeners for multiple events, it is then possible to use the event payload method to get the corresponding events property value.

dailyMotionVideoPlayer.setEventListener { event ->
    when (event) {
        is ApiReadyEvent -> ...
        is StartEvent -> ...
        is LoadedMetaDataEvent -> ...
        is ProgressEvent -> ...
        is DurationChangeEvent -> ...
        /* And many more event */
        else -> {
            /* In case a POJO is not available you can directly access the raw data */
            if (event.name == "_generic_") {
                /* Do some stuff for my event: parse the raw date to extract the event name or values */
                Log.d("Event with payload: ${event.payload}")
            }
        }
    }
}

Best practices

Player Ready Event:
When using the Player with any of our of SDKs, we recommend before you make any API commands, wait till after the API ready event is sent by the player. You can pick this up in your android app using the ApiReadyEvent.

Preload player:
It's possible to load the player and the video separately. In your application, you can preload the player before the user attempts to play a video. In order to preload the player without a video being displayed. Use the initialize() method and base the baseUrl of just the player with a video not defined, https://www.dailymotion.com/embed/.

Reuse player:
When utilizing the player via our SDKs in an application, you can reuse the same player instance. Use the load() method passing in the video id after initializing the player.

Handle full-screen orientation:
Any activity you are using your player in, you should add the below snippet in your AndroidManifest.XML . The setFullScreenButton() method which is available, doesn't have complete control of the full-screen functionality in your application. This should be used in parallel with your own native application functionality adjusting the player to take the whole screen space. This method controls the UI fullscreen component and updates the player state.

android:configChanges="orientation|screenSize"

Google player services:
The SDK uses Google Play Services to get the Advertising Id, you may want to override the play-services-ads version to avoid conflicting with other play services artifacts.

dependencies {
    implementation "com.google.android.gms:play-services-ads:[your_play_services_version]"
}

Picture In Picture:
Our flagship Dailymotion app use our Android SDK, although we can't provide out of the box PiP functionality, it is possible to achieve this like we have done, depending on your software architecture. You can review info on Google's android Picture-in-Picture support here.

TCF2

Our Android SDK complies with IAB TCF2 standards so it's easy to access the stored content string and pass it to the Player.

Using a recognized CMP, generate the consent string and store it in the correct location as specified by the TCF2 iAB specification. After generating the content string then pass it to the Player using the tcf2Handler.loadConsentString(content = this) method.

OM SDK

Open Measurement SDK from IAB is designed to facilitate third party viewability and verification measurement for ads served to web video and mobile app environments. For more details see here.

We have integrated the SDK in our Dailymotion Player SDK and it does more or less everything out of the box :

  • Ad session management
  • Ad main signals (play, buffer_start, buffer_end, pause, resume, quartiles, click)
  • Device and Player volume management
  • Basic Player state handling. NORMAL or FULLSCREEN based on player fullscreen state.

Please note that it is recommended to update at all times the player state if your app has more player layout variety, such as mini-player, picture-in-picture, etc. This can be achieved by updating the OMHelper playerState field :

    OMHelper.playerState = PlayerState.COLLAPSED
EnumDescription
MINIMIZEDThe player is collapsed in such a way that the video is hidden. The video may or may not still be progressing in this state, and sound may be audible. This refers to specifically to the video player state on the page, and not the state of the browser window
COLLAPSEDThe player has been reduced from its original size. The video is still potentially visible
NORMALThe player's default playback size
EXPANDEDThe player has expanded from its original size
FULLSCREENThe player has entered fullscreen mode

iOS SDK (Swift)

The Dailymotion Swift iOS SDK is a swift wrapper around the WKWebView Class that allows developers to easily embed the Dailymotion Player in their app and let them communicate with its API natively.

The Swift iOS SDK is open source and you can get all required information plus a sample app here on our GitHub. It requires Xcode 8 and later, Swift 4 and iOS 8+. If you require an Objective-C version please check out our git here.

The Dailymotion iOS SDK, starting from version 3.10.0 has integrated the latest changes on the IDFA collection as part of the App Tracking Transparency compliance. It is recommended to all partners to utilize the latest SDK version, IDFA will not be collected on versions prior to 3.10.0 on iOS 14.5.

How to use

  1. Add our SDK to your project, the easiest way to do so is with CocoaPods, a dependency manager solution. Add the below pod to your Podfile.

    use_frameworks!
    pod 'DailymotionPlayerSDK'
    
  2. Import DailymotionPlayerSDK into each file where you need to create an instance of Dailymotion player.

    import DailymotionPlayerSDK
    
  3. Inside a view controller where you want to display the player, create a fresh DMPlayerViewController instance and set your view controller as delegate. Please, ensure your view controller conforms to the DMPlayerViewControllerDelegate protocol.

    import DailymotionPlayerSDK
class VideoViewController: UIViewController {
    private lazy var playerViewController: DMPlayerViewController = {
      let controller = DMPlayerViewController(parameters: [:])
        controller.delegate = self
        return controller
    }()
}
//MARK: - Conform to protocol
extension VideoViewController: DMPlayerViewControllerDelegate {
  func player(_ player: DMPlayerViewController, didReceiveEvent event: PlayerEvent) {
  }
  func player(_ player: DMPlayerViewController, openUrl url: URL) {
  }
  func playerDidInitialize(_ player: DMPlayerViewController) {
  }
  func player(_ player: DMPlayerViewController, didFailToInitializeWithError error: Error) {
  }
}
  1. Add the playerViewController as a child view controller. Then pass a video id to the player load() method. Once the player is initialized, it will take care of loading the video and start the playback.

    playerViewController.load(videoId: "x84sh87")
    

Using player parameters

To customize the player, select the required parameters from the player parameter list and pass them to the player init method. The params value should contain a String Array with the customization values. If you don't need any customization, pass an empty array.

let parameters: [String: Any] = [
    "logo": "false", //to disable the Dailymotion logo
    "ui-highlight": "FF0000",  //to color the player UI using HEX value
]
let playerViewController = DMPlayerViewController(parameters: parameters)

Some parameters can be passed in on player creation but also used with the load method to update their runtime config. These parameters include video, playlist, ads_params & start. These params require some encoding on the partner's side. Please see the example below of the steps required.

func loadVideo(withId id: String) {
  let parameters = ["start": 30]
  guard
    let encoded = try? JSONEncoder().encode(parameters),
    let params = String(data: encoded, encoding: .utf8)
  else { return }
  playerViewController.load(videoId: id, params: params)
}

Player Parameters for iOS

Use the below parameters to customize your player via the iframe or SDK embed.

ParameterInfoType
autoplayAutomatically attempt to start playback with sound, if it is blocked by the browser, the player will force the video muteBoolean
controlsWhether to display the player controls, true by defaultBoolean
idID of the player unique to the page to be passed back with all API messagesString
muteWhether to mute the videoBoolean
qualitySpecify the suggested playback quality for the videoNumber
sharing-enableWhether to display the sharing buttonBoolean
startSpecify the time (in seconds) from which the video should start playingNumber
subtitles-defaultSpecify the default selected subtitles languageString
syndicationPass your syndication key to the playerString
ui-highlightChange the default highlight color used in the controls (hex value without the leading #). Color set in the Partner HQ will override this paramString
ui-logoWhether to display the Dailymotion logoBoolean
ui-start-screen-infoWhether to show video information (title and owner) on the start screenBoolean
playlistSpecify a playlist ID to populate the Up Next Queue with videos from a playlistString
fullscreenWhether to display the fullscreen buttonBoolean
scaleModeSpecify the default focus of the player in order to reframe and refocus on a specific area in the video. To be used for scaling and repurposing of videos between different aspect ratios for example landscape to portrait. Values ( ‘fit’, ‘fill’, ‘fillLeft’, ‘fillRight’, ‘fillTop’, ’fillBottom’ )String
loopWhether to loop a video or an entire playlist. A video embed will start over again automatically. A playlist embed will start to play from the first item in the playlist after the entire playlist has finishedBoolean

Methods

Our iOS SDK is loaded with all the functionality you need to create a unique video-centric application. Once the player is loaded, you can use the Player API and our player methods.

playerViewController.play()
MethodDescription
load(params: String)Calls the initialize method, loads the player with a video associated with the video id (e.g. x7tgad0).
play()Starts or resumes video playback
pause()Pauses videos playback
toggleFullscreen()Toggle the fullscreen state of the player and fullscreen UI component. The method should be used in association with the native fullscreen functionality in your app.
unmute()Unmute the player
mute()Mute the player
seek()Seek to the specified time in video playback in seconds.
toggleControls()Disables the player UI when set to false, enables when true

Player events

The player sends events when a specific player property changes or becomes available. It is possible to add listeners to specific events. The events are split between two groups: namedEvent and timeEvent. For a list of all events, please see our Player API reference here.

Below is an example of how to set a listener for loadedmetadata & apiready event.

extension ViewController: DMPlayerViewControllerDelegate { 
    func player(_ player: DMPlayerViewController, didReceiveEvent event: PlayerEvent) {
        switch event {
        case .namedEvent(let name, _) where name == "loadedmetadata":
            print("Player Metadata loaded")
        case .namedEvent(let name, _) where name == "apiready":
            print("Player is ready")
        default:
            break
        }
    }
}

Player properties

It is possible to get access to information about the player's current state or specific player properties. Add a listener to an event and retrieve the corresponding player property, depending on the event type, use the data or position value.

func player(_ player: DMPlayerViewController, didReceiveEvent event: PlayerEvent) {
    switch event {
    case .namedEvent(let name, let data):
        print("\(name) - \(data)")
    case .timeEvent(let name, let position):
        print("\(name) - \(position)")
    }
}

Best practices

Player Ready Event:
When the player is ready to receive API commands it will send the apiready event. Listen to this event to ensure the player is ready to receive any API commands.

Preload player:
In your application, you can preload the player before the user attempts to play a video. In order to load the player, you must use the DMPlayerViewController() method, followed by the load method when you want to load a video in the player.

Reuse player:
When using our player in an application, you can (and should) reuse the same player instance, therefore a single-player instance can load multiple videos.

Handle fullscreen orientation and state:
The toggleFullscreen() method toggles the fullscreen UI component and the player fullscreen state, it doesn't have control of the fullscreen functionality of your application. This method should be used alongside the native functionality adjusting the player orientation. You can see an example of how it could be handled in our sample application.

Sample application:
You can access a sample application utilizing our SDK from our git here. Check out the SDK repo and the sample will be available.

TCF2

The iOS SDK complies with IAB TCF2 standards and will take care of everything by default starting from version 3.8.0+. It will automatically access the stored content string and pass it through to the player.

OM SDK

Open Measurement SDK from IAB is designed to facilitate third-party viewability and verification measurement for ads served to web video and mobile app environments. For more details see here.

We have integrated the SDK in our Dailymotion Player SDK and it does more or less everything out of the box:

  • Ad session management
  • Ad main signals (play, buffer_start, buffer_end, pause, resume, quartiles, click)
  • Device and Player volume management
  • Basic Player state handling. NORMAL or FULLSCREEN based on player fullscreen state.

Please note that It is recommended to update at all times the player state if your app has more player layout variety, such as mini-player, picture-in-picture, etc. This can be achieved by updating the playerState property in your DMPlayerViewController instance.

    player.playerState = .fullscreen

Player state

EnumDescription
MINIMIZEDThe player is collapsed in such a way that the video is hidden. The video may or may not still be progressing in this state, and sound may be audible. This refers to specifically to the video player state on the page, and not the state of the browser window
COLLAPSEDThe player has been reduced from its original size. The video is still potentially visible
NORMALThe player's default playback size
EXPANDEDThe player has expanded from its original size
FULLSCREENThe player has entered fullscreen mode

Embed the player on AMP

AMP (Accelerated Mobile Pages) is an open-source project which provides a robust framework for creating a lightweight experience of a webpage that loads lightning fast on mobile connections.

In order to build these pages the framework provides a large library of components. This library includes a dedicated Dailymotion AMP component which is available for anyone to use Dailymotion videos on their AMP site.

Required Script

<script async custom-element="amp-dailymotion" src="https://cdn.ampproject.org/v0/amp-dailymotion-0.1.js"></script>

Our Component

<amp-dailymotion>

Example embed

<amp-dailymotion
    data-videoid="x2m8jpp"
    layout="responsive"
    autoplay
    data-mute="true"
    width="480"
    height="270"
    data-param-ads_params="12345"
    data-param-syndication=12345">
</amp-dailymotion>

In order to autoplay correctly on AMP pages it is required that both autoplay and mute are configured. Add both the autoplay & data-mute="true" to configure this. Our tap to unmute feature won't be visible, however, this framework provides its own version.

For player parameters that don't have matching AMP attributes, it's possible to add in any player parameter using the data-params-{Player_Param}.


oEmbed API

oEmbed is a format for allowing an embedded representation of a URL on third party sites.
The oEmbed API allows a website to turn a Dailymotion video page URL into a structured data set, making it easy to embed and share content across the web.

When to use it

This protocol is the preferred method when you need to transform the URL provided into an embed code. For more information, see the oEmbed specification.

How to use it

Use the following endpoint to request the corresponding video information using only a Dailymotion video URL. Add in URL params from the table below to configure the response.

https://www.dailymotion.com/services/oembed?url=VIDEO_URL?PARAM1&PARAM2

Example call using URL parameters:

https://www.dailymotion.com/services/oembed?url=https://www.dailymotion.com/video/x7tgad0?maxwidth=480&maxheight=269&autoplay=true

Example JSON response:

{
  "type": "video",
  "version": "1.0",
  "provider_name": "Dailymotion",
  "provider_url": "https://www.dailymotion.com",
  "title": "Midnight Sun | Iceland",
  "description": "",
  "author_name": "Dailymotion player demo",
  "author_url": "https://www.dailymotion.com/dailymotionplayerdemo2",
  "width": 478,
  "height": 268,
  "html": "<iframe frameborder=\"0\" width=\"478\" height=\"268\" src=\"https://www.dailymotion.com/embed/video/x7tgad0?autoplay=true\" allowfullscreen allow=\"autoplay\"></iframe>",
  "thumbnail_url": "https://s2.dmcdn.net/v/SBL5q1U_Klu8xz_7m/x240",
  "thumbnail_width": 427,
  "thumbnail_height": 240
}

URL parameters

ParameterParameter description
urlThe Dailymotion URL for a video (required)
maxwidthThe maximum width the embedded video can take on the destination page
maxheightThe maximum height the embedded video can take on the destination page
formatResponse format, either json or xml. Defaults to json
callbackWhen returning JSON, wrap in this function
autoplayAutomatically start playback of the video. Defaults to false
syndicationYour syndication key

Customize the player

The Dailymotion Player can be customized to match your brand perfectly, with a modern UI that works across all platforms. If you need a completely custom experience our SDKs allow you to disable our UI interface and use your own.

Please note, that depending on where and how you embed the player, how it is customized will vary.

On web

The main player experience must be created and managed through the Player configurator UI in the Partner Space (Players tab) or the REST API, these allow you to configure the player settings seen from the list here. Additional customization is achievable at runtime with player parameters seen from the list here

In app

The player in app using our natives SDK can be customized using client side parameters. The parameters which are available in these environments can found in their corresponding iOS parameters and Android parameters sections.

Our Web SDK and Player API are the to-go tools to take full control of the player. You can control not only the behavior of the player but get access to all the properties and methods of the player.


Working with player settings

When embedding the Player on the web it's required to specify the Player settings to manage the player behavior on your properties.

The player settings manage the main player experience and are controlled through the Player configurator UI in the Partner Space (Players tab) or the REST API. Client-side customization is not possible to override any settings value.

Please note player customization in our native SDKs is currently managed via Player parameters, the list of the useable parameters are available in the corresponding iOS and Android sections.

Player settingFieldDefaultDescriptionValues
AutostartautostartfirstTimeViewableTo control the player's autoplaying behaviour"firstTimeViewable","on", "off"
Picture-in-PicturepipoffTo specify the Dailymotion picture-in-picture behaviour"instant", "on", "off"
Start PiP in Expandedenable_start_pip_in_expandedfalseWhether to start the PiP in expanded mode on small viewports"true","false"
Aspect ratioaspect_ratio16:9To control the aspect ratio of the player. Only available when embedding using JavaScript"16:9", "4:3", "1:1", "3:4", "9:16", "inherit"
ColorcolorundefinedChange the default highlight color used in the controls (hex value without the leading #). Color set in the Partner HQ will override this param-
Controlsenable_controlstrueWhether to enable the player controls or not"true","false"
Logoenable_dm_logotrueWhether to display the Dailymotion logo or not"true","false"
Queueenable_queuetrueWhether to show the Up Next queue. see note below"true","false"
Auto Nextenable_autonexttrueWhether to play automatically the next item in the queue"true","false"
Sharingenable_sharingtrueWhether to enable the sharing button or not"true","false"
Video Infoenable_infotrueTo remove title and video owner information"true","false'
Channel Owner Linkenable_channel_linktrueTo remove the link on the channel"true","false"
Video Title Linkenable_video_title_linktrueTo remove the link on the video title"true","false"
Embed script URLembed_script_urlundefinedURL of the player to be used in a script HTML tag-
Library script URLlib_script_urlundefinedURL of the player embed library to be used in a script HTML tag-
Embed HTML URLembed_html_urlundefinedURL of the player to be used in an iFrame HTML tag-
Sharing URLenable_sharing_url_locationpage linkTo control whether the user shares the page link or the dailymotion link location when using the share functionality of the player. The page link is only available when embedding using JavaScript-

Please note to create a player configuration through the Dailymotion REST API you need to have the manage_players specific permission. For the exhaustive list of fields or for more information about using the REST API please see here.


Working with player parameters

Additional runtime customization is achievable using player client-side parameters from the table below. These URL encoded query strings can easily be added to the data-params attribute on the Player embed script, within the createPlayer() method when using the Player API or passed into the src URL for an Iframe embed. These parameters allow you to specify additional behaviors or pass in required values to a specific player embed.

To note, when embedding using the Native iOS and Android SDKs please refer the list of the available parameters in their corresponding iOS or Android section.

NameParameterDefaultDescriptionValuesType
Video IDvideoundefinedThe ID of the video to load-String
Playlist IDplaylistundefinedThe ID of the playlist to load-String
Advertising ConfigcustomConfigundefinedFor passing in unique keys for advertising purposes. For example, customConfig[customParams]=adKey-Object
SyndicationsyndicationKeyundefinedPass your syndication key to the player-String
Scale modescaleModefitTo adjust the player's video focus"fit", "fill", "fillLeft", "fillRight", "fillTop" & "fillBottom"Enum
MutemutefalseWhether to mute the video or not. To note, enabling mute may impact monetization. The player provides smart mute behaviour, 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."true","false"Boolean
StartstartTime0Specify the time (in seconds) from which the video should start playing-Number
LooploopfalseWhether the player is currently in loop mode"true","false"Boolean

Player embed script

Add the URL encoded query string to the data-params attribute when embedding the player with the Player embed script.

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-video="x84sh87" data-params="startTime=15&loop=true"></script>

Player library script

Add the URL encoded query string to the params object within the createPlayer() method when embedding the player with the Player Library.

dailymotion
  .createPlayer("my-dailymotion-player", {
    video: "x84sh87",
    playlist: "x5zhzj",
    params: {
      startTime: 15,
      loop: true,
    },
  })
  .then((player) => console.log(player))
  .catch((e) => console.error(e));

iFrame embed

Add the URL encoded query string after the video ID in the src attribute of the iFrame, then add any of the available parameters separating each parameter with an &.

<iframe frameborder="0" width="640" height="360" 
    src="https://geo.dailymotion.com/player/{Player ID}.html?video=x84sh87&startTime=5&mute=true" 
    allowfullscreen 
    allow="autoplay; fullscreen; picture-in-picture">
</iframe>

Working with Picture-in-Picture(PiP)

The Dailymotion Player is compatible with native Picture-in-Picture(PiP) in addition to our own out-of-the-box Picture-in-Picture product. Our PiP solution is easily managed through the Partner HQ, it delivers a smooth and engaging user experience and will help boost your monetization opportunities.

A verified partner can enable the Dailymotion Picture-in-Picture feature using our player configurator page or by allocating the setting pip to on |off| instant via the REST API.

PiP settings

As the user scrolls the page, the video must transition from playing in the in-page video player to playing in a sticky video player, which remains in view as the user scrolls the page.

ValueInfo
pip: offThe PiP is not enabled
pip: onThe PiP will tranisition after the main player was firstly seen by the user and after they scroll the page so less than 50% of the main player is within the viewport
pip: instantThe PiP will launch once the player is loaded and the main player isn't in the user's viewport

When triggered a mini player will be displayed at the bottom right on wide screens and at the top on narrow screens. Further positioning can be achieved using custom CSS, see the section below.

On desktop the PiP frame will transition and appear at the bottom right of the screen. It's optimized for viewability, performance, monetization and built with a minimal, user-centric design. The desktop will have a minimum pip size of 410px width with a 16:9 aspect ratio sized responsively.

On mobile, or on narrow viewport, the PiP player will automatically adapt and have two modes:

Mobile specific behavior

ValueInfo
collapsedThe video player height is reduced not to interfere with page content (articles, text, images)
expandedThe video player is at full width and height (preserving video ratio)

By default on mobile, the player will initially transition to a collapsed format unless the configuration is set to to "Start PiP in expanded" option in the partner HQ or REST API. The viewers can alter between the mobile PiP formats using the collapsed toggle on the UI. During advertisements the PiP will automatically expand to preserve ad viewability on all devices. The Mobile PiP will take 100% of the width on a mobile screen. The PiP can also be programmatically closed, resumed, collapsed or expanded using allocated methods via the API, please see the below examples.

Only one PiP will be launched per page, when using multiple player configurations its recommended to only embed one player configuration with PiP active. In the case of instant PiP the first player which will load on the page will launch in instant PiP.

PiP customization

The PiP will be displayed at the bottom right on wide screens and at the top on narrow screens by default. Its possible to reposition the PiP by adding specific CSS code for the dedicated element IDs. You can view the CSS samples below or view a live demo in our codepen.io collection here.

CSS SelectorInfo
#dailymotion-pip-large-viewportTargets PiP for "corner display" on large viewports
#dailymotion-pip-small-viewportTargets PiP for "top sticky display" on small viewports

⚠️Make sure to add the !important keyword to all your custom CSS rules in order to override already existing styles and behaviors, you will find below some common customization examples.

Reposition PIP desktop - top right:

#dailymotion-pip-large-viewport {
  right: 0 !important;
  top: 0 !important;
}

Reposition PIP desktop - bottom left without margin:

#dailymotion-pip-large-viewport {
  bottom: 0 !important;
  margin: 0 !important;
  left: 0 !important;
}

Reposition PIP mobile - below menu bar:

#dailymotion-pip-small-viewport {
  top: 50px !important;
}

Reposition PIP mobile - bottom of the page:

#dailymotion-pip-small-viewport {
  bottom: 0px !important;
  top: initial !important;
}

Programmatically interacting with PiP

Please note that to programmatically interact with the PiP the feature has to be enabled with the embed player configuration. Once the PiP is activated the Player API exposes four global methods:

TypeMethodInfo
Close PiPdailymotion.pipClose()To suspend PiP functionality.
Resume PiPdailymotion.pipResume()To resume PiP functionality after it has been suspended.
Collapse mobile PiPdailymotion.pipCollapse()To collapse the sticky PiP displayed on mobile (delayed if an ad is running).
Expand mobile PiPdailymotion.pipExpand()To expand the sticky PiP displayed on mobile.

Working with autostart

In recent years browsers have been setting stricter autostart policies. Although you can activate the autostart behavior in the player's configuration, complete control over autostart behavior isn't possible, due to users' browser settings.

Our player includes smart autostart behavior that is engineered to maximize the chances of automatically playing a video in all browser conditions. When autostart is enabled, the player goes through the following waterfall:

  1. If the browser allows autostarting, the player will automatically play with sound.

  2. If autostart is prevented by the browser, it will attempt to play the video again but will automatically mute itself. In this case on mobile devices, the player will display a Tap to unmute call to action that allows users to unmute with a single tap anywhere on the player.

  3. If the browser doesn't allow autostart the player will display a start screen and wait for the user's interaction to start video playback.

Please note, where possible we advise to utilize the modefirstTimeViewable, it will help safeguard viewability and monetization. Its only available when embedding the Player on web using either the Player embed script or when adding the player via the Player library script.


Working with the advertising configuration

The advertising parameter is a custom parameter used for targeting and reporting purposes. Verified partners can use the parameter to dynamically pass information to their VAST tag. The parameter is passed in on player initialization and can be changed dynamically by the Player API using the setCustomConfig()​ method which updates the value on video change. Some configuration is also required on our side. Please see examples of the below embed types on how to pass in the parameter on initialization or contact our support team for more information.

Please note that depending on the embed type, either the player embed script or the API, some encoding may be required if utilizing multiple ads parameters values. If more complex use-cases need to be handled we invite you to contact our Ads Ops team. Please see the table and sample embeds below.

TypeInfoEncoding required
Player embed scriptPass values using the customConfig[customParams] parameter in the data-params attributeYes
Player library scriptPass values when using the createPlayer() methodNo
Player iFramePass value using query string "customConfig[customParams]"Yes
Update with the Player APIUpdating the ad values using the setCustomConfig() methodNo

Player embed script - values [test/value=1234&value2=3214]

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-video="" data-params="logo=false&customConfig[customParams]=test%2Fvalue%3D1234%26value2%3D3214"></script>

Player Library Script - values [test/value=1234&value2=3214]

To 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.

dailymotion.createPlayer("player1", {
  video: "x84sh87",
  params: {
    customConfig: {
      customParams: "test/value=1234&value2=3214",
    },
  },
});

Player API - update values with setCustomConfig()

dailymotion.getPlayer("player").then((player) => {
    player.setCustomConfig({ customParams: new_params })
});

Player iframe - values [test/value=1234&value2=3214]

 <iframe src="https://geo.dailymotion.com/player/x938as.html?video=x84sh87&customConfig[customParams]=test/value=1234&value2=3214&startTime=10" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen frameborder="0" width="640" height="360"></iframe>

Working with the referrer policy

It may be required to adjust the referrer-policy string to match your own privacy policy or integration requirements. The Dailymotion video player relies on the referrer passing the full URL to provide valuable products to publishers. Our player by default won't specify the referrer-policy setting, if no referrer-policy is set the browser's default policy will be applied.

You have full control over how much data is available in the referrer. If you want the Dailymotion video player to receive the full URL in the Referer HTTP Header you need to add the “no-referrer-when-downgrade” to the referrer-policy parameter in the player embed. Please see the embed examples below on how to adjust the policy when using web embeds.

Player script embed

<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-video="x84sh87" referrerpolicy="no-referrer-when-downgrade"></script>

Player library embed

dailymotion.createPlayer("player", {
  video: "x84sh87",
  referrerPolicy: "no-referrer-when-downgrade",
});

iFrame embed

<iframe src="https://geo.dailymotion.com/player/x938as.html?video=" allow="autoplay; fullscreen; picture-in-picture" allowfullscreen frameborder="0" width="640" height="360" referrerpolicy="no-referrer-when-downgrade"></iframe>

Working with the REST API

To create a player through the Dailymotion REST API you need to have the manage_players specific permissions. Please refer to the list of extended permissions to obtain them. Define and specify the required fields and then perform a POST request. For the exhaustive list of fields refer to this page.

Example of player creation:

curl -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -d 'label=My new player' \
     https://api.dailymotion.com/me/players

Once a player has been created and associated with your account it is then possible to update it or delete it. You can test and learn more about the REST API with the explorer.

After the creation of your player you must add it to your page using a <script> tag. You can retrieve the script URL from the REST API (see embed_script_url field).



Working with TCF2

The embedded Dailymotion Player complies with the IAB TCF 2 standards and automatically detects any TCF 2-certified CMP. In such a case, it collects consent sent by a Publisher’s TCF 2.-certified CMP and does not deploy its independent built-in consent dialogue (i.e. a cookie banner). Note that Dailymotion is a registered IAB Vendor (n° 573). When available, the Dailymotion Player will always rely on the consent that it receives from a CMP through the standard CMP integration. The CMP integration is currently offered at no additional fees to Publishers. 

Having a single cookie banner contributes to a less disruptive user experience which may improve the consent rate and potentially result in increased revenues. If the embedding website doesn't use a TCF 2-compliant CMP, we use the Player’s built-in cookie banner as a fallback solution.


JavaScript Player API Reference

Each script used to embed the player also provides access to the Player API without any additional configuration, everything is available and bundled from the Player embed script. The Player API allows you to create a player, retrieve information about a specific player state, listen to player events and trigger player 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.

Methods

API commands can be called to programmaticallly create and control the player.

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 video, playlist or player can by specified using their corresponding paramater 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 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
dailymotion.pipResume()To resume PiP, the method applies to the whole webpage.
dailymotion.pipCollapse()To collapse the mobile sticky PiP, the method applies to the whole webpage
dailymotion.pipExpand()To expand the mobile sticky PiP, the method applies to the whole webpage

Player methods:

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

MethodInfoValuesTypes
loadContent()To load a video or a video with a playlist, a video id is mandatory({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 levelBetween 0 & 1Float
setSubtitles()To activate a subtitles track to a specified language if available-String
setQuality()To set the video's quality to the specified quality[240, 380, 480, 720, 1080, 1440, 2160 default]String
seek()To seek to the specified time in video playback in seconds-Number
setControls()To enable or disable the player's controls UI, we advise disabling controls on intialization using the player configurator if utilizing your own player UI design"true","false"Boolean
setFullscreen()To enable or disable fullscreen mode"true","false"Boolean
setMute()To set the mute mode of the player"true","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"fit", "fill", "fillLeft", "fillRight", "fillTop" & "fillBottom"Enum
updateParams()To change the following player config values at runtime scaleMode, mute, volume, enableControls & customConfig-Object
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(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(event:String, [listener:Function])-
getState()To retrieve the current state of the player. see usage here--
getSettings()To retrieve the Partner Space configuration of a player. see usage here--

Events

The player emits events relating to the change of the player state, video playback and ad content.

To pick up on these events use the method player.on("YOUR_EVENT", (state)).

If you want to add a unique listener to be invoked only once, pass an additional object composing of {once:true} into the method.

It's possible to unbind specified listeners using the player.off("YOUR_EVENT").

Player events

EventInfo
PLAYER_ASPECTRATIOCHANGESent when the aspect ratio of the player changes after calling setAspectRatio('4:3'))
PLAYER_CONTROLSCHANGESent when the availability to use our player controls changes
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_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_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
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_STARTSent when the player begins playback of an ad video
AD_TIMECHANGESent when the playback position of an ad changes

Example of adding a listener to the player event PLAYER_START

player.on(dailymotion.events.PLAYER_START, (state) => {
  console.log("Received PLAYER_START event. Current state is:", state);
});

Example of adding a unique listener which will be automatically removed when invoked Add { once: true } as a third option parameter.

player.on(
  dailymotion.events.PLAYER_START,
  (state) => {
    console.log("Received PLAYER_START event. Current state is:", state);
  },
  { once: true }
);

Example of unbinding all listeners from PLAYER_START event

player.off(dailymotion.events.PLAYER_START);

State

It's possible to access player and video data using the getState() method, which on resolve returns an object representation of the player state. From the state it is possible for example to pick up if the PiP is currently displayed, the video duration or if the player is in or out of the user's viewport.

Player State Structure

NameTypeInfoValues
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"error", "stopped", "skipped" or null
adErrorObjectContains the infos about the last error that occurred with the ad or null-
adIdStringThe id of the ad-
adIsPlayingBooleanIf an ad resource is running"true","false"
adIsSkippableBooleanIf the ad can be skipped by the user at this moment"true","false"
adPositionStringThe position of the ad in the video,null if no ad is running"preroll", "midroll", "postroll" 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-
playerAreControlsEnabledBooleanIf the player controls are enabled"true","false"
playerAspectRatioStringThe player current aspect ratio"inherit", "16:9", "4:3", "1:1", "3:4", "9:16"
playerErrorObjectContains the infos about the last error that occurred in the player or null-
playerIsAlertDialogDisplayedBooleanIf the player has the alert dialog displayed"true","false"
playerIsBufferingBooleanIf the player is loading the media resource"true","false"
playerIsCriticalPathReadyBooleanIf the player is ready to play"true","false"
playerIsMutedBooleanIf the player is muted"true","false"
playerIsNavigationEnabledBooleanIf the next and previous controls in the PiP are enabled"true","false"
playerIsPipNativeSupportedBooleanIf the player does support the native PiP"true","false"
playerIsPlaybackAllowedBooleanIf the player is allowed to play, depending on the browser permissions"true","false"
playerIsPlayingBooleanIf the player is currently playing video or ad content"true","false"
playerIsStartScreenBooleanIf the player is in start screen"true","false"
playerIsReplayScreenBooleanIf the player is in replay screen"true","false"
playerIsViewableBooleanIf the player is within the viewability threshold"true","false"
playerNextVideoStringThe id of the video next video in the queue-
playerPipDisplayStringThe current display mode of PiP, If its display on a larger/smaller Screen"largeViewport", "smallViewport"
playerPipStatusStringThe current PiP feature status"enabled" ,"disabled" or "closed"
playerPipIsExpandedBooleanIf the mobile sticky PiP is expanded"true","false"
playerPlaybackPermissionReasonStringThe reason why the playback has been allowed or not"allowedFallbackMuted", "allowed", "rejectedInactiveTab", "rejectedByBrowser"
playerPresentationModeStringThe current mode where the player is displayed"inline", "nativePip", "pip" or "fullscreen"
playerPrevVideoStringThe id of the video previous video which was played-
playerScaleModeStringThe player's current scale mode"fit", "fill", "fillLeft", "fillRight", "fillTop", "fillBottom"
playerVolumeNumberThe current volume level. The volume and mute params operate separately, therefore, you could have a player with full volume, but also mutedBetween 0.0 to 1.0
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-
videoIsPasswordRequiredBooleanIf the video required a password to be read"true","false"
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-
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-

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",
  "playerAreControlsEnabled": true,
  "playerAspectRatio": "16:9",
  "playerError": null,
  "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,
  "videoCreatedTime": 1551103337,
  "videoDuration": 214.06,
  "videoId": "x730nnd",
  "videoIsPasswordRequired": false,
  "videoOwnerId": "x23rwb7",
  "videoOwnerScreenname": "Player team",
  "videoOwnerUsername": "player-team",
  "videoQualitiesList": ["1080", "720", "480", "380", "240", "144"],
  "videoQuality": "Auto",
  "videoSubtitles": "en",
  "videoSubtitlesList": ["fr", "en"],
  "videoTime": 60.12,
  "videoTitle": "Dailymotion video",
}

Access the Player settings

It's possible to retrieve the intial player configuration including the playerID using the getSettings() method. On resolve this returns an object representation of the player config.

Example of logging the player settings to the console

dailymotion
  .getPlayer()
  .then((player) => {
    console.log(player.getSettings());
  })
  .catch((e) => console.error(e));

Example player settings object

{
  "id": "PLAYERID",
  "aspectRatio": "16:9",
  "autostart": "firstTimeViewable",
  "color": "",
  "enableAutoNext": true,
  "enableControls": true,
  "enableDMLogo": true,
  "enableInfo": true,
  "enableQueue": true,
  "enableSharing": true,
  "enableSharingUrlLocation": true,
  "enableChannelLink": true,
  "enableVideoTitleLink": true,
  "enableStartPipExpanded": true,
  "enableHeaderDetectionOverlap": false,
  "pip": "off"
}

Optimization info

Please check out the player embed collection on our Dailymotion codepen account to see some useful code snippets that you can test and use within your project.

In order to benefit from the best performance of the new player solution, please consider the following tips from our engineers.

  1. Add preload and preconnect directives towards to the top of the <head> section of the HTML response.
 <link rel="preload" href="{https://geo.dailymotion.com/libs/player/{Player ID}.js" as="script">
  1. Load the player or player library directly, avoid using any third-party solution such as Google Tag Manager. On top of making it load faster some tag management systems or third parties may be blocked therefore preventing the player load. Player libraries can be put in the <head> section of your document whereas player embed script must be placed in the <body> section.

  2. The Dailymotion player is a sophisticated piece of software that handles several complex processes for you (adaptive streaming, ads monetization, tracking and many more). If any video player is an important and engaging component of your website or app it should be prioritized infront of other resources. Its advisable to reduce the amount of JavaScript executed before the player loads; use the "defer" attribute on non-critical scripts, or load them dynamically via JS instead of HTML.


⚠️Legacy player functionality

Please be aware we are in the process of discontinuing support for the below products. We recommend all partners to utilize the latest integration methods outlined in the embed the player on web section found here. The following section outlines the functionality and player services that are considered to be no longer available.

JavaScript Player API Reference(legacy)

Our Player API allows you to interact with and take complete control of the Dailymotion video player. It can be accessed through our SDKs and provides access to all the player methods, events and properties. Our APIs allow you to create a unique and personalized experience.

Methods(legacy)

Before sending any API commands to a player instance, you should wait for the apiready player event to be fired.

MethodInfoExample
DM.player()Create a player instance. The SDK will take care of generating and injecting an iframe into the div placeholderDM.player(document.getElementById("player")
load(String)Load the player with a video ID (e.g. x7tgad0)player.load("x7tgad0")
load({video: String, playlist: String, autoplay : Boolean, start : Float})Load the player with a video and configure other runtime time parametersplayer.load( {video: "x7tgad0", playlist: "x5zhzj", autoplay:false, start: 5})
play()Start or resume video playbackplayer.play()
pause()Pause video playbackplayer.pause()
setVolume(Float)Set the player's volume to the specified level between 0 & 1. ie, 0.5 = 50%player.setVolume(0.5)
setSubtitles(String)Activate subtitles track to a specified language if availableplayer.setSubtitle('fr')
seek(Float)Seek to the specified time in video playback in secondsplayer.seek(30)
setQuality(String)Set the video's quality to the specified quality ['240', '380', '480', '720', '1080', '1440', '2160' 'default']player.setQuality('720')
setMuted(Boolean)Enable or disable muteplayer.setMuted(true)
setFullscreen(Boolean)Enable or disable fullscreen modeplayer.setFullscreen(true)
setControls(Boolean)Enable or disable the player's controls UIplayer.setControls(false)
togglePlay()Switch the player's playback state between play/pauseplayer.togglePlay()
toggleControls()Switch the player's controls UI between enabled/disabledplayer.toggleControls()
toggleMuted()Switch the player's Mute state between muted/unmutedplayer.toggleMuted()
watchOnSite()Redirect to watch video on Dailymotion.complayer.watchOnSite()
setAdsConfig()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 fileplayer.setAdsConfig({ads_params: "your_ads_params"})

Events(legacy)

The player emits events relating to the change of the player state, video playback and ad content. To listen to specific player events, you must integrate the player using our SDKs.

Player events(legacy)

Player eventDescription
apireadySent when the player is ready to accept API commands. Do not try to call functions before receiving this event
controlschangeSent when the availability to use our player controls changes (visible or hidden)
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(), load(), etc.)
endSent when playback of the content video, and eventual post-roll ad video, is completed
endedDeprecated. Use video_end instead
errorSent when the player triggers an error. Please see error codes here
fullscreenchangeSent when the player enters or exits the fullscreen state
playback_readySent 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
seekingSent when the player starts to seek to another position in the video timeline
seekedSent when the player has completed a seeking operation
videochangeSent when a new video has been loaded in the player. (e.g. after calling load(videoId, [params]), or at player start-up)
volumechangeSent when the volume or mute state changes

Video events(legacy)

Video eventDescription
video_startSent when the player begins playback of the content video
video_endSent when the player completes playback of the content video
pauseSent when the video playback has paused
playSent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute
playingSent when the content video starts playing, after the play or waiting event
durationchangeSent when the duration property of the video becomes available or changes after a new video load
loadedmetadataSent when the video's metadata is loaded
waitingSent when the player has to temporarily stop video playback for further buffering of content
subtitlechangeSent when the current subtitle changes
subtitlesavailableSent when subtitles are available, wait until the apiready event to set subtitle via the API
qualitiesavailableSent when video qualities are available
qualitieschangedSent when the video quality changes
timeupdateSent when the playback position changes
progressSent when the browser is fetching the media data
playback_resolution Sent each time any playback request has failed or if the initial playback attempt has succeeded. On dispatch the status and reason values can be accessed from the data.detail object.

Ad events(legacy)

Ad eventDescription
ad_startSent when the player begins playback of an ad video
ad_endSent when the player completes playback of an ad video
ad_pauseSent when the player pauses an ad
ad_playSent when the ad playback starts
ad_timeupdateSent when the playback position of an ad changes
ad_companionsSent 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_clickSent when a user clicks on a video ad
ad_loaded Sent when the player has loaded an advertisement in full or to the extent it can begin playback
ad_impression Sent when the first frame of the advertisement has been displayed
ad_bufferStart Sent when the advertising playback has stopped due to buffering
ad_bufferFinish Sent when the advertising playback has resumed due to the end of buffering
//An example listener to check if the player is ready to accept API commands
player.addEventListener('apiready', function(){
    console.log('Player Ready'); 
});

Player Properties(legacy)

The player API grants access to information about the player's current state and specific properties. The following properties will be maintained currently for utilization for player customization for AMP embeds and when using Android & iOS SDKs.

PropertyInfoType
bufferedTimeThe part of the media resource that has been downloaded in seconds.Number
controlsWhether the player controls are enabledBoolean
currentTimeThe current playback position in seconds of an ad or a video resourceNumber
durationThe duration time of the video resource in secondsNumber
endedWhether the video has endedBoolean
errorContains error code, title and message about the last error that occurred in the playerObject
fullscreenWhether the player is in full-screen modeBoolean
mutedWhether the player is currently mutedBoolean
pausedWhether the current playback state is pausedBoolean
qualitiesThe video qualities that are availableArray
qualityThe current quality value of the video element loadedString
seekingWhether the video element is seekingBoolean
subtitleThe subtitle language code that is currently enabledString
subtitlesThe available subtitle language codes of the media fileArray
volumeThe current volume level. Between 0.0 to 1.0. The volume and mute params operate separately, therefore, you could have a player with full volume, but also mutedNumber
videoContains the video ID and titleObject
companionAdsAn array of parsed companion ad creativesArray
loopWhether the player is currently in loop modeBoolean
//Logging a video title to the console
console.log(player.video.title)

Player Parameters(legacy)

⚠️The below parameters can be utilised still with our Android SDK, iOS SDK & AMPs embeds. However, we are in the process of phasing them out with future SDK updates. In future player customisation will be managed via Player settings using the Partner HQ or REST API.

Use the below parameters to customize your player via the iframe or SDK embed.

ParameterInfoType
autoplayAutomatically attempt to start playback with sound, if it is blocked by the browser, the player will force the video muteBoolean
controlsWhether to display the player controls, true by defaultBoolean
idID of the player unique to the page to be passed back with all API messagesString
muteWhether to mute the videoBoolean
qualitySpecify the suggested playback quality for the videoNumber
sharing-enableWhether to display the sharing buttonBoolean
startSpecify the time (in seconds) from which the video should start playingNumber
subtitles-defaultSpecify the default selected subtitles languageString
syndicationPass your syndication key to the playerString
ui-highlightChange the default highlight color used in the controls (hex value without the leading #). Color set in the Partner HQ will override this paramString
ui-logoWhether to display the Dailymotion logoBoolean
ui-start-screen-infoWhether to show video information (title and owner) on the start screenBoolean
playlistSpecify a playlist ID to populate the Up Next Queue with videos from a playlistString
fullscreenWhether to display the fullscreen buttonBoolean
scaleModeSpecify the default focus of the player in order to reframe and refocus on a specific area in the video. To be used for scaling and repurposing of videos between different aspect ratios for example landscape to portrait. Values ( ‘fit’, ‘fill’, ‘fillLeft’, ‘fillRight’, ‘fillTop’, ’fillBottom’ )String
loopWhether to loop a video or an entire playlist. A video embed will start over again automatically. A playlist embed will start to play from the first item in the playlist after the entire playlist has finishedBoolean

Changelog

2021-12-02

  • New Player Embed global release