Suggestions

close search

Searching ...

Using a session ID and token, you can connect to the OpenTok session using the OpenTok iOS SDK.

This topic includes the following sections:

• Initializing an OTSession object
• Connecting to a session
• Monitoring the connection status
• Disconnecting from a session
• Detecting when you have disconnected from a session
• Automatic reconnection
• Detecting when other clients have connected and disconnected
• Running in the background state

For information on creating a session ID and an authentication token, see Session Creation and Token Creation.

Initializing an OTSession object

Before you can connect to a session, instantiate an OTSession object by calling the [OTSession initWithApiKey: sessionId: delegate:] method with your OpenTok API key and the appropriate session ID:

// Replace kApiKey with your OpenTok API key:
// Replace kSessionId with an OpenTok session ID:
session = [[OTSession alloc] initWithApiKey:kApiKey
                                       sessionId:kSessionId
                                       delegate:self];

Note that calling the [OTSession initWithApiKey:sessionId:delegate:] method does not create an OpenTok session; it creates the Objective-C OTSession object, which represents an existing OpenTok session. You create an OpenTok session using the OpenTok server-side libraries. See Creating an OpenTok session.

Implement the methods of the OTSessionDelegate protocol in the object you specify as the delegate object. These methods are called when session-related events occur.

Connecting to a session

Call the [OTSession connectWithToken:error:] method, passing in the token for the client:

OTError* error = nil;
[session connectWithToken:kToken error:&error];
if (error) {
  NSLog(@"connect failed with error: (%@)", error);
}

The [OTSessionDelegate session:didConnect] message is sent when the client connects to the OpenTok session.

The OTSessionDelegate session:didFailWithError:] is sent when there is an error in connecting. See the documentation for the OTSessionErrorCode enum for descriptions of values of the code property of the error object.

Monitoring the connection status

You can get the connection status by checking the sessionConnectionStatus property of the OTSession object:

session.sessionConnectionStatus

Valid values are defined in the OTSessionConnectionStatus enum.

You can use a key-value observer to monitor this property. However, the [OTSessionDelegate sessionDidConnect:] and [OTSessionDelegate sessionDidDisconnect:] messages are sent to the session's delegate when the session connects and disconnects.

Disconnecting from a session

To disconnect from a session, call the [OTSession disconnect:] method.

OTError* error = nil;
[session disconnect:&error];
if (error) {
  NSLog(@"disconnect failed with error: (%@)", error);
}

Detecting when you have disconnected

The [OTSessionDelegate sessionDidDisconnect:] message is sent to the session's delegate when the session disconnects.

Note that sessions automatically disconnect when the app is suspended.

If the connection to the session drops due to an error that occurs after a successful connection, the [OTSessionDelegate session:DidFailWithError:] message is sent prior to the [OTSessionDelegate sessionDidDisconnect:] message. The OTSessionErrorCode enum defines the code property of the OTError object passed into the [OTSessionDelegate session:DidFailWithError:] message, and it describes the the reason for the disconnection.

Automatic reconnection

Clients will attempt to automatically reconnect to a session they disconnect unexpectedly (for example, due to a drop in network connectivity). You do not need to add any code to have the clients reconnect automatically, unless you want to respond to messages sent when your client disconnects and reconnects. For sample code that demonstrates the use of these events, see the opentok-reconnection repo on GitHub.

When the connection is dropped and the client tries to reconnect, the [OTSessionDelegate sessionDidBeginReconnecting:] message is sent to the OTSession object's delegate. When the connection is restored, the [OTSessionDelegate sessionDidReconnect:] message is sent. If the client cannot restore the connection, the [OTSessionDelegate sessionDidDisconnect:] message is sent.

In response to these events, your application can (optionally) display user interface notifications indicating the temporary disconnection, reconnection, and disconnection states.

// OTSession delegate callbacks:
- (void)sessionDidBeginReconnecting:(OTSession*)session
{
  // Display a user interface notification.
}

- (void)sessionDidReconnect:(OTSession*)session
{
  // Adjust user interface.
}

- (void)sessionDidDisconnect:(OTSession*)session
{
  // Adjust user interface.
}

When your client temporarily disconnects from a session, the OKSubscriberKitDelegate objects in clients subscribing to a stream you publish send messages when your published stream drops and when (and if) it resumes automatically. For more information, see Automatic reconnection in the "Subscribing to streams" developer guide.

By default, any signals you send while your client is temporarily disconnected from a session are queued and sent when (and if) you successfully reconnect. You can use the [OTSession signalWithType:string:connection:retryAfterReconnect:error:] method to prevent signals from being queued while you are disconnected. For more information, see Preventing signals from being sent during automatic reconnection.

Detecting when other clients have connected and disconnected

The [OTSessionDelegate session:connectionCreated:] message is sent to the session's delegate when another client connects to the session (and for each client connected to the session when you connect).

The [OTSessionDelegate session:connectionDestroyed:] message is sent to the session's delegate when another client disconnects from the session.

Running in the background state

See Using the OpenTok iOS SDK in applications running in the background state.