Migrating from 2.x to 3.x - iOS

This guide provides an introduction to the 3.x Programmable Video iOS SDK and a set of guidelines to migrate an application from 2.x to 3.x.

Programming Model

The programming model has not changed from 2.x to 3.x. Refer to our 2.x migration guide for a refresher on the Video iOS SDK models.

Xcode and iOS Version Support

Twilio Video 3.x is built with Xcode 11 and officially adds support for iOS 13 and iPadOS 13 APIs. The framework can be consumed with previous versions of Xcode. However, re-compiling Bitcode when exporting for Ad Hoc or Enterprise distribution requires the use of Xcode 11.x. 3.0 also removes support for iOS 9 and iOS 10, and raises the minimum supported iOS version to 11.0.

If your application's Deployment Target was previously set to iOS 10.3 or earlier, you will need to update it to 11.0 or greater to use the 3.x SDK.

Region Selection

The SDK uses a new WebSocket based signaling transport, and communicates with globally available signaling Servers over IPv4 and IPv6 networks. The TVIConnectOptions.region property has been added which allows you to specify the region of the signaling server. By default, the Client will connect to the nearest signaling Server determined by latency based routing. Setting a value other than "gll" bypasses routing and guarantees that signaling traffic will be terminated in the region that you prefer.

let connectOptions = ConnectOptions(token: accessToken) { (builder) in
    builder.region = "us1"
    builder.roomName = "my-room"
}
self.room = TwilioVideoSDK.connect(with: connectOptions, delegate: self)

If you were previously allowing traffic to signaling servers by IP address you will now need to allow the FQDN for the region that you are connecting to instead. See the Signaling Communication section of the Video IP Addresses guide for more information.

Access Tokens

With this new WebSocket based signaling transport, some modifications may need to be made to the Access Tokens that you generate. Specifically:

• Ensure that the AccessToken does not contain a configuration profile sid. Configuration profiles were previously deprecated and are no longer supported.
• Set the Time-To-Live (TTL) of your AccessToken to the maximum allowed session duration, currently 14400 seconds (4 hours). This ensures that when a network loss occurs the client will be able to re-authenticate the reconnection. Note, a reconnection attempt with an expired AccessToken will result in an AccessTokenExpiredError.

TVICameraSource Orientation Tracking Changes

With support for iOS 13, we now have the ability to monitor UIWindowScene based notifications, for determining the orientation of the camera for capture and preview. The TVICameraSourceOrientationTracker protocol has been added and TVICameraSourceOptionsBuilder has a new property, orientationTracker which allows you to adopt this method of tracking.

To opt into tracking based on the rotation of a UIWindowScene you must provide the scene to track when creating the TVICameraSourceOptions.

// Track the orientation of the key window's scene.
let options = CameraSourceOptions { (builder) in
    if let keyScene = UIApplication.shared.keyWindow?.windowScene {
        builder.orientationTracker = UserInterfaceTracker(scene: keyScene)
    }
}
let camera = CameraSource(options: options, delegate: self)

You will also need to forward UIWindowScene events from your UIWindowSceneDelegate to keep TVIUserInterfaceTracker up to date as the scene changes.

// Forward UIWindowScene events
func windowScene(_ windowScene: UIWindowScene,
                 didUpdate previousCoordinateSpace: UICoordinateSpace,
                 interfaceOrientation previousInterfaceOrientation: UIInterfaceOrientation,
                 traitCollection previousTraitCollection: UITraitCollection) {
    UserInterfaceTracker.sceneInterfaceOrientationDidChange(windowScene)
}

Removal of Deprecated Items

The deprecated TVIVideoCapturer APIs have been removed:

• TVIVideoCapturer
• TVICameraCapturer
• TVIScreenCapturer
• TVIVideoConstraints
• TVILocalVideoTrack.capturer
• TVILocalVideoTrack.constraints
• TVILocalVideoTrack.trackWithCapturer:
• TVILocalVideoTrack.trackWithCapturer:enabled:constraints:name:

Refer to our Video Source APIs document for more information on working with the Video Source APIs introduced in 2.6.0.

The TVIAudioOptions that are no longer supported by WebRTC have been removed.

• TVIAudioOptions.levelControl
• TVIAudioOptions.levelControlInitialPeakLevelDBFS
• TVIAudioOptionsBuilder.levelControl
• TVIAudioOptionsBuilder.levelControlInitialPeakLevelDBFS

The TVIAudioSessionActivated() and TVIAudioSessionDeactivated() methods have been removed as the Video SDK no longer needs to terminate the signaling connection when an application is backgrounded.

The TVIVideoRenderer.optionalPixelFormats property has been removed. TVIVideoRenderer is expected to deal with video in any of the valid TVIPixelFormats. If the renderer cannot handle a frame it should drop that frame. There will be no more automatic conversion to I420 for renderers that do not support a particular format.

Improved Objective-C API

In 3.x we have refactored the TVILocalParticipantDelegate and TVIRemoteParticipantDelegate methods to be consistent with the did naming convention used in the Swift APIs. Listed below are the changes to the Objective-C APIs:

TwilioVideoSDK

TVILocalParticipantDelegate

TVIRemoteParticipantDelegate

Improved Swift API

In 3.x we have revisited the way the Programmable Video iOS SDK is exposed in Swift to make developing Swift applications more idiomatic. Numerous changes were made across the entire surface area of the SDK which will require modifications in your current project. Among the high level changes:

• The TVI prefix has been removed from all exposed types.
• Many of the delegate and class function declarations have been renamed to provide better clarity of their intent.
• The TwilioVideo class has been renamed to TwilioVideoSDK. This was necessary to allow type clashes to be resolved by qualifying the type name with the module name. For instance, if your application also declares a Room type, it will be necessary to distinguish the SDK's Room type by prefixing it with module name, TwilioVideo.Room. In previous versions of the iOS SDK, this would fail because Swift would recognize that there was a TwilioVideo class and it would attempt to find the Room type declared there. This is a known issue in Swift where type qualification will fail if a module contains a type of the same name.

For example, consider an application, MyApp, that contains its own implementation of a RemoteParticipant class. To differentiate between the RemoteParticipant class from the application and from the SDK, you would prefix the type definition with the module name:

var remoteParticipantFromApp: MyApp.RemoteParticipant?
var remoteParticipantFromSDK: TwilioVideo.RemoteParticipant?

Listed below are the major changes to the Swift APIs:

TwilioVideoSDK

AudioDevice

AudioDeviceRenderer

AudioDeviceCapturer

AudioFormat

AudioOptionsBuilder

CameraSource

CameraSourceDelegate

CameraSourceOptionsBuilder

ConnectOptionsBuilder

DataTrackOptions

DataTrackOptionsBuilder

DefaultAudioDevice

IceCandidatePairStats

IceOptions

IceOptionsBuilder

IsacCodec

LocalParticipantDelegate

RemoteDataTrackDelegate

RemoteParticipantDelegate

Room

RoomDelegate

Track

VideoOrientation

VideoView

VideoViewDelegate