Suggestions

close search

Joining a Session — Android

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

This topic includes the following sections:

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

Initializing a Session object

Before you can connect to a session, instantiate a Session object by calling the Session() constructor, passing in the appropriate Android application context, your OpenTok API key and a session ID:

mSession = new Session(context, API_KEY, SESSION_ID);

Note that calling the Session() constructor does not create an OpenTok session; it creates the Java Session object, which represents an existing OpenTok session. You create an OpenTok session using the OpenTok server-side libraries. See Creating an OpenTok session.

Add a listener object for basic session-related events by calling the setSessionListener(Session.SessionListener listener) method of the Session object:

mSession.setSessionListener(this);

Implement the methods of the Session.SessionListener interface in the object you specify as the event listener object. These methods are called when session-related events occur.

Connecting to a session

Call the Session.connect(token) method, passing in a valid token:

mSession.connect(TOKEN);

The Session.SessionListener.onConnected(Session session) method is called when the client connects to the OpenTok session.

@Override
protected void onConnected(Session session) 
  // This client has connected to the session.
}

The Session.SessionListener.onError(Session session, OpentokError error) method is called when there is an error in connecting. See the documentation for the OpentokException.ErrorCode enum for descriptions of values of the code property of the error object.

@Override
public void onError(Session session, OpentokError error) {
  Log.i(LOGTAG, "Exception: " + error.getMessage());
}

Disconnecting from a session

To disconnect from a session, call the Session.disconnect() method.

mSession.disconnect();

Detecting when you have disconnected

The Session.SessionListener.onDisconnected(Session session) method is called when the client disconnects from the OpenTok session.

@Override
public void onDisconnected(session) {
  // This client has disconnected to the session.
}

If the connection to the session drops due to an error that occurs after a successful connection, the Session.SessionListener.onError(Session session, OpentokError error) method is called prior to the Session.SessionListener.onDisconnected(Session session) method. The OpentokError object passed into the Session.SessionListener.onError(Session session, OpentokError error) method describes 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 events that occur 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 Session.ReconnectionListener.onReconnecting(Session session) method is called. When the connection is restored, the Session.ReconnectionListener.onReconnected(Session session) method is called. If the client cannot restore the connection, the client disconnects from the OpenTok session, and the Session.SessionListener.onDisconnected(Session session) method is called.

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

// In the implementation of the Session.ReconnectionListener interface
@Override
public void onReconnecting(session) {
  // Display a user interface notification.
}

public void onReconnected(session) {
  // Adjust user interface.
}

// In the implementation of the Session.SessionListener interface
@Override
public void onDisconnected(session) {
  // Adjust user interface.
}

When your client temporarily disconnects from a session, methods in the implementations of the SubscriberKit.StreamListener interface in clients subscribing to a stream you publish are called when your published stream drops and when (and if) it resumes automatically. For more information, see the automatic reconnection section in the "Subscribing to streams" developer's 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 Session.sendSignal(String type, String data, Connection connection, boolean retryAfterReconnect) method and set the retryAfterReconnect parameter to false 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

When you are connected to a session, the Session.ConnectionListener.onConnectionCreated(Session session, Connection connection) method is called when a new client (other than your own) connects to the session.

The Session.ConnectionListener.onConnectionDestroyed(Session session, Connection connection) method is called when a client (other than your own) leaves the session. The Connection object passed into the method defines the connection hat has left the session.

Add a listener object for these connection events by calling the setConnectionListener(Session.ConnectionListener listener) method of the Session object:

mSession.setSessionListener(this);
@Override
public void onConnectionCreated(Session session, Connection connection)
{
  // New client connected to the session
}

@Override
public void onConnectionDestroyed(Session session, Connection connection)
{
  // A client disconnected from the session
}