Using a session ID and token, you can connect to the OpenTok session using the OpenTok.js library.
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 a Session object by calling the
OT.initSession()
method with your
OpenTok API key and the appropriate
session ID:
// Replace with your OpenTok API key and session ID:
var session = OT.initSession(apiKey, sessionID);
The OT.initSession()
method returns a Session object, through which subsequent API calls take place.
Note that calling the OT.initSession()
method does not create an OpenTok session;
it creates a JavaScript Session object, which represents an existing OpenTok session. You create an OpenTok session
using the OpenTok server-side libraries. See Creating
an OpenTok session.
If the user's browser does not support WebRTC, the call to OT.initSession()
results in the page
displaying a message to the user. To check for WebRTC support and prevent this message from being displayed,
you can call the OT.checkSystemRequirements()
method before calling OT.initSession()
:
if (OT.checkSystemRequirements() == 1) {
var session = OT.initSession(apiKey, sessionId);
} else {
// The client does not support WebRTC.
// You can display your own message.
}
Once you have initialized a Session object, call its
connect()
method, passing in a token
and a completion handler function:
var session = OT.initSession(apiKey, sessionId);
session.connect(token, function(error) {
if (error) {
console.log("Error connecting: ", error.name, error.message);
} else {
console.log("Connected to the session.");
}
});
An error object is passed into the completion handler of the connect
event when
the client fails to connect to the OpenTok session. Otherwise, no error object is passed in,
indicating that the client connected successfully to the session.
The Session object also dispatches a sessionConnected
event when the client
connects to the OpenTok session. And the OT object dispatches an exception
event
when there is an error in connecting. However, it is simpler to check for success in connecting
by passing a completion handler into the connect()
method, as the last parameter.
To disconnect from a session, call the disconnect()
method of the Session object:
session.disconnect();
When your client disconnects from a session, the Session object dispatches a sessionDisconnected
event:
session.on("sessionDisconnected", function (event) {
// The event is defined by the SessionDisconnectEvent class
if (event.reason == "networkDisconnected") {
alert("Your network connection terminated.")
}
});
session.connect(token);
The reason
property of the event is a string that describes why the session disconnected.
For example, the previous example notifies the user if they were disconnected due to the network connection
terminating. For details, see SessionDisconnectEvent.
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 dispatched 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 object dispatches a
reconnecting
event. When the connection is restored, the Session object dispatches
a reconnected
event. If the client cannot restore the connection, the client
disconnects from the OpenTok session, and the Session object dispatches the
sessionDisconnected
event.
In response to these events, your application can (optionally) display user interface notifications indicating the temporary disconnection, reconnection, and disconnection states:
session.on(
sessionReconnecting: function() {
// Display a user interface notification.
},
sessionReconnected: function() {
// Adjust user interface.
},
sessionDisconnected: function() {
// Adjust user interface.
}
);
When your client temporarily disconnects from a session, the Subscriber objects in clients subscribing to a stream you publish dispatch events 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 set the
retryAfterReconnect
property to false
in the options you pass into
the Session.signal()
method to prevent signals from being queued while you are disconnected. For more information, see
Preventing signals from being sent during automatic reconnection.
The Session object dispatches a connectionCreated
event when a new client
(including your own) connects to the session. The Session object dispatches a
connectionDestroyed
event when other clients leave the session. These events are
defined by the ConnectionEvent class, which has a connection
object, which is
a Connection object for the connection (created or destroyed) related to the event:
var connectionCount;
session.on({
connectionCreated: function (event) {
connectionCount++;
if (event.connection.connectionId != session.connection.connectionId) {
console.log('Another client connected. ' + connectionCount + ' total.');
}
},
connectionDestroyed: function connectionDestroyedHandler(event) {
connectionCount--;
console.log('A client disconnected. ' + connectionCount + ' total.');
}
});
session.connect(token, function (error) {
if (error) {
console.log("Failed to connect.");
} else {
console.log('You have connected to the session.');
}
});
The Session.connect()
method has a callback function which is passed an optional
error
parameter. If this parameter is present and defined (not null
or
undefined), then there was an error when connecting. Looking for this error in your code will
help you decipher why the end-user was unable to connect:
session.connect(token, function(err) {
if (err) {
// handle error
} else {
// connection succeeded
}
});
A large number of errors that come back when attempting to connect are due to either invalid or expired tokens. Make sure you are following the token best practices outlined here.
Another common reason for connecting to a session failing is due to the end user's internet connection. Examples of this include:
This will result in an error with the code 1006. We recommend you handle this using the code below. Other reasons for connecting to a session failing include the OpenTok servers being down, or that some kind of unexpected error happened (such as a 500-level error in the server). While this doesn't happen often, it is good practice to handle these errors.
If you follow these instructions your error handling code should look something like:
session.connect(token, function(err) {
if (err) {
if (err.name === "OT_NOT_CONNECTED") {
showMessage('Failed to connect. Please check your connection and try connecting again.');
} else {
showMessage('An unknown error occurred connecting. Please try again later.');
}
}
});
You can lose your connection after you have already successfully connected to a Session. You can
handle this case by listening for the sessionDisconnected
event with a reason of
"networkDisconnected":
session.on({
sessionDisconnected: function(event) {
if (event.reason === 'networkDisconnected') {
showMessage('You lost your internet connection.'
+ 'Please check your connection and try connecting again.');
}
}
});
The following code includes a connect()
method, which connects to a session. Once connected,
the code tracks when clients join and leave the session. It also has a method for disconnecting from the session:
var session;
var connectionCount = 0;
function connect() {
// Replace apiKey and sessionId with your own values:
session = OT.initSession(apiKey, sessionId);
session.on({
connectionCreated: function (event) {
connectionCount++;
console.log(connectionCount + ' connections.');
},
connectionDestroyed: function (event) {
connectionCount--;
console.log(connectionCount + ' connections.');
},
sessionDisconnected: function sessionDisconnectHandler(event) {
// The event is defined by the SessionDisconnectEvent class
console.log('Disconnected from the session.');
document.getElementById('disconnectBtn').style.display = 'none';
if (event.reason == 'networkDisconnected') {
alert('Your network connection terminated.')
}
}
});
// Replace token with your own value:
session.connect(token, function(error) {
if (error) {
console.log('Unable to connect: ', error.message);
} else {
document.getElementById('disconnectBtn').style.display = 'block';
console.log('Connected to the session.');
connectionCount = 1;
}
});
}
function disconnect() {
session.disconnect();
}
connect();