iOS SDK Reference
Introduction
Our iOS SDK allows you to easily embed videos in the iOS environment.
In this article, you’ll find the exhaustive SDK Reference to help you tailor your unique video experience for your iOS apps and explore the available runtime Player parameters, methods, events and states.
Getting started
If you’re new to our iOS SDK, we recommend checking our Getting started guide to help you set up the SDK, get familiar with the embed basics and see how to use each element of the SDK.
Runtime Player parameters
While the main Player experience is controlled using the settings defined in your Player configuration, additional runtime customization is achievable using client-side parameters.
Check the dedicated guide to see how to add runtime Player parameters with the iOS SDK.
Parameter | Default | Description | Type |
---|---|---|---|
video | undefined | The ID of the video to load | String |
playlist | undefined | The ID of the playlist to load | String |
customConfig | undefined | Define advertising configuration by passing in keys and values. More details E.g. customConfig[key]=values | Object |
scaleMode | fit | To adjust the player’s video focus Possible values: fit , fill , fillLeft , fillRight , fillTop & fillBottom | Enum |
mute | false | Whether to mute the video or not. To note, enabling mute may impact monetization. The Player provides smart mute behavior, it tries to automatically start the video playback with sound. If this isn’t possible due to browser prevention, there is a fallback mechanism and the Player reattempts to play the video but with the sound set to mute. Possible values: true or false | Boolean |
startTime | 0 | Specify the time (in seconds) from which the video should start playing | Number |
loop | false | To set the video to loop Learn more Possible values: true or false | Boolean |
defaultFullscreenOrientation | landscapeLeft | Default player orientation when user interacts with fullscreen button Possible values: landscapeRight , landscapeLeft , portrait or upsidedown | Enum |
Methods
Initialization methods
Name | Info | Example |
Create Player | To create the player object DMPlayerView , the object will be returned in the completion closure given as a parameter. Player ID is mandatory and can be created and managed on Dailymotion Studio | Dailymotion.createPlayer(playerId: "PLAYERID", videoId: "VIDEOID", playerParameters: DMPlayerParameters() , playerDelegate: self) |
Player methods
When the Player is loaded you can use the below methods to take full control of the player and interact with it programmatically.
Method | Info | Type |
loadContent(videoId:playlistId:startTime:) | To load a video or a playlist. You can play a specific video followed by a playlist by specifying both the video and playlist IDs Note that the loaded content playback is based on the autostart configuration defined in the PlayerID settings | String?, |
play() | To play video playback | – |
pause() | To pause video playback | – |
setFullscreen() | To enable or disable fullscreen mode with fullscreen: true, or false If fullscreen: true , fullscreen orientation is by default orientation: .landscapeLeft Other available values for orientation are .landscapeRight or .portrait E.g. setFullscreen(fullscreen: true, orientation: .landscapeRight) | Boolean |
setSubtitles(code:) | To activate a subtitles track to a specified language if available | String |
setQuality(level:) | To set the video’s quality to the specified quality | String |
seek(to:) | To seek to the specified time in video playback in seconds | TimeInterval |
setMute(mute:) | To set the mute mode of the player | Bool |
setCustomConfig(config:) | 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 Learn more | Dictionary [String:String] |
setPlaybackSpeed(speed: Double) | To modify the playback speed, if the value passed does not match one from the list, the playback speed is rounded to the superior one. The playback speed is kept across videos. Possible values: [0.25, 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2] | Double |
setScaleMode(config:) | To adjust the player view of the video screen Possible values: fit , fill , fillLeft , fillRight , fillTop & fillBottom | ScaleMode |
getState(completion:) | To retrieve the current state of the player | StateCompletionHandler |
try await getState() | To retrieve the current state of the player | |
updateParams(params:) | To change the following player config values at runtime scaleMode , mute , volume , enableControls & customConfig | DMPlayerParameters |
Events
Check the dedicated guide to learn how to listen to events.
Player events – DMPlayerDelegate
Event | INFO |
player(_:openUrl:) | Informs the delegate that has to open a URL in a browser result as a user action |
player(_:didFailWithError:) | Sent when the player triggers an error. |
playerDidStart(_:) | Sent 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.) |
playerDidEnd(_:) | Sent when the playback of the content video, and eventual post-roll ad video is completed |
player(_:didChangeVideo:) | Sent when a new video has been loaded in the player. (e.g. after calling loadContent({ video: 'xID' }) , or at player start-up) |
player(_:didChangeVolume:_:) | Sent when the volume level or mute state changes |
player(_:didChangePlaybackSpeed speed: Double:) | Sent when the playback speed changes |
player(_:didReceivePlaybackPermission:) | Sent each time any playback request has failed or if the initial playback attempt has succeeded |
player(_:didChangePresentationMode:) | Sent 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(_:didChangeScaleMode:) | Sent when the scale mode of the player changes after using setScaleMode() |
playerDidCriticalPathReady(_:) | Sent 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) |
Video events – DMVideoDelegate
Event | Info |
video(_:didChangeSubtitles:) | Sent when the current subtitle changes |
video(_:didReceiveSubtitlesList:) | Sent when subtitles are available |
video(_:didChangeDuration:) | Sent when the duration property of the video becomes available or changes after a new video load |
videoDidEnd(_:) | Sent when the player completes playback of the content video |
videoDidPause(_:) | Sent when the video playback has paused |
videoDidPlay(_:) | Sent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute |
videoIsPlaying(_:) | Sent when the content video starts playing, after the play or waiting event |
video(_:isInProgress:) | Sent when the browser is fetching the media data |
video(_:didReceiveQualitiesList:) | Sent when video qualities are available |
video(_:didChangeQuality:) | Sent when the video quality changes |
video(_:didSeekEnd:) | Sent when the player has completed a seeking operation |
video(_:didSeekStart:) | Sent when the player starts to seek to another position in the video timeline |
videoDidStart(_:) | Sent when the player begins playback of the content video |
video(_:didChangeTime:) | Sent when the playback position changes |
videoIsBuffering(_:) | Sent when the player has to temporarily stop video playback for further buffering of content |
Ad events – DMAdDelegate
Event | Info |
adDidReceiveCompanions(_:) | Sent 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(_:didStart:_:) and ad(_:didEnd:) |
ad(_:didChangeDuration:) | Sent when the duration property of the video advertisement becomes available or changes after a new video load |
ad(_:didEnd:) | Sent when the player completes playback of an ad |
adDidPause(_:) | Sent when the player pauses an ad |
adDidPlay(_:) | Sent when the ad playback starts or continues after being in a paused state |
ad(_:didStart:_:) | Sent when the player begins playback of an ad video |
ad(_:didChangeTime:) | Sent when the playback position of an ad changes |
adDidImpression(_:) | Sent when the first ad frame is displayed |
ad(_:adDidLoaded:) | Sent 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 |
adDidClick(_:) | Sent when a user clicks on a video ad |
ad(_:adDidReadyToFetch:) | Sent a few seconds before an request is made: – First preroll: 2 sec – Consecutive preroll: 4 sec – Midroll & postroll: 6 sec Important: Only sent when Player setting enable_wait_for_custom_config is true |
State
/// The ad companion's information
public var adCompanion: [DailymotionPlayerSDK.AdCompanion]?
/// The description of the ad
public var adDescription: String?
/// The advertiser name
public var adAdvertiserName: String?
/// The universal ad id node from the VAST or the ad id of the creative node from the VAST
public var adCreativeAdId: String?
/// The id of the creative node from the VAST
public var adCreativeId: String?
/// The reason why the last ad ended
public var adEndedReason: String?
/// Contains the infos about the last error that occurred with the ad
public var adError: String?
/// The id of the ad
public var adId: String?
/// If an ad resource is running
public var adIsPlaying: Bool?
/// If the ad can be skipped by the user at this moment
public var adIsSkippable: Bool?
/// The position of the ad in the video
public var adPosition: String?
/// The remaining time before the ad can be skipped or -1 if no ad is running
public var adSkipOffset: Double?
/// The title of the ad
public var adTitle: String?
/// The player current aspect ratio
public var playerAspectRatio: String?
/// If the player is ready to play
public var playerIsCriticalPathReady: Bool?
/// If the player is allowed to play, depending on the browser permissions
public var playerIsPlaybackAllowed: Bool?
/// The reason why the playback has been allowed or not
public var playerPlaybackPermissionReason: String?
/// The current mode where the player is displayed
public var playerPresentationMode: String?
/// The player’s current scale mode
public var playerScaleMode: String?
/// If the video is created for Children
public var videoIsCreatedForKids: Bool?
/// If the player controls are enabled
public var playerAreControlsEnabled: Bool?
/// The error shown in the Player
public var playerError: DailymotionPlayerSDK.PlayerError?
/// If the player is muted
public var playerIsMuted: Bool?
/// If the player does support the native PiP
public var playerIsPipNativeSupported: Bool?
/// If the player is currently playing video or ad content
public var playerIsPlaying: Bool?
/// If the player is loading the media resource
public var playerIsBuffering: Bool?
/// If the next and previous controls in the PiP are enabled
public var playerIsNavigationEnabled: Bool?
/// If the player is in replay screen
public var playerIsReplayScreen: Bool?
/// If the video required a password to be read
public var videoIsPasswordRequired: Bool?
/// If the player is in start screen
public var playerIsStartScreen: Bool?
/// If the player has the alert dialog displayed
public var playerIsAlertDialogDisplayed: Bool?
/// The id of the video previous video which was played
public var playerPrevVideo: String?
/// The id of the video next video in the queue
public var playerNextVideo: String?
/// The id of the owner of the video
public var videoOwnerId: String?
/// The user name of the owner of the video
public var videoOwnerUsername: String?
/// The screen name of the owner of the video
public var videoOwnerScreenname: String?
/// The video qualities that are available
public var videoQualitiesList: [String]?
/// The quality value of the video loaded
public var videoQuality: String?
/// The language codes of the subtitle tracks which are available for the current media resource
public var videoSubtitlesList: [String]?
/// The language code of the subtitle track that is currently enabled
public var videoSubtitles: String?
/// The unique Id of the video
public var videoId: String?
/// The title of the video loaded
public var videoTitle: String?
/// The timestamp that corresponds to the creation of the video
public var videoCreatedTime: Double?
/// The current volume level. The volume and mute params operate separately, therefore, you could have a player with full volume, but also muted
public var playerVolume: Double?
/// The current playback position of an ad in seconds
public var adTime: Double?
/// The duration time of the ad resource in seconds
public var adDuration: Double?
/// The current playback position of the video in seconds
public var videoTime: Double?
/// The duration time of the video resource in seconds
public var videoDuration: Double?
Check the guide to see how to retrieve a Player state.
Changelog
Version 1.4.0
Date: 2024-10-02
- iOS 18 support
Version 1.3.10
Date: 2024-09-12
- Added new Player method
setPlaybackSpeed
- Added new Player event
didChangePlaybackSpeed
Version 1.3.9
Date: 2024-09-04
- Integrated new OM SDK 1.5.0
Version 1.3.8
Date: 2024-07-30
- Added new
ad(_:adDidReadyToFetch:)
ad event
Version 1.3.7
Date: 2024-06-19
- Disable ad stack when Chromecast is running
- Make Chromecast integration optional
Version 1.3.6
Date: 2024-05-30
- Updated the privacy manifest (including tracking domains) in compliance with iOS 17 privacy requirements
Version 1.3.5
Date: 2024-05-10
- Removed Dailymotion branding on Chromecast receiver
Version 1.3.4
Date: 2024-05-08
- Updated full screen mode
Version 1.3.3
Date: 2024-04-16
- Hot Fix: Updated
loadContent()
command to correctly load the content at the given start time
Version 1.3.1
Date: 2024-02-22
- Hot fix: Added missing simulator Architecture to all Dailymotion SDKs
Version 1.3.0
Date: 2024-02-14
- This version contains Chromecast integration
Version 1.1.3
Date: 2024-01-12
- Fix for encoding issue for customConfig()
- Update IMA SDK to version 3.19.1
- Increase SDK min version to iOS 14 in order to support IMA 3.19.1
Version 1.1.2
Date: 2023-12-05
- Fix an issue with the SDK reporting a wrong version
Version 1.1.1
Date: 2023-11-03
- Fix for IMA ad mute button which wasn’t showing actual state
- Fix for ad event firing issue:
ad(_:didStart:_:)
Version 1.1.0
Date: 2023-11-01
- Signing DailymotionPlayerSDK and DailymotionAdvertisingServices
- Ability to disable Ads Controls using Player setting
enable_ads_controls
- Improved Out-of-the-box fullscreen transitions
- Added possibility to implement custom fullscreen experience
iOS SDK sample application
Date: 2023-10-17
Sample applications for our iOS SDK are now available.
More details here.
Version 1.0.9
Date: 2023-08-22
The latest version introduces internal tracking fixes plus exposing additional internal logs.
Version 1.0.7
Date: 2023-08-22
Fixes and optimizations:
- IMA events sync
- Extend setMute methods to the advertisement
- Optimization UI controls gradient
Version: 1.0.5
Date: 2023-07-06
Deprecation of:
setControls()
methodplayer(_:didChangeControls:)
eventplayerAreControlsEnabled
state
You can now enable/disable your playback and ad controls independently using one of the following methods:
- From your Player configurator use the Player controls and Ads controls toggles
- Programatically with
enable_playback_controls
andenable_ads_controls
Version: 1.0.4
Date: 2023-06-13
Manage different fullscreen orientation with setFullscreen()
method:
- Default param on Player creation
- Enhanced
setFullscreen()
, orientation can be programmatically set to.landscapeLeft .landscapeRight
or.portrait
Version: 1.0.3
Date: 2023-05-23
- Optimize to use native pip
- Fix to facilitate multiple ads params usage
- Removal of safe bar area on full screen
iOS SDK release
Date: 2023-03-23
After weeks of beta test, we’re now releasing our new iOS SDK!
The previous iOS SDK won’t be maintained anymore, and documentation has been removed from our official documentation.
We invite you to switch on our new iOS SDK to benefit from our latest features and optimizations.
Don’t hesitate to reach out to your Content Manager or our Support team if you need assistance.