Table of content

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.

ParameterDefaultDescriptionType
videoundefinedThe ID of the video to loadString
playlistundefinedThe ID of the playlist to loadString
customConfigundefinedDefine advertising configuration by passing in keys and values.
More details

E.g. customConfig[key]=values
Object
scaleModefitTo adjust the player’s video focus

Possible values: fitfillfillLeftfillRightfillTop & fillBottom
Enum
mutefalseWhether 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
startTime0Specify the time (in seconds) from which the video should start playingNumber
loopfalseTo set the video to loop
Learn more

Possible values: true or false
Boolean
defaultFullscreenOrientationlandscapeLeftDefault player orientation when user interacts with fullscreen button

Possible values: landscapeRightlandscapeLeftportrait or upsidedown
Enum

Methods

Initialization methods

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

MethodInfoType
load​Content(video​Id:​playlist​Id:​start​Time:​)
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?,
String?,
TimeInterval?
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]
setScaleMode(config:)To adjust the player view of the video screen

Possible values: fitfillfillLeft
fillRightfillTop
 & fillBottom
ScaleMode
enum
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 scaleModemutevolumeenableControls & customConfigDMPlayerParameters

Events

Check the dedicated guide to learn how to listen to events.

Player events – DMPlayerDelegate

EventINFO
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(_: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

EventInfo
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

EventInfo
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

State

/// The description of the ad
    public var adDescription: String?

    /// If the player does support the native PiP
    public var playerIsPipNativeSupported: Bool?

    /// 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?

    /// If the player is muted
    public var playerIsMuted: 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?

    public var playerError: DailymotionPlayerSDK.PlayerError?

    public var adCompanion: [DailymotionPlayerSDK.AdCompanion]?

Changelog

Version 1.3.0

Date: 2024-02-14


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() method
  • player(_:didChangeControls:) event
  • playerAreControlsEnabled 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 and enable_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.