Using a session ID and token, you can connect to the OpenTok session using the OpenTok iOS SDK.
This topic includes the following sections:
For information on creating a session ID and an authentication token, see Session Creation and Token Creation.
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.
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.
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.
To disconnect from a session, call the [OTSession disconnect:]
method.
OTError* error = nil;
[session disconnect:&error];
if (error) {
NSLog(@"disconnect failed with error: (%@)", error);
}
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.
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.
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.
See Using the OpenTok iOS SDK in applications running in the background state.