SDKs

In order to make your developer's life easier, we designed a set of SDKs that enable you to integrate with our API. For now on, available SDKs are:

Those SDKs enable you to access all of the features of the Dailymotion Data API in your favorite language. Some SDKs also support the Player API.

They are available on our Github.

JavaScript SDK

The JavaScript SDK is available on GitHub and must be loaded from https://api.dmcdn.net/all.js.

Loading the SDK

You can load the SDK using a <script> element and by calling DM.init() method. Below is an example of initializing the SDK with all the common options turned on:

<script src="https://api.dmcdn.net/all.js"></script>
<script>
  DM.init({
    apiKey: 'YOUR API KEY',
    status: true, // check login status
    cookie: true // enable cookies to allow the server to access the session
  });
</script>

Loading the SDK asynchronously

The most efficient way to load the SDK in your site is to load it asynchronously so it does not block loading other elements of your page. This is particularly important to ensure fast page loads for users and SEO robots/spiders. Below outlines an example:

<script>
  window.dmAsyncInit = function()
  {
    DM.init({ apiKey: 'your app id', status: true, cookie: true });
  };
  (function() {
    var e = document.createElement('script');
    e.async = true;
    e.src = 'https://api.dmcdn.net/all.js';

    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(e, s);
  }());
</script>

In the example above, the function assigned to window.dmAsyncInit is run as soon as the Dailymotion JavaScript SDK is loaded. Any code you want to run after the SDK is loaded should be placed within this function and after the call to DM.init(). For example, this is where you would test the logged in status of the user or subscribe to any Dailymotion events your application is interested in.

Authentication

The Dailymotion JavaScript SDK allows you to log your users with their Dailymotion account in order to act on their behalf: access content, publish or edit videos, etc. For this purpose, you can use any of:

MethodMethod description
DM.login()Login and/or request extended permissions.
DM.logout()Logout (only if the user is connected with your site).
DM.getLoginStatus()Get current login status from dailymotion.com.
DM.getSession()Synchronous accessor for the current session.

In addition, you can subscribe to the following events using DM.Event.subscribe():

  • auth.statusChange
  • auth.sessionChange
  • auth.login
  • auth.logout

Graph API

You can make Graph API requests using DM.api() method:

var handleAPIResponse = function (response) {
  alert('Name is ' + response.screenname);
};

DM.api('/user/rs', {
  fields: 'screenname'
}, handleAPIResponse);

Player API

To dynamically create a player with which you can interact, use the DM.player() method:

var player = DM.player(document.getElementById('player'), {
  video: 'xwr14q'
});

The player object instantiated implements the Player API.

Here is a complete example of a naive "playlist" implementation that plays the latest "buzz" videos:

var handleAPIResponse = function (response) {
  var videos = response.list;
  var player = DM.player(document.getElementById('player'), {
    video: videos.shift().id
  });

  // At the end of a video, load the next video if any
  player.addEventListener('end', function (e)
  {
    var nextVideo = videos.shift();
    if (nextVideo) {
      e.target.load(nextVideo.id);
    }
  });
};

DM.api('/videos', {
  filters: 'buzz',
  fields: 'id',
  limit: 100
}, handleAPIResponse);

Note: The video option is optional so you can call DM.player(document.getElementById("player")); and load a video dynamically later, through a call to the player.load() method.

Methods

DM.api()

The JavaScript SDK allows you to build rich applications that can make API calls against the Dailymotion servers directly from the user's browser. This can improve performance in many scenarios, as compared to making all calls from your server. It can also help reduce, or eliminate the need to proxy the requests through your own servers, freeing them to do other things.

Signature
DM.api(path, method, params, callback)
Parameters

Except path, all arguments to this method are optional.

NameTypeDescription
pathStringThe resource path.
methodStringThe HTTP method (default “get”).
paramsObjectThe parameters for the query.
callbackFunctionThe callback function to handle the response.
Examples

If you have an authenticated user, get their User Object:

var handleAPIResponse = function (response) {
  alert('Your name is ' + user.screenname);
};

DM.api('/me', {
  fields: 'screenname'
}, handleAPIResponse);

Get the 3 most recent posted video from the authenticated user:

var handleAPIResponse = function(response) {
  alert('Got ' + response.list.length + ' videos' + (response.has_more ? ' and has more' : ''));
};

DM.api('/me/videos', {
  limit: 3
}, handleAPIResponse);

Search for videos with “javascript tutorial” query:

var handleAPIResponse = function(response) {
  alert(response.list[0].title);
};

DM.api('/videos', {
  search: 'javascript tutorial',
  fields: 'title'
}, handleAPIResponse);

If you have an authenticated user with write permission scope and you want to like a video for them:

var videoId = 'xk2jd2';

var handleAPIResponse = function(response) {
  if (!response || response.error)
  {
    alert('Error occured');
  }
  else
  {
    alert('Liked successfuly');
  }
};

DM.api('/me/favorites/' + videoId, 'post', handleAPIResponse);

DM.getLoginStatus()

Find out the current status from the server, and get a session if the user is connected.

The user's status or the question of who is the current user is the first thing you will typically start with. For the answer, we ask dailymotion.com. Dailymotion will answer this question in one of two ways:

  • Someone you don't know.
  • Someone you know and have interacted with. Here's a session for them.

Here is how you find out:

DM.getLoginStatus(function(response)
{
  if (response.session)
  {
    // logged in and connected user, someone you know
  }
  else
  {
    // no user session available, someone you dont know
  }
});

The example above will result in the callback being invoked once on load based on the session from www.dailymotion.com. JavaScript applications are typically written with heavy use of events, and the SDK encourages this by exposing various events. These are fired by the various interactions with authentication flows, such as DM.login().

Events

Event nameEvent description
auth.loginThis event is fired when your application first notices the user (in other words, gets a session when it didn't already have a valid one).
auth.logoutThis event is fired when your application notices that there is no longer a valid user (in other words, it had a session but can no longer validate the current user).
auth.sessionChangeThis event is fired for any auth related change as they all affect the session: login, logout, session refresh. Sessions are refreshed over time as long as the user is active with your application.
auth.statusChangeTypically you will want to use the auth.sessionChange event. But in rare cases, you want to distinguish between these three states: Connected Logged into Dailymotion but not connected with your application * Not logged into Dailymotion at all.

The DM.Event.subscribe and DM.Event.unsubscribe functions are used to subscribe to these events. For example:

DM.Event.subscribe('auth.login', function(response)
{
  // do something with response
});

The response object returned to all these events is the same as the response from DM.getLoginStatus, DM.login or DM.logout. This response object contains:

PropertyProperty description
statusThe status of the user. One of connected, notConnected or unknown.
sessionThe session object.

Parameters

NameTypeDescription
cbFunctionThe callback function to handle the response.

DM.getSession()

Synchronous accessor for the current Session. The synchronous nature of this method is what sets it apart from the other login methods. It is similar in nature to DM.getLoginStatus(), but it just returns the session. Many parts of your application already assume the user is connected with your application. In such cases, you may want to avoid the overhead of making asynchronous calls.

Note: You should never use this method at page load time. Generally, it is safer to use DM.getLoginStatus() if you are unsure.

Returns: The current session if available, null otherwise.

DM.login()

Once you have determined the user's status, you may need to prompt the user to login. It is best to delay this action to reduce user friction when they first arrive at your site. You can then prompt and show them the “Connect with Dailymotion” button bound to an event handler which does the following:

DM.login(function(response)
{
  if (response.session)
  {
    // user successfully logged in
  }
  else
  {
    // user cancelled login
  }
});

You should only call this on a user event as it opens a popup. Most browsers block popups, unless they were initiated from a user event, such as a click on a button or a link.

Depending on your application's needs, you may need additional permissions from the user. A large number of calls do not require any additional permissions, so you should first make sure you need a permission. This is a good idea because this step potentially adds friction to the user's process. Another point to remember is that this call can be made even after the user has first connected. So you may want to delay asking for permissions until as late as possible:

DM.login(function(response)
{
  if (response.session)
  {
    if (response.session.scope)
    {
      // user is logged in and granted some permissions.
      // perms is a comma separated list of granted permissions
    }
    else
    {
      // user is logged in, but did not grant any permissions
    }
  }
  else
  {
    // user is not logged in
  }
}, {scope: 'read write'});

Parameters

NameTypeDescription
cbFunctionThe callback function to handle the response
optsObject(optional) Options to modify login behavior. scope: Space separated list of permissions.

DM.logout()

Logout the user in the background.

Just like logging in is tied to dailymotion.com, so is logging out – and this call logs the user out of both Dailymotion and your site. This is a simple call:

DM.logout(function(response)
{
  // user is now logged out
});

Note: You can only log out a user that is connected to your site.

Parameters

NameTypeDescription
cbFunctionThe callback function to handle the response.

DM.Event.subscribe

Subscribe to a given event name, invoking your callback function whenever the event is fired.

For example, suppose you want to get notified whenever the session changes:

DM.Event.subscribe('auth.sessionChange', function(response)
{
  // do something with response.session
});

Parameters

NameTypeDescription
nameStringName of the event.
cbFunctionThe handler function.

DM.Event.unsubscribe

Removes subscribers, inverse of DM.Event.subscribe.

Removing a subscriber is basically the same as adding one. You need to pass the same event name and function to unsubscribe that you passed into subscribe. If we use a similar example to DM.Event.subscribe, we get:

var onSessionChange = function(response)
{
  // do something with response.session
};
DM.Event.subscribe('auth.sessionChange', onSessionChange);

// sometime later in your code you dont want to get notified anymore
DM.Event.unsubscribe('auth.sessionChange', onSessionChange);

Parameters

NameTypeDescription
nameStringName of the event.
cbFunctionThe handler function.

DM.player()

Creates a player.

<script src='https://api.dmcdn.net/all.js'></script>
<div id='player'></div>div>
<script>
  var player = DM.player(document.getElementById('player'), {
    video: 'xwr14q',
    width: '100%',
    height: '100%',
    params: {
      autoplay: true,
      mute: true
    }
  });
</script>
DM.player() parameters
NameTypeDescription
elementDOM element or StringA reference to a DOM element or an id of the HTML element where the API will insert the <iframe> tag containing the player.
optionsObjectA JavaScript object containing the following properties:
options.videoStringThe Dailymotion video ID that identifies the video that the player will load.
options.widthStringThe width of the video player. The default value is 480.
options.heightStringThe height of the video player. The default value is 270.
options.paramsObjectThe object's properties identify player parameters that can be used to customize the player. Please refer to the Player parameters documentation for more details.
options.eventsObjectThe object's properties identify the events that the API fires and the functions (event listeners) that the API will call when those events occur.

PHP SDK

The PHP SDK is available on GitHub.
Feel free to report any issue or send pull requests there.

Usage

The PHP SDK implements the Dailymotion Advanced API. For a list of all available methods, see the complete API reference. To call a method using the PHP SDK, use the get, post or delete methods as follow:

$api = new Dailymotion();
$result = $api->get(
    '/videos',
    array('fields' => array('id', 'title', 'owner'))
);

The $result variable contains the result of the method (as described in the Data API overview) as an array.

Authentication

The Dailymotion API requires OAuth 2.0 authentication in order to be used.

Contrary to most OAuth SDKs, the Dailymotion PHP SDK implements lazy authentication, which means that no authentication request is sent as long as no data is requested from the API. At which point, two requests are sent back-to-back during the first request for information, one to authenticate and one to fetch the data. Keep this in mind while working through the rest of the documentation.

Please note that the Dailymotion PHP SDK also takes care of abstracting the entire OAuth flow, from retrieving, storing and using access tokens, to using refresh tokens to gather new access tokens automatically. You shouldn't have to deal with access tokens manually but if you have to, at the programming-level, the SDK exposes this information with the Dailymotion::getSession() and Dailymotion::setSession() methods. At the Oauth-level, a session is the response sent by the OAuth server when successfully authenticated, for example:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 36000,
    "refresh_token": "<REFRESH_TOKEN>",
    "scope": "<SCOPE1 SCOPE2 SCOPE3>",
    "uid": "<USER_ID>"
}

Note: One of the problems with OAuth 2.0 is that the specification doesn't offer any mechanism to upgrade the scope of an existing session. To add new scopes to an already existing session, you first need to call the Dailymotion::logout() method and start a new session with your new list of scopes.

If you really wish to manually retrieve an access token without waiting for the SDK to take care of it when sending the first query, you can use the Dailymotion::getAccessToken() method. It will try to authenticate and return you the corresponding access token or an exception. Please note that this isn't the recommended way to proceed. See the Overloading the SDK section for more information about handling access tokens.

This library implements three OAuth 2.0 granting methods for different kind of usages.

Authorization Grant Type

This grant type is the one you should use in most cases. With this grant type you redirect the user to an authorization page on Dailymotion and your application is called back once the end-user authorized your API key to access Dailymotion on his/her behalf.

Here is a usage example:

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Tell the SDK what kind of authentication you'd like to use.
// Because the SDK works with lazy authentication, no request is performed at this point.
$api->setGrantType(Dailymotion::GRANT_TYPE_AUTHORIZATION, $apiKey, $apiSecret);

try
{
    // The following line will actually try to authenticate before making the API call.
    // * The SDK takes care of retrying if the access token has expired.
    // * The SDK takes care of storing the access token itself using its `readSession()`
    //   and `storeSession()` methods that are made to be overridden in an extension
    //   of the class if you want a different storage than provided by default.
    $result = $api->get(
        '/me/videos',
        array('fields' => array('id', 'title', 'owner')
    );
}
catch (DailymotionAuthRequiredException $e)
{
    // If the SDK doesn't have any access token stored in memory, it tries to
    // redirect the user to the Dailymotion authorization page for authentication.
    return header('Location: ' . $api->getAuthorizationUrl());
}
catch (DailymotionAuthRefusedException $e)
{
    // Handle the situation when the user refused to authorize and came back here.
    // <YOUR CODE>
}

Password Grant Type

If your PHP application isn't a web application and cannot redirect the user to the Dailymotion authorization page, the password grant type can be used instead of the authorization one. With this grant type you have the responsibility to ask the user for its credentials. Make sure your API secret remains secret though, do not use this kind of authentication for any service that is running on the client if you do not want your API secret to be publicly exposed.

Here is a usage example:

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Ask the end-user for his/her Dailymotion credentials in a way or another.
if (empty($_POST['username']) || empty($_POST['password']))
{
    // <YOUR CODE>
}
else
{
    // Tell the SDK what kind of authentication you'd like to use. Because the SDK
    // works with lazy authentication, no request is performed at this point.
    $api->setGrantType(
        Dailymotion::GRANT_TYPE_PASSWORD,
        $apiKey,
        $apiSecret,
        array(), // OAuth 2.0 scopes that you'd like to be granted by the end-user
        array(
            'username' => $_POST['username'], // don't forget to sanitize this,
            'password' => $_POST['password'], // never use POST variables this way
        )
    );
    // The following line will actually try to authenticate before making the API call.
    // * The SDK takes care of retrying if the access token has expired.
    // * The SDK takes care of storing the access token itself using its `readSession()`
    //   and `storeSession()` methods that are made to be overridden in an extension
    //   of the class if you want a different storage than provided by default.
    $result = $api->get(
        '/me/videos',
        array('fields' => array('id', 'title', 'owner'))
    );
}

Client Credentials Grant Type

If you don't need to access the Dailymotion API on behalf of someone else because, for instance, you only plan to access public data, you can use the client credentials grant type. With this grant type, you will only have access to public data or data protected by a specific scope and/or role. It's the equivalent of being unlogged but having the permission (granted by Dailymotion as part of a partners program or similar) to access sensitive data.

Here is a usage example:

// Instanciate the PHP SDK.
$api = new Dailymotion();

// Tell the SDK what kind of authentication you'd like to use.
// Because the SDK works with lazy authentication, no request is performed at this point.
$api->setGrantType(Dailymotion::GRANT_TYPE_CLIENT_CREDENTIALS, $apiKey, $apiSecret);

// This will actually try to authenticate before making the API call.
// * The SDK takes care of retrying if the access token has expired.
// * The SDK takes care of storing the access token itself using its `readSession()`
//   and `storeSession()` methods that are made to be overridden in an extension
//   of the class if you want a different storage than provided by default.
$result = $api->get(
    '/videos',
    array('fields' => array('id', 'title', 'owner'))
);

There is no authenticated user in this scenario, thus you won't be able to access the /me endpoint.

Upload File

Some methods like POST /me/videos requires a URL to a file. To create those URLs, Dailymotion offers a temporary upload service through the Dailymotion::uploadFile() method which can be used like this:

// Temporarily upload a file on Dailymotion' servers
// This does not create a video, it only offers you a public URL to work with.
$url = $api->uploadFile($filePath);
var_dump($url);

You can then use this $url result as an argument to methods requiring such a parameter. For instance to create a video:

// More fields may be mandatory in order to create a video.
// Please refer to the complete API reference for a list of all the required data.
$result = $api->post(
    '/me/videos',
    array('url' => $url, 'title' => $videoTitle)
);

You can also retrieve a progress URL like this:

$progressUrl = null;
$url = $api->uploadFile($filePath, null, $progressUrl);
var_dump($progressUrl);

Hitting this URL after the upload has started allows you to monitor the upload progress.

Overloading the SDK

As stated in the Authentication section above, the PHP SDK takes care of abstracting the entire OAuth flow, from retrieving, storing and using access tokens, to using refresh tokens to gather new access tokens automatically.

Overloading the SDK with your own implementation allows you to adapt the SDK behaviour to your needs. The most common usage is to overload both Dailymotion::storeSession() and Dailymotion::readSession() methods to change the default storage system (which uses cookies).

Here is a crude example of overloading the SDK to store sessions (access token + refresh token) on the file system instead of using cookies (for a command line program for example):

class DailymotionCli extends Dailymotion
{
    /**
     * Where to store the current application session.
     * @var string
     */
    protected static $sessionFile;

    /**
     * Define where to store the session on the file system.
     */
    public function __construct()
    {
        self::$sessionFile = __DIR__ . '/api-session.json';
    }
    /**
     * Overloading the default implementation with file system implementation.
     * `readSession` is used to restore the session from its storage medium.
     * @return array Restored session information.
     */
    protected function readSession()
    {
        $session = json_decode(file_get_contents(self::$sessionFile), true);
        return $session;
    }
    /**
     * Overloading the default implementation with file system implementation.
     * `storeSession` is used to store the session to its storage medium.
     *
     * @param array $session Session information to store.
     * @return DailymotionCli $this
     */
    protected function storeSession(array $session = array())
    {
        file_put_contents(self::$sessionFile, json_encode($session), LOCK_EX);
        return $this;
    }
}

Don't hesitate to extend the functionalities of the SDK and send us pull requests once you're done! And again, if you think that something's wrong, don't hesitate to report any issue.

Objective-C SDK

The iOS SDK is a thin wrapper around a UIWebView that allows to easily embed Dailymotion videos into your iOS application. Please check the source code and documentation on GitHub.

If you want to get started easily, we provide an example application that demonstrates the use of the API.

Python SDK

The Python SDK for using Dailymotion Data API is available on our GitHub.

Install

Install dailymotion module:

python setup.py install

Examples

Public api call

d = dailymotion.Dailymotion()
d.get('/videos')

Authenticated call

d = dailymotion.Dailymotion()
d.set_grant_type('password', api_key=API_KEY, api_secret=API_SECRET, scope=['userinfo'], info={'username': USERNAME, 'password': PASSWORD})
d.get('/me', {'fields' : 'id,fullname'})

Publish new video

d = dailymotion.Dailymotion()
d.set_grant_type('password', api_key=API_KEY, api_secret=API_SECRET, scope=['manage_videos'], info={'username': USERNAME, 'password': PASSWORD})
url = d.upload('./video.mp4')
d.post('/me/videos', {'url' : url, 'title' : 'MyTitle', 'published' : 'true', 'channel' : 'news'})

Tests

  1. Install Nose

    pip install nose
  2. Create a new file config.py

    CLIENT_ID = '[YOUR API KEY]'
    CLIENT_SECRET = '[YOUR API SECRET]'
    USERNAME = '[YOUR USERNAME]'
    PASSWORD = '[YOUR PASSWORD]'
    REDIRECT_URI = '[YOUR REDIRECT URI]'
    BASE_URL = 'https://api.dailymotion.com'
    OAUTH_AUTHORIZE_URL = 'https://www.dailymotion.com/oauth/authorize'
    OAUTH_TOKEN_URL = 'https://api.dailymotion.com/oauth/token'
  3. Run tests
    nosetests -v

Android SDK

The Android SDK is a thin wrapper around a WebView that allows to easily embed Dailymotion videos into your Android application. Please check the source code, documentation and sample app on GitHub.

More sample code is available on the dev branch of the Dailymotion Android SDK. Beware that it is still being developed and not considered stable. Backward compatibility may be broken in the future, so we wouldn't recommend it for real production use yet. Feel free to send pull requests and changes and tell us what you think, we welcome all suggestions!