Suggestions

close search

Searching ...

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:

• You can only send a string as the signal data. You can no longer set the data as other types of objects.
• The method takes a connection parameter that is either a single OTConnection object (not an array) or nil (to send a signal to all clients in the session).
• Completion blocks for signaling have been removed. If sending a signal fails, the error object passed into the signal methods is set to an OTError object. The OTSessionErrorCode enum (in OTError.h) includes OTSessionInvalidSignalType and OTSessionSignalDataTooLong constants for these errors.

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:

• OTPublisherKit—Use this class to use a custom video capturer and video renderer for an audio-video stream to publish to an OpenTok session. Note that the OTPublisher class, which uses the iOS camera as a direct video feed, is a subclass of OTPublisherKit.

• OTSubscriberKit—Use this class to use a custom video renderer for an audio-video stream. Note that the OTSubscriber class, which displays the video stream unaltered, is a subclass of OTSubscriberKit.

• OTVideoCapture—Use this interface is to provide video data to an OTPublisherKit object.

• OTVideoRender—Use this interface is to render video data in an OTPublisherKit object or OTSubscriberKit object.

• Other classes and enums related to the custom video stream API are defined in the OTVideoKit.h file.

• New OTSession.apiQueue property—The delegate callback queue is now application-definable. The GCD queue for issuing callbacks to the delegate may be overridden to allow integration with XCTest (new in Xcode 5) or other frameworks that need the to operate in (and block) the main thread.

• The enums in the OTError.h file have new values. The error code values match the values for corresponding errors in the OpenTok.js 2.2 library and the OpenTok Android 2.2 SDK.

UI changes in publisher and subscriber objects

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

• A control for toggling the camera in the OTPublisher view — You can add your own user interface control that uses the cameraPosition property of the OTPublisher object to set the camera used by the publisher.
• A display of the stream name in both the OTSubscriber view and the OTPublisher view — You can add your own user interface control that displays the name based on the name property of the OTStream object consumed by the subscriber or the name used when calling the [OTPublisher initWithDelegate:name:] method.
• A mute button in the OTSubscriber view — You can add your own user interface control that sets the subscribeToAudio property of the OTSubscriber object to mute and resume audio for the subscriber. Check the hasAudio property of the OTStream object consumed by the subscriber to determine if the stream has audio.
• Mute button in the OTPublisher view — You can add your own user interface control that sets the publishAudio property of the OTPublisher object to mute and resume audio for the publisher.
• An indicator that the video was disabled for a subscriber — You can add your own user interface control that responds to the [OTSubscriber subscriberVideoDisabled:reason:] message to indicate that video was disabled.

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.