Suggestions

close search

Migrating to version 2.2+ of the OpenTok iOS SDK

There are API changes, new features, UI changes and other considerations that you should be aware of when migrating an application from version 2.1.7 to version 2.2+ of the OpenTok iOS SDK.

API changes in version 2.2
New API in version 2.2
UI changes in publisher and subscriber objects
Other new features

API changes in version 2.2

When migrating from version 2.1.7, change your code based on the following API changes.

Initializing a session — The initializer for the OTSession object now includes an API key parameter:

2.1.7 version 2.2 version
[OTSession initWithSessionId:
           delegate:]
[OTSession initWithApiKey:
           sessionId:
           delegate:]

Connecting to a session — The method to connect to a session no longer includes the API key as a parameter:

2.1.7 version 2.2 version
[OTSession connectWithApiKey:
           token:]
[OTSession connectWithToken:
           error:]

Note that the new error parameter. In the case of a synchronous error in calling this method, this parameter is set to an OTError object.

The names of the following OTSessionConnectionStatus enum constant changed in version 2.2:

2.1.7 constant 2.2 constant
OTSessionConnectionStatusDisconnected OTSessionConnectionStatusNotConnected

Subscribing to a stream — In version 2.1.7, when you initialize an OTSubscriber object, it immediately starts subscribing to the stream. In version 2.2, after you instantiate an OTSubscriber instance, you must call the [OTSession subscribe:error:] method to begin subscribing to the stream:

_subscriber = [[OTSubscriber alloc] initWithStream:stream delegate:self];
OTError* myError = nil;
[_session subscribe:_subscriber error:&myError]
if (myError) {
  NSLog(@"subscribe failed with error: (%@)", myError);
}

The OTSubscriber class extends the new OTSubscriberKit class. And the OTSubscriberDelegate protocol conforms to the new OTSubscriberKitDelegate protocol. (See New API in version 2.2 below.).

The OTSubscriber.view property is a UIView object. (In version 2.1.7, it was set to an OTVideoView object, but that class has been removed from the SDK. See UI changes in publisher and subscriber objects.)

In version 2.2 of the SDK, subscriber views are not automatically removed from their superviews when the [OTSessionDelegate sessionDidDisconnect:] message is sent. Call the [_subscriber.view removeFromSuperView:] method of the OTSubscriber object to remove the subscriber.

The [OTSubscriber stream:didChangeVideoDimensions:] method is removed in version 2.2 of the SDK. You can implement your own custom subscriber class, based on the new OTSubscriberKit class, and directly monitor the dimensions of the video stream. (See New API in version 2.2 below.)

See UI changes in publisher and subscriber objects for information on changes to the OTSubscriber user interface.

Publishing a stream — The OTPublisher class extends the new OTPublisherKit class. And the OTPublisherDelegate protocol conforms to the new OTPublisherKitDelegate protocol. (See New API in version 2.2 below.). Also, the following message names have changed in the OTPublisherDelegate protocol:

2.1.7 version 2.2 version
[OTPublisherDelegate publisherDidStartStreaming:] [OTPublisherDelegate publisher:
                     streamCreated:]
[OTPublisherDelegate publisherDidStopStreaming:] [OTPublisherDelegate publisher:
                     streamDestroyed:]

The OTPublisher.view property is a UIView object. (In version 2.1.7, it was set to an OTVideoView object, but that class has been removed from the SDK. See UI changes in publisher and subscriber objects.)

In version 2.2 of the SDK, publisher views are not automatically removed from their superviews when the [OTSessionDelegate sessionDidDisconnect:] message is sent. Call the [_publisher.view removeFromSuperView:] method of the OTPublisher object to remove the publisher.

See UI changes in publisher and subscriber objects for information on changes to the OTPublisher user interface.

Error handling — Error parameters have been added to the following methods:

[OTSession connectWithToken:error:]
[OTSession publish:error:]
[OTSession signalWithType:string:connection:error:]
[OTSession subscribe:error:]
[OTSession unpublish:error:]
[OTSession unsubscribe:error:]

If there is a synchronous error in calling the method, the error object is set to an OTError object; otherwise it is set to NULL.

For example, the following code checks for a synchronous error when calling [OTSession subscribe:error]:

OTError* myError = nil;
[_session subscribe:_subscriber error:&myError]
if (myError) {
  NSLog(@"subscribe failed with error: (%@)", myError);
}

The following error constants are no longer used in version 2.2 (and they are not included in the OTError enums):

OTSDKUpdateRequired
OTP2PSessionUnsupported
OTUnknownServerError
OTP2PSessionRequired
OTSessionCompatibilityMismatch
OTSelfSubscriberFailure

The following OTSessionErrorCode constants in version 2.1.7 are replaced in version 2.2:

2.1.7 version 2.2 version
OTInvalidSessionId OTInvalidSession
OTSessionSignalConnection OTSessionInvalidSignalType
OTSessionSignalDataTooLong

The following OTPublisherErrorCode constants in version 2.1.7 are replaced in version 2.2:

2.1.7 version 2.2 version
OTNoMediaPublished OTPublisherInternalError
OTUserDeniedCameraAccess OTPublisherInternalError

The following OTSubscriberErrorCode constants in version 2.1.7 are replaced in version 2.2:

2.1.7 version 2.2 version
OTFailedToConnect OTSubscriberInternalError
OTNoStreamMedia OTSubscriberInternalError
OTInitializationFailure OTSubscriberInternalError
OTConnectionTimeOut
OTInvalidStreamType OTSubscriberInternalError

Signaling API — The signaling API has changed from version 2.1.7 to version 2.2:

2.1.7 version 2.2 version
[OTSession signalWithType:
           data:
           completionHandler:]
[OTSession signalWithType:
           string:
           connection:
           error:]
[OTSession signalWithType:
           data:
           connections:
           completionHandler:]
[OTSession signalWithType:
           string:
           connection:
           error:]

Note the following changes:

In version 2.2, receiving a signal is implemented in the OTSessionDelegate protocol:

2.1.7 version 2.2 version
[OTSession receiveSignalType:
           withHandler:]
[OTSessionDelegate session:
           receivedSignalType:
           fromConnection:
           withString:]

Subscriber delegate name change — The OTSubscriberDelegate protocol has been renamed OTSubscriberKitDelegate.

Session delegate name changes — Some messages in the OTSessionDelegate methods have been renamed:

2.1.7 version 2.2 version
[OTSessionDelegate didReceiveStream:] [OTSessionDelegate streamCreated:]
[OTSessionDelegate didDropStream:] [OTSessionDelegate streamDestroyed:]
[OTSessionDelegate didCreateConnection:] [OTSessionDelegate connectionCreated:]
[OTSessionDelegate didDropConnection:] [OTSessionDelegate connectionDestroyed:]

OTVideoView removed — The OTVideoView class is no longer included. See UI changes in publisher and subscriber objects below.

OTSession.connectionCount removed — The OTSession class no longer includes a connectionCount property. You can monitor the [OTSessionDelegate session:connectionCreated:] and [OTSessionDelegate session:connectionDestroyed:] messages and maintain a count of connections in your own variable.

OTStream.type removed — The OTStream is no longer includes a type property.

New API in version 2.2

Support for archiving — The OpenTok iOS SDK 2.2 supports the OpenTok archiving feature. The [OTSessionDelegate session:archiveStartedWithId:name:] message is sent when an archive recording of a session starts. The [OTSessionDelegate session:archiveStoppedWithId:] message is sent when an archive recording of a session stops. You may want to add or remove a user interface element indicating that recording has started or stopped, based on this message.

New custom video stream API — The following new classes and protocols support the new custom video stream API:

UI changes in publisher and subscriber objects

The OTPublisher and OTSubscriber objects no longer include the default user interface controls for the following:

The default view in the OTPublisher and OTSubscriber class includes only the video.

You must implement these user interface controls in your own code. This gives you the ability to use your own design and add only the controls you want. The OpenTok iOS SDK sample apps at github show how to implement these.

The cookbook also includes sample code for adding a user interface control indicating that archiving of a session has started (or stopped). (Archiving is a new feature in version 2.2 of the OpenTok iOS SDK.)

Other new features

The OpenTok iOS 2.2 SDK also includes support for TURN over TCP. This improves connectivity in restricted network environments. Only ports 80 and 443 are required. For more information see OpenTok now supports TURN over TCP.