Table of content

Android SDK Reference


Introduction

Our Android SDK allows you to easily embed videos on Android environments.

In this article, you’ll find the exhaustive SDK Reference to help you tailor your unique video experience for your Android apps and explore the available runtime Player parameters, methods, events and states.

Getting started

If you’re new to our Android 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 Android 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
defaultFullscreenOrientationOrientation.LandscapeSpecify which orientation should be used for fullscreen.

Possible values: LandscapeReverseLandscapePortrait or ReversePortrait
Sealed class

Methods

API commands can be called to programmatically create and control the Player. Check the dedicated guide to see how to use methods.

Initialization methods

NameInfo Example
Create Player To create the player object


Player ID is mandatory and can be created and managed either through the “Players” tab in the Dailymotion Studio or programmatically via the player REST API.
Dailymotion.createPlayer(
context: Context,
playerId: String,
videoId: String?,
playlistId: String?,
playerParameters: PlayerParameters,
playerListener: PlayerListener?,
videoListener: VideoListener?,
adListener: AdListener?,
playerSetupListener: PlayerSetupListener
)

Player methods

MethodInfoType
load​Content(video​Id: String?, playlist​Id:​ String?, start​Time:​ Long?)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?,
Long?
play() To play video playback
pause()To pause video playback
setFullScreen(fullscreen: Boolean, orientation: Orientation)To enable or disable fullscreen mode with fullscreen: true or false

If fullscreen: true, fullscreen orientation is by default orientation: Landscape

Other available values for orientation are LandscapeReverseLandscapePortrait or ReversePortrait

E.g. setFullScreen(fullscreen: true, orientation: ReverseLandscape)
Boolean
setSubtitles(wantedSubtitle: String)To activate a subtitles track to a specified language if available
String
setQuality(wantedQuality: String)To set the video’s quality to the specified quality
String
seek(seekTo:)To seek to the specified time in video playback in seconds
Double
SetMute()Mute the player
Boolean
setCustomConfig(customConfig:)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
Map<String, String>
setScaleMode(wantedScaleMode: String)To adjust the player view of the video screen

Possible values: fitfillfillLeft
fillRightfillTop
 & fillBottom
String
getState(callback: PlayerStateCallback)To retrieve the current state of the player
PlayerStateCallback
setLogLevel(LogLevel.String)To determine the level of details logs should return.
Available values are None Info Warning Error and All
String
destroy()Destroy the Player. Once the Player is destroyed, PlayerView will become useless.

Events

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

Player events

EventINFO

onPlayerError
Sent when the player triggers an error.
onPlayerStartSent 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.)
onPlayerEndSent when the playback of the content video, and eventual post-roll ad video is completed
onPlayerVideoChangeSent when a new video has been loaded in the player. (e.g. after calling loadContent({ video: 'xID' }), or at player start-up)
onPlayerVolumeChangeSent when the volume level or mute state changes
onPlayerPlaybackPermissionSent each time any playback request has failed or if the initial playback attempt has succeeded
onPlayerScaleModeChangeSent when the scale mode of the player changes after using setScaleMode()

Video events

EventInfo
onVideoSubtitlesChangeSent when the current subtitle changes

onVideoSubtitlesReady
Sent when subtitles are available

onVideoDurationChange
Sent when the duration property of the video becomes available or changes after a new video load
onVideoEndSent when the player completes playback of the content video
onVideoPauseSent when the video playback has paused
onVideoPlaySent when the playback state of the content video is no longer paused, as a result of the play method or the autoplay attribute
onVideoPlayingSent when the content video starts playing, after the play or waiting event
onVideoProgressSent when the browser is fetching the media data

onVideoQualitiesReady
Sent when video qualities are available
onVideoQualityChangeSent when the video quality changes
onVideoSeekEndSent when the player has completed a seeking operation
onVideoSeekStartSent when the player starts to seek to another position in the video timeline
onVideoStartSent when the player begins playback of the content video
onVideoTimeChangeSent when the playback position changes
onVideoBufferingSent when the player has to temporarily stop video playback for further buffering of content

Ad events

EventInfo
onAdCompanionsReadySent 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
onAdDurationChangeSent when the duration property of the video advertisement becomes available or changes after a new video load
onAdEndSent when the player completes playback of an ad
onAdPauseSent when the player pauses an ad
onAdPlaySent when the ad playback starts or continues after being in a paused state
onAdstartSent when the player begins playback of an ad video
onAdTimeChangeSent when the playback position of an ad changes
onAdImpressionSent when the first ad frame is displayed
onAdLoadedSent 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
onAdClickSent when a user clicks on a video ad

State

class PlayerState(

    // The description of the ad
    var adDescription: String? = null,

    // The advertiser name
    var adAdvertiserName: String? = null,

    /// The universal ad id node from the VAST or the ad id of the creative node from the VAST
    var adCreativeAdId: String? = null,

    // The id of the creative node from the VAST
    var adCreativeId: String? = null,

    // The reason why the last ad ended
    var adEndedReason: String? = null,

    // Contains information about the last error that occurred with the ad
    var adError: String? = null,

    // The id of the ad
    var adId: String? = null,

    // If an ad resource is running
    var adIsPlaying: Boolean? = null,

    // If the ad can be skipped by the user at this moment
    var adIsSkippable: Boolean? = null,

    // The position of the ad in the video
    var adPosition: String? = null,

    // The remaining time before the ad can be skipped or -1 if no ad is running
    var adSkipOffset: Long? = null,

    // The title of the ad
    var adTitle: String? = null,

    // The player current aspect ratio
    var playerAspectRatio: String? = null,

    // If the player is ready to play
    var playerIsCriticalPathReady: Boolean? = null,

    // If the player is allowed to play, depending on the browser permissions
    var playerIsPlaybackAllowed: Boolean? = null,

    // The reason why the playback has been allowed or not
    var playerPlaybackPermissionReason: String? = null,

    // The current mode where the player is displayed
    var playerPresentationMode: String? = null,

    // The player’s current scale mode
    var playerScaleMode: String? = null,

    // If the video is created for Children
    var videoIsCreatedForKids: Boolean? = null,

    // If the player controls are enabled
    var playerAreControlsEnabled: Boolean? = null,

    // If the player is muted
    var playerIsMuted: Boolean? = null,

    // If the player is currently playing video or ad content
    var playerIsPlaying: Boolean? = null,

    // If the player is loading the media resource
    var playerIsBuffering: Boolean? = null,

    // The current playback speed
    var playerPlaybackSpeed: Long? = null,

    // If the next and previous controls in the PiP are enabled
    var playerIsNavigationEnabled: Boolean? = null,

    // If the player is in replay screen
    var playerIsReplayScreen: Boolean? = null,

    // If the video required a password to be read
    var videoIsPasswordRequired: Boolean? = null,

    // If the player is in start screen
    var playerIsStartScreen: Boolean? = null,

    // If the player has the alert dialog displayed
    var playerIsAlertDialogDisplayed: Boolean? = null,

    // The id of the video previous video which was played
    var playerPrevVideo: String? = null,

    // The id of the video next video in the queue
    var playerNextVideo: String? = null,

    // The id of the owner of the video
    var videoOwnerId: String? = null,

    // The user name of the owner of the video
    var videoOwnerUsername: String? = null,

    // The screen name of the owner of the video
    var videoOwnerScreenName: String? = null,

    // The video qualities that are available
    var videoQualitiesList: List<String>? = null,

    // The quality value of the video loaded
    var videoQuality: String? = null,

    // The language codes of the subtitle tracks which are available for the current media resource
    var videoSubtitlesList: List<String>? = null,

    // The language code of the subtitle track that is currently enabled
    var videoSubtitles: String? = null,

    // The unique Id of the video
    var videoId: String? = null,

    // The title of the video loaded
    var videoTitle: String? = null,

    // The timestamp that corresponds to the creation of the video
    var videoCreatedTime: Double? = null,

    // The current volume level. The volume and mute params operate separately, therefore, you could have a player with full volume, but also muted
    var playerVolume: Double? = null,

    // The current playback position of an ad in seconds
    var adTime: Double? = null,

    // The duration time of the ad resource in seconds
    var adDuration: Double? = null,

    // The current playback position of the video in seconds
    var videoTime: Double? = null,

    // The duration time of the video resource in seconds
    var videoDuration: Double? = null,
	
    var playerError: Error? = null,
	
    var adCompanion: AdCompanion? = null
	
) : PlayerEvent(...) {


    class Error(
        val title: String? = null,
        val message: String? = null
    )

    class AdCompanion(
        val id: String? = null,
        val adId: String? = null,
        val sequence: String? = null,
        val apiFramework: String? = null,
        val type: String? = null,
        val adCompanionRequired: Boolean? = null,
    )
}

Check the guide to see how to retrieve a Player state.


Changelog

Version 1.0.9

Date: 2024-02-14

  • Fix for Player initialization issue
  • Set targetSdk to 34

Version 1.0.8

Date: 2023-11-07

  • Fix for default fullscreen landscape orientation issue

Version 1.0.7

Date: 2023-10-19

  • New public API method setFullscreen() for PlayerView
  • New public API method destroy() for PlayerView
  • Added gradient below IMA Native controls

Version 1.0.6

Date: 2023-08-31

  • Fix on R8 configuration

Version 1.0.5

Date: 2023-08-30

  • Fix for Player loading issue

Version 1.0.4

Date: 2023-08-08


Version 1.0.3

Date: 2023-07-21

  • Fix on R8 configuration

Version 1.0.2

Date: 2023-07-21

  • Fix for IMA and DM Player muted state issue

Version 1.0.1

Date: 2023-07-18

  • Fix for Player loading issue – playerSetupFailed issue

Version 1.0.0

Date: 2023-06-26

Initial release