Table of content

iOS SDK (Legacy)
Deprecated SDK:

This is the legacy iOS SDK documentation. If you’re getting started with your integration, please use the iOS SDK documentation available in our main Player documentation.

Date: March 2023

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 parameters list below 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] = [ "controls": "false", //to hide the Player control buttons "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 videoplaylistads_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.

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 Dailymotion Studio will override this paramString
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

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

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

The Player sends events when a specific Player property changes or becomes available. It is possible to add listeners to specific events: the exhaustive list of events is available below.

See 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 events
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.
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
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_resolutionSent 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
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_loadedSent when the player has loaded an advertisement in full or to the extent it can begin playback
ad_impressionSent when the first frame of the advertisement has been displayed
ad_bufferStartSent when the advertising playback has stopped due to buffering
ad_bufferFinishSent when the advertising playback has resumed due to the end of buffering
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.


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.


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: The SDK includes a solution to ensure the OM SDK can recognize device volume changes by default. The default solution can be overridden by changing the following parameter ‘allowAudioSessionActive’ to ‘false’ in the ‘DMPlayerViewController’ init method. Overriding this function will result in verification scripts underreporting videos as non-audible, which can negatively affect revenue.DMPlayerViewController(parameters: [:], allowAudioSessionActive: false)

It is recommended to update the Player state at all times if your app uses a variety of Player layout, 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

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