Table of content

Getting started with the Web SDK


Overview

Embedding the Player on your website is simple: we have different integration methods available depending on your technical preferences. We recommend using the Player Embed Script or Player Library Script where possible as they provide access to all Player functionalities and to the Platform API.

Embed methodsInfo
Player Embed ScriptEmbed using JavaScript, the single line script will load the Player at the point where you add it to the HTML page. This method provides access to the Platform API.
Player Library ScriptAdd just the library and create the Player programmatically using the Platform API.
Player iFrameEmbed the Player without JavaScript to use a basic Player configuration.
Advanced functionalities such as PiP firstTimeView and enable_receive_url_location will not be available.

Getting started

1 – Create a custom Player configuration

As a first step, you need to create a custom Player configuration associated with your Dailymotion account and identified by a unique Player ID.

Important:

The Player ID is required to ensure accurate monetization, targeting and attribution

A custom Player configuration can be created and managed either through the “Players” tab in the Dailymotion Studio or programmatically via the Platform API.

A Player configuration is composed of several settings that can’t be modified or overridden at run time. These settings can only be updated via the Player configurator in the Dailymotion Studio or the Platform API.

For more information on the settings available, please refer to the section “Player fields” .

2 – Choose an embed method

Once a Player configuration is created you can access the corresponding embed methods to embed content into your properties. Embed scripts can be accessed either from the “Players” tab within the Dailymotion Studio or programmatically via the Platform API.

Find below the 3 embed methods available to embed content on web and examples on how to use them.


Embed methods

Player Embed Script

The Player Embed Script integration method is the easiest way to embed the Player with the library on your site and provides access to the Platform API. It is a single-line script that loads the Player exactly where it is added into the <body> of the page.

Important:

The Player Embed Script should always be loaded directly on every page. We don’t advise using any third-party solution to integrate it.

Embed a video

After adding the Player embed script, use the data-video attribute to specify which video ID to load. It should be added directly to 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 Dailymotion Studio and requires only a video Id to be defined.

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

Embed a playlist

After adding the Player embed script, use the data-playlist attribute to specify which playlist ID to load. It should be added directly to the script tag that loads the pre-configured player.

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

You can play any specific video on top of a playlist, just specify both the video and playlist IDs in the embed script.

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

Embed multiple players

To use multiple Player configurations on a single page just add different embed scripts specifying their unique 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>
Note:

Only embed one player configuration with PiP activated as only one can be launched per page. In the case of instant PiP mode, the first player which will load on the page will launch in instant PiP.

Player Library Script

The Player library script is available for developers who want to load just the library, the Player can be then loaded programmatically via the Platform API. The Player library URL can be either copied from the Dailymotion Studio in the Player’s tab or retrieved from the Platform API (see lib_script_url field).

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

Warning:

The player library should always be loaded directly on every page, we don’t advise using any third-party solution to integrate any player assets.

It takes only 3 steps to load our player using the Player library script:

1. Add the Player library script to your HTML page

Add the library script within the <body> section of the page. This provides access to the Platform API and allows you to create a Player instance programmatically. It should be added before any code that interacts with the Platform API is loaded.

<body>
  <script src="https://geo.dailymotion.com/libs/player/{Player ID}.js"></script>
</body>
2. Add a placeholder for the Player

Add a div placeholder on the page where you want the player(s) to be loaded and assign an id to the container which will be required in the createPlayer() method.

<div id="my-dailymotion-player">My Player placeholder</div>
3. Create the Player using the Platform API

Use the createPlayer() method and pass in the assigned container id to initialize the player, specify the video, playlist and parameters 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.

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


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

<script>
  dailymotion
    .createPlayer("my-dailymotion-player", {
      video: "x84sh87",
  })
    .then((player) => console.log(player)) // you can use web SDK here: https://developers.dailymotion.com/sdk/player-sdk/web/
    .catch((e) => console.error(e));
</script>
</body>

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 specified in the embedded library script will apply to every created player.

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 the playlist Id to be loaded. The Player configuration specified in the embedded library script will apply to every created player.

The playlist must be specified using the playlist attribute.

Tip:

You can play a specific video on top of a playlist, just specify both the video and playlist IDs.

Embed multiple players

Any Player created with the Platform 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 only a single-Player library URL.

If the Player ID is incorrectly specified or does no longer exist the configuration will fall back to a default library configuration. If multiple player scripts are loaded on a page but no player is specified via the createPlayer() method, an error will be logged and the created player will take a default config.

Warning:

It’s not required to embed different Player library scripts for each Player config, only a single library script is required and the other Player configs will be loaded on the fly.

Note:

When adding only one single Player on a page, allow for the configuration to be specified in the library script itself.

Tip:

Only embed one Player configuration with PiP activated as only one can be launched per page. In the case of instant PiP mode, 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”, “auto-sizing” and “Forward full URL” along with access to the Platform API won’t be available. The iFrame Player will benefit only from basic UI customizations specified in the Player configurator UI or Rest API. We recommend Partners take full advantage of our Player technology and use the Player Embed Script or Player Library Script.

Warning:

The iFrame embed type is only appropriate for environments that restrict the use of JavaScript i.e AMP. We encourage where possible to embed the player via one of our provided script embeds.

Embed a video

Use the video param in the src:

<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; web-share">
</iframe>

Embed a playlist

Use the playlist param in the src:

<!-- Replace the Player ID and Playlist ID with your own -->
<iframe frameborder="0" width="640" height="360" 
    src="https://geo.dailymotion.com/player/{Player ID}.html?playlist={Playlist ID}" 
    allowfullscreen 
    allow="autoplay; fullscreen; picture-in-picture; web-share">
</iframe>

Explore the Web SDK Reference

Now that you’ve learned more about how to embed content using the Web SDK, you can dive deeper and see what’s possible to do to improve your integration and customize it to fit your needs with the following elements:

  • Advanced runtime parameters: On top of your Player configuration, you can add extra parameters that can change at runtime.
  • Methods: Our methods allow you to control the Player behavior, customize the user experience and create dynamic interactions.
  • Events: Work with events to capture user interactions with the Player and trigger custom actions.
  • State: Retrieve the data of your Player state

Add runtime Player parameters

While the main Player experience is controlled using the settings defined in your Player configuration from the Dailymotion Studio (Players tab) or the Platform API, additional runtime customization is achievable using client-side parameters. They allow you to specify additional Player behavior or pass in required values to a specific Player embed.

See below how to add runtime Player parameters for each embed method available.

For each example, we’re adding the following runtime parameters to the existing Player config defined in the {Player ID} placeholder:

  • startTime=15: video will start playing from second 15
  • mute=true: video will start muted

Find all available runtime parameters in the Web SDK Reference.

Player Embed Script

Add the URL encoded query string to the data-params attribute.

// Replace {Player ID} with your own Player ID, and x84sh87 with your own video ID
<script src="https://geo.dailymotion.com/player/{Player ID}.js" data-video="x84sh87" data-params="startTime=15&mute=true"></script>
Player Library Script

Add the URL encoded query string to the params object within the createPlayer() method.

// Replace x84sh87 with your own video ID
dailymotion
  .createPlayer("my-dailymotion-player", {
    video: "x84sh87",
    params: {
      startTime: 15,
      mute: true,
    },
  })
  .then((player) => console.log(player))
  .catch((e) => console.error(e));
iFrame

Add the URL encoded query string after the video ID in the src attribute of the iFrame.

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


Use methods

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

Find all available methods in the Web SDK Reference.

Example 1: Use the callback function onScriptLoaded()

The callback function can be used to determine when the Player Library Script is loaded and the global Dailymotion variable is initialized.

if (window.dailymotion === undefined) {
  window.dailymotion = { 
    onScriptLoaded: () => {
      // Create a video player when script has loaded
    }
  }
} else {
  // Script already loaded
}

Example 2: Access Player settings

It’s possible to retrieve the initial Player configuration including the Player ID using the getSettings() method. On resolve, this method returns an object representation of the Player configuration.

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

Which will log the following Player settings object:

{
  "aspectRatio": "16:9",
  "autostart": "on",
  "color": "D0021B",
  "enableAdsControls": true,
  "enableAutonext": true,
  "enableChannelLink": true,
  "enableContextualContent": true,
  "enableCustomRecommendations": true,
  "enableDMLogo": true,
  "enableInfo": true,
  "enablePlaybackControls": true,
  "enableAutomaticRecommendations": true,
  "enableSharing": true,
  "enableSharingUrlLocation": false,
  "enableStartPipExpanded": false,
  "enableStartscreenDMLink": false,
  "enableTitlesInVideoCards": true,
  "enableVideoTitleLink": true,
  "enableWaitForCustomConfig": true,
  "id": "PLAYER_ID",
  "pip": "instant",
  "watermarkImageType": "from_channel",
  "watermarkImageUrl": "",
  "watermarkLinkType": "from_channel",
  "watermarkLinkUrl": ""
}

Listen to events

Listening to events can only be implemented with the Player Embed Script or Player Library Script, not with iFrame embeds.

Find all available events in the Web SDK Reference.

To pick up on events use the method player.on():

player.on(dailymotion.events.YOUR_EVENT, callback) // callback function will be trigger each time 'YOUR_EVENT' is fired

player.on(dailymotion.events.YOUR_EVENT, callback, { once: true }) // callback function will be trigger only the first time 'YOUR_EVENT' is fired

It is also possible to unbind specified listeners using an additional method player.off():

player.off(dailymotion.events.YOUR_EVENT, callback) // the specific callback associated to 'YOUR_EVENT' will be removed

player.off(dailymotion.events.YOUR_EVENT) // every listeners binded to 'YOUR_EVENT' will be removed

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

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

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

Retrieve Player state

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

From the state, it is possible to access required player, video or advertising data for your video application or analytics purposes. For example, you can determine if PiP is currently displayed, access the duration of the video or know if the Player is in or out of the user’s viewport.

Find all available states in the Web SDK Reference.

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,
  "videoCreatedTime": 1551103337,
  "videoDuration": 214.06,
  "videoId": "x730nnd",
  "videoIsCreatedForKids": false,
  "videoIsPasswordRequired": false,
  "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",
}


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 our Player solution, please consider the following tips from our engineers:

  • Add preload and preconnect directives towards 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">
  • Load the Player or Player library directly, avoid using any third-party solution such as Google Ad Manager. Player libraries and the Player Embed Script should be added to the <body> section of your document.
  • Load the Player Library in the <body> section. Ensure any code that interacts with the Player is loaded after it.
  • The Dailymotion Player is a sophisticated piece of software that handles several complex processes for you, such as adaptive streaming, ads monetization, tracking and many more. The loading of the Player should be prioritized in front of other resources where possible. It’s 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 JavaScript instead of HTML.