Objective

Managing JavaScript sessions and SDK socket connections.

Applies To

• JavaScript
• WebSocket Connection

Procedure

Sessions

Sessions facilitate a live communication stream between the Client SDK and Vonage API platform. Sessions are established by calling the login(token) method and enables the client to receive in-app Voice and Messaging events. The client connection is maintained through a WebSocket connection.

SDK Socket Connection Management

During the lifecycle of a session, the socket managing the session may experience connectivity issues, for example, due to local network conditions.

If the socket experiences connectivity issues, two things happen; The API platform will dispatch a disconnect callback with CONNECTION_FAILED, and, by default, the SDK will automatically attempt to reconnect the socket and connect to the same Session.

// Disconnect is the first callback fired
client.on("disconnect", () => {
    // You can update UI as required, but no further work is required to reconnect
}

There will be five reconnection attempts by default, starting at 1s intervals from losing the connection and increasing exponentially.

// This callback will fire for each reconnection attempt.
client.on("reconnecting", (retryCount) => {
    console.log(`reconnection attempt: ${retryCount}`)
}

If the automatic reconnection attempts are successful there will be no other work required.

// This will fire on successful reconnection
client.on("reconnect", () => {}

If the reconnect attempts fail, the socket will transition to a disconnected state, and the error will be surfaced to the SDK through the NexmoClient error callback with the type “error:client:reconnection_failed”.

// Use the existing error callback on client 
client.on("error", (err:NexmoClientError) => {
    // Reconnection failure error type
    if (err.type == "error:client:reconnection_failed"){
        sleep(10*1000)
        // This call is required to restart connection after failure
        client.connect()
    }
}

After emitting this error event the SDK will no longer try to reconnect automatically. In order to restart the connection, call the client.connect() method. If the manual reconnection was successful within five minutes of the initial loss of the connection it will reconnect to the same session. As long as the reconnection is done within those five minutes, and, for example, there is an active call, the call will remain active. If the client does not reconnect after five minutes, there is a risk for the active call to be dropped.

Session Token Expiration

JWT tokens are minted with an expiration timeframe and this timeframe is up to the developer to decide. These tokens are used to authenticate the creation of the session.

When a session token expires, the API platform will dispatch a disconnect callback with TOKEN_EXPIRED in the `reason` parameter. After getting the disconnect callback, the automatic reconnection logic described above will fail due to the invalid token, so a minting of a new token and the calling for client.connect() is the way to keep the session alive. This should be done within the five minute timeframe for the session to stay alive.

const nexmoApplication = await client.login("TOKEN");
// disconnect is called whenever a connection is closed
client.on("disconnect", (reason) => {
    if (reason == "TOKEN_EXPIRED") {
        // GET NEW TOKEN FROM SOMEWHERE
        await nexmoApplication.updateToken("NEW_TOKEN")
        // on reconnection CAPI will automatically recreate session with updated token
        client.connect()
    }
    else {
        // The other option here is the CONNECTION_FAILED mentioned above
        // SDK will automatically try and reconnect
    }
}

We strongly recommend that you periodically update the session token before the previous token expires to prevent potential reconnection errors.