Mobile SDK

Mobile SDK is an API bundle of the following:

1. API Methods
2. Player Properties
3. VHX Integration
4. Customizing the Player
5. Advertising (IMA SDK)
6. Live Streaming
7. Chromecast and AirPlay
8. Subtitles
9. DRM
10. Analytics & Events

API Methods

Video Loading and Configuration

● configure()
Configures the video player on the screen. This must be called before
playing a video. See usage when embedding the player in the ​Embed the
Player​​ documentation.

● loadVideo()
Loads a new video from the given URL. See usage when embedding the
player in the ​Embed the Player​​ documentation.

● loadVHXVideo()
Loads a VHX video. Further information on ​VHX Integration​​.

● updateVideoFrame()
Updates the current frame of the video on the screen.

● removeVideoPlayer()
Removes the video player from the screen. There's an optional
"keepRemotePlayback" which, when set to true, will remove the video from
 the screen but keep it playing on the remote device in case it's connected
to AirPlay or Chromecast.

● disableVideoDisplay()
Removes the video display from the screen, but keeps audio playing (must
be called after the video has been loaded).

● enableVideoDisplay()
If disableVideoDisplay() was called at some point, re-enables the video
display.

Playback Methods

● startPlayback()
After loading video, this method should be called to actually start video
playback.

● resumePreviousRemotePlayback()
If there is a video currently playing on a remote device, calling this method
will display the controls on the current screen.

● play()
Resumes playback if video was paused or stopped.

● pause()
Pauses video playback if it's playing.

● stop()
Stops video playback. It resets current timecode to 0.

● seekToTime()
Seeks video to a specific timecode.

● hasStartedPlayback()
Returns whether video playback has started.

● isFinished()
Returns whether video has finished, due to achieving its end, or if user has
stopped the playback.
 ● isLive()
Returns whether the video is a live one.

● isLocal()
Returns whether the video is playing on the local device.

● isPlayingAds()
Returns whether ads are playing or not.

● isPlaying()
Returns whether the video is playing or not.

● isReadyToPlay()
Checks if player is ready to play the video that has been loaded previously.

● isReloading()
Returns whether the video is being reloaded.

● getCurrentTimecode()
Returns current timecode for the video.

● getVideoDuration()
Returns video duration.

External Playback Methods

● isCasting()
Returns whether video is being cast to Chromecast.

● setChromecastReceiverID()
Sets the id of the Chromecast receiver that will be used when playing on
Chromecast.

● isAirPlaying()
Returns whether video is being played via AirPlay.

● getAirPlayDeviceName()
Returns the name of the AirPlay device that is being used to play the video.
Subtitle Methods

● setAvailableSubtitles()
Sets the available subtitles. This method is only useful when using default
controls that display a default subtitles picker. User can build their own.

● loadSubtitle()
Loads a subtitle and starts displaying it.

● removeCurrentSubtitle()
Stops displaying current subtitle.

● showDefaultSubtitlesPicker()
Shows the default subtitles picker, with all available subtitles. If using a
custom URL video, user should call setAvailableSubtitles() first.

Quality Selector Methods

● hasQualitySelector()
Returns a bool value indicating if there are different qualities for a VHX
video, this is especially useful when working with custom controls, as it
will allow the user to show or hide a quality selector button.

● showQualitySelector()
Shows the default quality picker, with all available qualities. This will only
work if hasQualitySelector() returns true.

Player Controls Methods

● addControlsChildViewController()
This will add a child view controller to the player controls (and its view as a
subview), allowing the user to extend the default controls functionality with
an additional element. The user must define where the view will be
anchored (top, bottom, leading, or trailing) and optionally its width and
height.

● addControlsSubview()
Similar as above, but this will add a view only, with no associated view
controller. It's not necessary to call this method if
 ● addControlsChildViewController()
has already been called.

● removeControlsChildViewController()
Removes the specified view controller (and its view) from the player
controls.

● removeControlsSubview()
Similar as above, but for removing a view.

● removeAllControlsSubviews()
Removes all custom views that have been added to the player controls.

Delegate Methods

● videoPlayerAirPlayDidChangeStatus()
Called when device connects / disconnects from AirPlay. The following
status are possible: VimeoAirPlayConnected and
VimeoAirPlayDisconnected.

● videoPlayerChromecastDidChangeStatus()
Called when status for Chromecast has changed. The following status are
possible:VimeoCastUnavailable, VimeoCastAvailable,
VimeoCastConnecting and VimeoCastConnected. Notice that when device
is disconnected from Chromecast, SDK will call
videoPlayerChromecastDidChangeStatus() with either
VimeoCastUnavailable or VimeoCastAvailable.

● videoPlayerDidStart()
Called when the video has started playing.

● videoPlayerDidPause()
Called when the video has been paused.

● videoPlayerDidResume()
Called when the video has resumed playing.

● videoPlayerDidFinish()
Called when video playback has finished, due to reaching the end or when
a user has manually stopped the video.

● videoPlayerDidLoad()
Called when the video has been loaded by the player. At this point at least
 the first frame of the video is ready to be shown on-screen.

● videoPlayerDidStartBuffering()
Called when the player starts buffering.

● videoPlayerDidFinishBuffering()
Called when the player finishes buffering.

● videoPlayerDidSeek()
Called when the player has finished seeking. The call contains a Float value
indicating the new timecode that the player was seeked to.

● videoPlayerDidFail()
Called when the player has encountered an error. It will contains an object
"Error" with relevant details.

● videoPlayerDidProgress()
Called every second when video is playing, updating current progress.

● videoPlayerDidEnterFullscreen()
Called whenever the player goes to full screen mode. It includes the full
screen UIView as a parameter.

● videoPlayerDidExitFullscreen()
Called whenever the player leaves full screen mode.

● videoPlayerHasNowPlayingInfoDictionaryUpdate()
Indicates that a new NPI dictionary is ready to be set.

● videoPlayerLiveVideoIsReadyToPlay()
When playing a live video, the loadVHXVideo() will return success even if
video hasn't started yet. This delegate method is called once the live has
actually started playing.

● videoPlayerWillExitFullscreen()
Called to indicate that the video player will leave full screen mode.

● videoPlayerDidChangeSubtitleSelection()
Called when the user changes the subtitle selection. It includes the subtitle
as a parameter (nil if the user removed the previously selected subtitle.)
● videoPlayerWillHideControls()
Called every time the player controls are hidden. It includes an "animated"
parameter that indicates if there will be an animation or not.
 ● videoPlayerWillShowControls()
Called every time the player controls are shown. It includes an "animated"
parameter that indicates if there will be an animation or not.

● videoPlayerControlsWillStartAnimatingSpinner()
Called every time the default player controls spinner will start animating. It
includes the spinner as a parameter.

● videoPlayerControlsWillStopAnimatingSpinner()
Called every time the default player controls spinner will stop animating. It
includes the spinner as a parameter.

● videoPlayerDidSendAnalyticsEvent()
Called every time an analytics event is sent to VHX. It includes an
"analyticsEventDict" parameter containing the information that is sent to
VHX.

● videoPlayerAdDidStart()
Called when an ad has started playing.

● videoPlayerAdDidFinish()
Called when ad has finished playing.

● videoPlayerAdDidFail()
Called when an ad failed to play. It contains an object "Error" with relevant
details.

● videoPlayerAdDidSkip()
Called when user has manually skipped the ad.

Ad Source Methods

● videoPlayerAdVideoDisplay()
This method returns an instance of IMAAVPlayerVideoDisplay which will be
used to display ads, in case the user decides to use a custom IMA Ads
framework. It includes 2 parameters: an AVPlayer instance and an
IMAAdDisplayContainer instance, which can be used in the
IMAAVPlayerVideoDisplay initialization if so required.
Player Properties

● adDisplaySource
Property to indicate the instance that will receive the ad display source call.
This will be used if the user wants to integrate the SDK with a custom Ads
SDK. Check the ​Ad Source Methods​​ documentation for an explanation of
the ad display source method.

● analyticsVersion
Optional property that allows a custom version to be sent for video
analytics events.

● chromecastInformation
This property allows user customization of the Chromecast receiver, with
the following optional initialization values: thumbnail, videoTitle,
videoDescription and playerProgressHexColor (a string containing the
hexadecimal color, starting with #. Example: #B32D2F).

● controlsSliderTintColor
This property defines a custom color for the slider shown in the player
controls.

● currentSubtitle
This property returns the current subtitle being displayed by the player or
nil if none is currently selected.

● customAdsOverlayOrigin
Set this property to display the default ads overlay with a custom origin
point.
defaultControlsAnimationTime
The duration of the animation for showing and hiding the default player
controls.
● Delegate
Property to indicate the instance that will receive delegate calls. Check the
API Methods​​ documentation for a list of delegate methods.

● fullscreenOnly
If this property is set to true, the player will force full screen once the
playback starts. Please note that if you're using custom controls you need
to implement the videoPlayerDidEnterFullscreen delegate method and your
controls as a subview of the fullScreenView that is sent as a parameter.

● isAirPlayMirroring (readonly)
Indicates if the device is currently mirroring.

● isAnimatingFullscreen (readonly)
Indicates if the player is currently animating a fullscreen display.

● isAnimatingLoadingSpinner (readonly)
Indicates if a spinner is currently being animated to indicate that the player
is loading.

● isFullscreen (readonly)
Indicates if the player is currently fullscreen or not.

● isPendingLiveVideo (readonly)
Indicates if a live video has been loaded and is currently waiting for it to
start.
● isSeeking (readonly)
Indicates if the player is currently seeking.

● isShowingDefaultControls (readonly)
Indicates if the default player controls are currently being displayed.

● loadingThumbnail
An optional UIImage that can be displayed while the video is loading.
● maxInitialVHXLiveVideoLoadDelay
When playing a live VHX video, you can specify a maximum time to wait for
the video to start streaming. If no response is received after the time
passes, the SDK will try to reload the video.

● muxInformation
This struct contains a muxPropertyKey property that can be set with the
key to use for optional ​Mux​​ integration.

● playerVersion (readonly)
Returns the current player version.

● seekingToTime (readonly)
Returns the timecode that the player is currently seeking to.

● shouldAllowDoubleTapFullscreen
When set to true, the user will be able to double tap on full screen to
change the video gravity style. Which will cause it to zoom in or out if its
aspect ratio does not match the device's aspect ratio.
shouldAllowLandscapeOnlyFullscreen
When set to true, the full screen player will only show on landscape.
Important: make sure that the UISupportedInterfaceOrientations key of
your Info.plist file includes landscape support if you wish to enable this
property, otherwise the player will crash when attempting to go to full
screen.

● shouldAnimateFullscreenDisplay
When set to true, there will be a fade animation when entering fullscreen.

● shouldHideAirPlay
When set to true, will hide the AirPlay picker button from the default player
controls.

● shouldHideChromecast
When set to true, will hide the Chromecast picker button from the default
 player controls.

● shouldHideDefaultControlsOnPlaybackFinish
When set to true, the player controls will be hidden after the video playback
finishes. If the play() method is called at some point to restart playback, the
controls will be shown again.

● canHideDefaultPlayerControls
When set to false, the default player controls will remain on-screen
indefinitely.

● shouldHideDefaultPlayerControls
When set to true, the default player controls will not be shown.

● shouldHideQualitySelector
When set to true, will hide the quality selector button from the default
player controls.

● shouldLoop
When set to true, the video will loop.

● shouldRemovePlayerOnViewDisappearance
When set to false, the video player will NOT be automatically removed
when leaving the screen in which it's currently embedded. In this case, the
user will need to call removeVideoPlayer: when leaving the screen to
ensure that the playback won't keep going on the background.

● shouldSendVHXAnalytics
Indicates if the SDK should be sending video events to VHX Analytics. The
default value of this variable is true.

● shouldToggleFullscreenOnDeviceRotation
When set to true, this will toggle full screen state by rotating the device.
For this to work, the fullscreenOnly property must be false and
shouldAllowLandscapeOnlyFullscreen must be true. This is because
there's no toggle functionality for the full screen-only video and the full
screen exit will occur when the device is rotated to a portrait position, so if
the full screen portrait is allowed there's no point in toggling in that case.
 ● shouldUseBottomAnchoredDurationSlider
When set to true, the default player controls will display the duration slider
anchored to the bottom of the video playback when not in fullscreen. This
property must be changed before video playback begins. Note that when
using this type of controls you might need to override the
preferredScreenEdgesDeferringSystemGestures property on your parent
view controller to ensure that the bottom anchored slider will be
responsive at the edges of the screen.

● platformID
This is a value that is sent as a parameter to VHX analytics.

● qaServer
The qa server address used to make API calls to VHX.

VHX Integration

In order to play VHX videos, user needs to fill a class called

VHXPlayerConfiguration, with the following information:
apiKey,customerID,useProductionServer. Or you can use user authorization
token, sending the accessToken and useProductionServer parameters. When
using apiKey, make sure you send a valid customerID, as VHX servers use this
information to track progress and to resume video playback properly. Notice
that progress will be resumed only if user has watched at least 1% of the
video, and hasn't reached 90% of it.

User can play any video associated to his VHX account, using method
loadVHXVideo(), sending the above VHXPlayerConfiguration as parameter and
the desired videoID.

By default, this method will fetch video playback information like the duration,
initial time, and URL from VHX. But if so desired, the user can also pass these
values as parameters on this call, which will override the values received from
VHX.

This loadVHXVideo() also has a callback parameter, with useful information for
the user about the loaded VHX Video. It has an object of VHXVideoInfo struct,
with the following information:
 ● videoName
● videoTitle
● commentsLink
● videoPage
● advertisingLink
● desc
● subtitles
● durationSeconds
● playStateTimecode
● thumbnailSmall
● thumbnailMedium
● thumbnailLarge
● thumbnailSource
● liveVideo
● liveStatus
● liveScheduledAt

Customizing the Player

In order to use custom controls for the video player, user needs to set the
property shouldHideDefaultPlayerControls to true.The user should then create a
view on top of the video player view. To do so, user needs to call configure()
before adding the custom controls view.

Example:

let​ videoPlayerController ​=​ VimeoVideoPlayerViewController.sharedInstance

videoPlayerController.​configure​(​withParentViewController​: ​self​, ​inView​:
self​.​view​, ​withFrame​: videoPlayerFrame)
videoPlayerController.shouldHideDefaultPlayerControls ​=​ ​true
self​.customControlsView ​=​ ​UIView​(​frame​: videoPlayerController.​view​.frame)
self​.​view​.​addSubview​(​self​.customControlsView)
 Inside customControlsView user should put all subviews to control video
playback, i.e. play/pause buttons, slider for seeking, etc. User should use API
Methods to control the player.

Please note: User is responsible for detecting the screen tap to show and hide
custom controls.

Advertising (IMA SDK)

The Vimeo Player SDK automatically fetches ad playback information when

playing a VHX Video (​​View Example​​). If the video is correctly configured, the SDK
will automatically load and play the ads, no additional action is required by the
user.

It is also possible to define a specific ads link to be played, or send specific user
ad parameters for each video that is loaded into the SDK.

Both the loadVideo and the loadVHXVideo methods have optional parameters
adsLink (which is used to set a specific link of ads to be played) and
userAdParams (a Dictionary with key-value pairs that will be added or replaced
on the ads link, allowing customization of the ad url).

Live Streaming

To play live videos, simply load a live video URL and the SDK should
automatically detect it and treat it as such. In this case, the seek functionality will
be disabled, but the user will still be able to play and pause the video.

Chromecast and AirPlay

The VimeoPlayer SDK implements Chromecast and AirPlay on its default

controls, so user is ready to use it right from installation. If user wants to build
 his own controls, he needs to add Apple's MPVolumeView on his controls and
one button to display chromecast options. User has access to a
VimeoChromecastDeviceManager instance, that has the following public
methods: numberOfDevicesAvailable(), devicesAvailable(), connectToDevice(),
disconnectFromChromecast(), getConnectedDeviceName() and
showDevicePicker(). On Chromecast, the user can customize its appearance on
the receiver, with some properties defined on the public
VimeoChromecastInformationclass.

The SDK also includes some delegate methods to receive notifications about
Chromecast and AirPlay changes. See ​Delegate methods​​ on API specification.

Subtitles

VimeoVideoPlayer is able to display subtitles for VHX videos or any custom

video. When using VHX Videos, it will be seamless for the user, as it will
automatically detect subtitles and set the subtitles array for the video player.

DRM

DRM supports DRM via FairPlay Streaming (FPS), which we will use for all Apple
devices that implement DRM.

Analytics and Events

The SDK is currently integrated with the VHX back end in order to track analytics
events. When playing any video through the SDK, the appropriate events will
automatically be sent, with no additional input needed.
List of Tracked Events

● Firstplay
Fired when the playback begins for a video.

● Play
Video resumes playback.

● Pause
Video playback pauses.

● Timeupdate
Fired every 10 seconds to indicate progress of the video.

● Seeked
Video has been seeked.

● Error
An error occurred during playback.
● Waiting
A buffer has begun during playback.

● Ended
Playback finished.