Session Creation

When you connect to a TokBox session on an app, you specify the session you want to connect to using a TokBox session ID.

OpenTok sessions do not expire. However, authentication tokens do expire. (See Connection Token Creation.) Also note that sessions cannot explicitly be destroyed.

Creating a session ID using the the test sandbox session creation form

While working on a test version of your app, you can obtain a test session ID using the Dashboard page.

You can include the following advanced settings:

• Location hint — An IP address that TokBox will use to situate the session in its global network. In general, you should not specify a location hint; if no location hint is specified,the session uses a media server based on the location of the first client connecting to the session. Specify a location hint only if you know the general geographic region (and a representative IP address) for the session and you think the first client connecting may not be in that region.
• Peer-to-peer — Enable this option and the session will attempt to transmit streams directly between clients. Peer-to-peer streaming is supported for sessions that have no more than two connected clients. If peer-to-peer streaming fails (either when streams are initially published or during the course of a session), the session falls back to using the OpenTok servers for relaying streams. For more information, see Peer-to-Peer Streaming.

Click the Generate Session button. The form displays a new session ID.

You can also use the OpenTok server-side libraries to create session IDs while testing. See the next section.

Creating a session ID using the OpenTok server-side libraries

You can create an OpenTok session using one of the OpenTok server-side libraries, which are available for Java, PHP, Python, and Ruby. Each server-side library includes an OpenTokSDK object. While each of these libraries may slightly differ, the basic concept remains the same. Alternatively, the developer can POST a request directly to the specified OpenTok API URL, as described at the end of this section.

In order to create a session, an OpenTokSDK object is created by passing in the API key and the partner secret. You can invoke the API to create a session by calling the create_session() method of the OpenTokSDK object. This returns an OpenTokSession object of the format described below.

Here is a simple example in PHP:

<?php
    require_once 'API_Config.php';
    require_once 'OpenTokSDK.php';

    $apiObj = new OpenTokSDK(API_Config::API_KEY, API_Config::API_SECRET);
    $session = $apiObj->create_session();
    echo $session->getSessionId();
?>

This creates a new session, situating it in TokBox's global network near the IP as specified by $_SERVER["REMOTE_ADDR"].

The create_session method that generates a Session object. This object includes a session_id property, which is the session ID for the new session. Use this session ID in JavaScript on the page that you serve to the client. The JavaScript will use this value when calling the connect() method of the Session object (to connect a user to an OpenTok session).

Although this example is written in PHP, the other OpenTok server-side libraries (for Java, Python, and Ruby) work in the same way. They each define an OpenTokSDK object, which includes a create_session() method. This method has two parameters:

• location (String) — An IP address that TokBox will use to situate the session in its global network. Ideally, this IP address should be representative of the geographical locations of the participants in the session. If you have access to the IP address of the first participant in the session, use that address.
• properties (Object) — Optional. An object used to enable peer-to-peer streaming in sessions. For details, see Peer-to-Peer Streaming and OpenTok server-side libraries documentation.

For more details, see Session Management and the documentation for the create_session() method OpenTok server-side libraries documentation.

Next workflow step: Connection Token Creation.