iOS Migration Reference

Explore JW Player's new iOS SDK v4.

The following sections provide notes on how to migrate from iOS SDK v3 to iOS SDK 4.x.

Configuration API

In iOS SDK 3.x, the main player configuration object is called JWConfig.

// Create a JWConfig object with a single JWPlaylistItem
let config = JWConfig()
let playlistItem = JWPlaylistItem()
playlistItem.file = fileURL
config.playlist = [playlistItem]

In iOS SDK 4.x, JWConfig is renamed to JWPlayerConfiguration. This configuration object is created using a separate object called JWPlayerConfigurationBuilder. We have made similar modifications to other player configuration objects such as JWPlaylistItem (now JWPlayerItem) and JWAdConfig (now JWAdvertisingConfig).

// Create a JWPlayerConfiguration object with a single JWPlayerItem.
var item: JWPlayerItem!
do {
    item = try JWPlayerItemBuilder()
} catch {
    // Do something with the build error

do {
    let playerConfiguration = JWPlayerConfigurationBuilder()
} catch {
    // Do something with the error

By separating the construction of configuration objects from their representation, we are able to throw an error if an object is created incorrectly. For example, a configuration object could be missing required properties or have multiple properties set that should not be set simultaneously.

// Try to create a JWPlayerConfiguration without a playlist
do {
    let playerConfiguration = JWPlayerConfigurationBuilder()
        .build() // Will throw an exception because “playlist” was not set
} catch {
    // Do something with the error

The following subsections outline how to migrate the various configuration objects in version 3.x to iOS SDK 4.x.


In iOS SDK 4.x, JWAdConfig is called JWAdvertisingConfig. Create a JWAdvertisingConfig object using either the JWAdsAdvertisingConfigBuilder, JWImaAdvertisingConfigBuilder, or JWImaDaiAdvertisingConfigBuilder class.

3.x 4.x
adMessage JWAdsAdvertisingConfig.adMessage(_ adMessage: String)
client Automatically set by the builder that is used to create the JWAdvertisingConfig
googimaDaiSettings Automatically set by the JWImaDaiAdvertisingConfigBuilder
googimaSettings Automatically set by the JWImaAdvertisingConfigBuilder
rules JWAdsAdvertisingConfig.adRules(_ adRules: JWAdRules

-- OR --

JWImaAdvertisingConfig.adRules(_ adRules: JWAdRules)
schedule JWAdsAdvertisingConfig.schedule(_ schedule: [JWAdBreak])

-- OR --

JWImaAdvertisingConfig.schedule(_ schedule: [JWAdBreak])
skipMessage JWAdsAdvertisingConfig.skipMessage(_ skipMessage: String)
skipOffset JWAdsAdvertisingConfig.skipOffset(_ skipOffset: UInt)
skipText JWAdsAdvertisingConfig.skipText(_ skipText: String)
tag JWAdsAdvertisingConfig.tag(_ tag: URL)

-- OR --

JWImaAdvertisingConfig.tag(_ tag: URL)
vpaidControls JWAdsAdvertisingConfig.vpaidControls(_ vpaidControls: Bool)


In iOS SDK 4.x, JWAdRules is still called JWAdRules. Create a JWAdRules object using the JWAdRulesBuilder class.

3.x 4.x
frequency JWAdRulesBuilder.jwRules(_startOn: UInt, frequency: UInt, timeBetweenAds: UInt, startOnSeek: JWAdShownOnSeek)

-- OR --

JWAdRulesBuilder.imaRules(startOn: UInt, frequency: UInt)
startOn JWAdRulesBuilder.jwRules(_startOn: UInt, frequency: UInt, timeBetweenAds: UInt, startOnSeek: JWAdShownOnSeek)

-- OR --

JWAdRulesBuilder.imaRules(startOn: UInt, frequency: UInt)
startOnSeek JWAdRulesBuilder.jwRules(_startOn: UInt, frequency: UInt, timeBetweenAds: UInt, startOnSeek: JWAdShownOnSeek)
timeBetweenAds JWAdRulesBuilder.jwRules(_startOn: UInt, frequency: UInt, timeBetweenAds: UInt, startOnSeek: JWAdShownOnSeek)


In iOS SDK 4.x, JWConfig is called JWPlayerConfiguration. Create a JWPlayerConfiguration object using the JWPlayerConfigurationBuilder class.

3.x 4.x
advertising JWPlayerConfigurationBuilder.advertising(_ advertising: JWAdvertisingConfig)
autostart JWPlayerConfigurationBuilder.autostart(_ autostart: Bool)
bitRateUpperBound JWPlayerConfigurationBuilder.bitRateUpperBound(_ bitRateUpperBound: Float)
captions JWPlayerView.captionStyle
controls JWPlayerViewController.interfaceBehavior
desc JWPlayerItemBuilder.description(_ description: String)
displayDescription JWPlayerSkin.descriptionIsVisible
displayTitle JWPlayerSkin.titleIsVisible
externalMetadata JWPlayerConfigurationBuilder.externalMetadata(_ externalMetadata: [JWExternalMetadata])
file JWPlayerItemBuilder.file(_ file: URL)
image JWPlayerItemBuilder.posterImage(_ posterImage: URL)
logo JWPlayerViewController.logo
mediaId JWPlayerItemBuilder.mediaId(_ mediaId: String)
nextupDisplay JWPlayerViewController.nextUpStyle
nextupOffset JWPlayerViewController.nextUpStyle
nextupPercentage JWPlayerViewController.nextUpStyle
offlineMessage JWPlayerViewController.offlineMessage
offlinePoster JWPlayerViewController.offlinePosterImage
playbackRates JWPlayerViewController.playbackRates
playbackRateControls JWPlayerViewController.playbackRateControlsEnabled
playlist JWPlayerConfigurationBuilder.playlist(_ playlist: [JWPlayerItem])
preload JWPlayerConfigurationBuilder.preload(_ preload: JWPreload)
related JWPlayerConfigurationBuilder.related(_ related: JWRelatedContentConfiguration)
repeat JWPlayerConfigurationBuilder.repeatContent(_ repeatContent: Bool)
size Set the size of the player by setting the size of JWPlayerView
skin JWPlayerViewController.styling
sources JWPlayerItemBuilder.sources(_ videoSources: [JWVideoSource])
stretching The functionality of JWConfig.stretching can now be achieved dynamically by setting videoGravity on JWPlayerView.
title JWPlayerItemBuilder.title(_ title: String)
tracks JWPlayerItemBuilder.mediaTracks(_ mediaTracks: [JWMediaTrack])


In iOS SDK 4.x, JWPlaylistemItem is called JWPlayerItem. Create a JWPlayerItem object using the JWPlayerItemBuilder class.

3.x 4.x
adSchedule JWPlayerItemBuilder.adSchedule(_ adSchedule: [JWAdBreak])
assetOptions JWPlayerItemBuilder.assetOption
desc JWPlayerItemBuilder.description(_ description: String)
externalMetadata JWPlayerItemBuilder.externalMetadata
file JWPlayerItemBuilder.file(_ file: URL)
googleDaiSettings JWPlayerItemBuilder.googleDAIStream
image JWPlayerItemBuilder.posterImage(_ posterImage: URL)
mediaId JWPlayerItemBuilder.mediaId(_ mediaId: String)
recommendations JWPlayerItemBuilder.recommendations(_ recommendations: URL)
sources JWPlayerItemBuilder.videoSources(_ videoSources: [JWVideoSource])
startTime JWPlayerItemBuilder.startTime(_ startTime: TimeInterval)
title JWPlayerItemBuilder.title(_ title: String)
tracks JWPlayerItemBuilder.mediaTracks(_ mediaTracks: [JWMediaTrack])


In iOS SDK 4.x, JWSource is called JWVideoSource. Create a JWVideoSource object using the JWVideoSourceBuilder class.

3.x 4.x
defaultQuality JWVideoSourceBuilder.defaultVideo(_ defaultVideo: Bool)
file JWVideoSourceBuilder.file(_ file: URL)
label JWVideoSourceBuilder.label(_ label: String)


In iOS SDK 4.x, JWTrack is called JWMediaTrack. Create a JWMediaTrack object using either the JWCaptionTrackBuilder or JWThumbnailTrackBuilder class.

3.x 4.x
defaultTrack JWCaptionTrackBuilder.defaultTrack(_ defaultTrack: Bool)
file JWCaptionTrackBuilder.file(_ file: URL)

-- OR --

JWThumbnailTrackBuilder.file(_ file: URL)
kind Automatically set by the builder that’s used to create the JWMediaTrack
label JWCaptionTrackBuilder.file(_ file: String)


In iOS SDK 4.x, JWRelatedConfig is called JWRelatedContentConfiguration. Create a JWRelatedContentConfiguration object using the JWRelatedContentConfigurationBuilder class.

3.x 4.x
autoplayMessage JWRelatedContentConfigurationBuilder.autoplayMessage(_ message: String)
autoplayTimer JWRelatedContentConfigurationBuilder.autoplayTimer(_ timer: Int)
displayMode JWRelatedContentConfigurationBuilder.displayMode(_ mode: JWRelatedDisplayMode)
file JWRelatedContentConfigurationBuilder.url(_ url: URL)
heading JWRelatedContentConfigurationBuilder.heading(_ heading: String)
onClick JWRelatedContentConfigurationBuilder.onClick(_ relatedOnClick: JWRelatedOnClick)
onComplete JWRelatedContentConfigurationBuilder.onComplete(_ relatedOnComplete: JWRelatedOnComplete)

Event API

In iOS SDK 3.x, there was one delegate (JWPlayerDelegate) to subscribe to for all events. Conforming to such a protocol in Swift would be cumbersome, as protocols in Swift require a class to conform to all interfaces.

In iOS SDK 4.x, the callbacks from JWPlayerDelegate have now been delegated to more logical interfaces. All playback and advertising-related callbacks have been divided across several new delegates. This allows you to optionally define delegates for categories of events through the JWPlayer object.

User interface-related delegates -- such as tracking what buttons a user is tapping or when the control bar appears or disappears -- can be subscribed to through the JWPlayerViewControllerDelegate.

Event Migration

The table below outlines how to migrate from the callbacks in JWPlayerDelegate to the iOS SDK 4.x delegates.

3.x 4.x Callback
onAdBreakEnd JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdBreakStart JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdClick JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdCompanions JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdComplete JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdError JWPlayerDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdImpression JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdMeta JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdPause JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdPlay JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdRequest JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdSchedule JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdSkipped JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdStarted JWAdDelegate jwplayer(_ player: AnyObject, adEvent event: JWAdEvent)
onAdTime JWPlayer See: [Time Events](#time-events)
onAdWarning JWPlayerDelegate jwplayer(_:encounteredWarning:message:)
onAll ---
onAudioTrack JWAVDelegate jwplayer(_:audioTracksUpdated:)
onAudioTrackChanged JWAVDelegate jwplayer(_:audioTrackChanged:)
onBeforeComplete JWPlayerStateDelegate jwplayerContentWillComplete(_:)
onBeforePlay JWPlayerStateDelegate jwplayer(_:willPlayWithReason:)
onBuffer JWPlayerStateDelegate jwplayerContentIsBuffering(_:)
onBufferChange JWPlayerStateDelegate jwplayer(_:updatedBuffer:position:)
onCaptionsChanged JWAVDelegate jwplayer(_:captionTrackChanged:)
onCaptionsList JWAVDelegate jwplayer(_:updatedCaptionList:)
onComplete JWPlayerStateDelegate jwplayerContentDidComplete(_:)
onControlbarVisible JWPlayerViewControllerDelegate playerViewController(_:controlBarVisibilityChanged)
onControls ---
onDisplayClick JWPlayerViewControllerDelegate playerViewController(_:screenTappedAt:)
onError JWPlayerDelegate jwplayer(_:failedWithError:message:)
onFirstFrame JWPlayerStateDelegate jwplayer(_:didFinishLoadingWithTime:)
onFullscreen JWViewControllerDelegate playerViewControllerDidGoFullScreen(_:)
onFullscreenRequested JWViewControllerDelegate playerViewControllerWillGoFullScreen(_:fullScreenViewController:)
onIdle JWPlayerStateDelegate jwplayer(_:didBecomeIdleWithReason:)
onLevels JWAVDelegate jwplayer(_:qualityLevelsUpdated:)
onLevelsChanged JWAVDelegate jwplayer(_:qualityLevelChanged:)
onMeta JWPlaybackMetadataDelegate jwplayer(_:didReceiveMetadata:)
onPause JWPlayerStateDelegate jwplayer(_:didPauseWithReason:)
onPlay JWPlayerStateDelegate jwplayer(_:isPlayingWithReason:)
onPlayAttempt JWPlayerStateDelegate jwplayer(_:isAttemptingToPlay:reason:)
onPlaybackRateChanged JWPlayerStateDelegate jwplayer(_:playbackRateChangedTo:at:)
onPlaylist JWPlayerStateDelegate jwplayer(_:didLoadPlaylist:)
onPlaylistComplete JWPlayerStateDelegate jwplayerPlaylistHasCompleted(_:)
onPlaylistItem JWPlayerStateDelegate jwplayer(_:didLoadPlaylistItem:at:)
onReady JWPlayerDelegate jwplayerIsReady(_:)
onRelatedClose JWPlayerViewControllerDelegate playerViewController(_:relatedMenuClosedWithMethod:)
onRelatedOpen JWPlayerViewControllerDelegate playerViewController(_:relatedMenuOpenedWithItem:withMethod:)
onRelatedPlay JWPlayerViewControllerDelegate playerViewController(_:relatedItemBeganPlaying:atIndex:withMethod:)
onResize JWViewControllerDelegate
onSeek JWPlayerStateDelegate jwplayerHasSeeked(_:)
onSeeked JWPlayerStateDelegate jwplayer(_:seekedFrom:to:)
onSetupError JWPlayerDelegate jwplayer(_:failedWithSetupError:message:)
onTime JWPlayer See: [Time Events](#time-events)
onViewable JWPlayerStateDelegate jwplayer(_:isVisible:)
onWarning JWPlayerDelegate jwplayer(_:encounteredWarning:message:)

Additional Callbacks

New callbacks have been added to iOS SDK 4.x.

3.x 4.x Callback
JWAVDelegate jwplayer(_:captionPresented:at:) Called when a caption is being presented on the screen
JWPlayerStateDelegate jwplayer(_:usesMediaType:) Reports when the type of media has been determined

Time Events

Time events (onTime and onAdTime) are handled differently in iOS SDK 4.x.

In order to listen for time events, call the addTimeObserver method in the player and specify the time events in which your are interested: time events during the content (.mediaTime) or time events during ad playback (.adTime). The block you supply receives the current time in seconds during each time update.

Optionally, you may specify a DispatchQueue to which the events can be emitted. We recommend using a serial queue to ensure your time events are received in the order they are emitted.

// Listen to time events as media content plays
let observer = playerView.player.addTimeObserver(category: .mediaTime, nil) { (seconds) in
   // Code to handle the time event.

// Or, listen to time during ads.
let observer = playerView.player.addTimeObserver(category: .adTime, nil) { (seconds) in
   // Code to handle the time event.

After observing time events, remove the observer from the player.

// Remove the time observer

Advertising API

In iOS SDK 4.x, the Advertising API maintains support for VAST, VMAP, Google IMA, and Google DAI advertising.

In iOS SDK 3.x, there was an advertising configuration property used to set up any type of ads. In iOS SDK 4.x, you can set up the advertising configuration through new dedicated builders for each type of ad.

VAST & VMAPJWAdsAdvertisingConfigBuilder
Google IMAJWImaAdvertisingConfigBuilder
Google DAIJWImaDaiAdvertisingConfigBuilder

To begin running advertising in iOS SDK 4.x, you must create a JWPlayerConfigurationBuilder to include the advertising configuration. Refer to Configuration API and Set up a basic player for more info about setting up the player.


• FreeWheel and VPAID advertising are no longer supported by iOS SDK 4.x.
• You must include the GoogleIMA SDK v3.11.4 in your project if you want to monetize advertising through IMA or DAI.
• For examples on creating advertisements, please refer to the advertising documentation.

Listening to advertising events

In iOS SDK 4.x, there is a dedicated delegate for the advertising events: JWAdDelegate. Refer to Event Migration for more info about the implementation of these delegates.

In iOS SDK 3.x, the SDK reported the ad time event by constantly calling the delegate method informing the current time of an ad. In iOS SDK 4.x, the ad time event is reported in a different way that increases the performance of listening for this event. Refer to Time Events for more information.

Did this page help you?