Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalBest practices for handling Video API server rotations and having clients automatically reconnect when they occur.
Modern cloud auto-scaling makes it necessary to establish a minimum rotation time for services. Sessions lasting more than 8 hours might be disconnected, as they may reside in services that are scaling out or scaling in.
You can register a callback URL for session events to be sent to your callback URL. When a group of Video API servers for one of your sessions is scheduled to be rotated, a sessionNotification event is sent to your registered callback endpoint.
See the Session Monitoring documentation.
If clients remain connected to a session when set of servers shut down because of server rotation, a sessionDestroyed event is set to your callback URL. The reason property of the sessionDestroyed event is set to "serverRotation". And each connected client is disconnected from the session and receives a sessionDestroyed event.
Clients using version 2.30.0 or later of the Video API client SDKs can automatically stay connected to a session when servers for the session rotate. See the next section, Automatic session migration.
For clients using older versions of the client SDKs, there are steps you can take in response to a sessionNotification event to keep clients connected. (See Responding to server rotation session notification events.)
The session migration feature seamlessly transfers all participants in a session to a new server during server rotation. This feature ensures session continuity with minimal disruption to participants.
Note: Session migration is a beta feature.
Session migration is available in version 2.30.0 or later of the client SDKs. See the next section, Enabling session migration in clients.
The benefits of enabling session migration include improved reliability, reduced reconnection times, and uninterrupted user experience during planned server transitions. Note only live sessions are migrated. Ongoing recordings may be interrupted during migration and will need to be restarted manually — see Responding to server rotation session notification events.
When you initialize a session in the Video API client SDKs, you can set an option to have a client remain connected to the session during server rotation.
By default, the session migration option is set to false. Be sure to set it to true to enable session migration in each client.
When you call the OT.initSession() pass in an options object with the sessionMigration property set to true:
const session = OT.initSession(
'12345', // your application ID
'1_MX40NzIwMzJ-clg1fn5-', // the session ID
{
sessionMigration: true,
},
);
Pass true into the setSessionMigration() method of the Session.Builder object you use to create a Session object:
mSession = new Session.Builder(this, apiKey, sessionId)
.setSessionMigration(true)
// other options
.build();
Set the sessionMigration property of an OTSessionSettings object to YES:
OTSessionSettings *settings = [[OTSessionSettings alloc] init];
settings.sessionMigration = YES;
Use this OTsessionSettings object when calling the [OTSession initWithApiKey:sessionId:delegate:settings:] method.
Set the SetSessionMigration property of a Session.Builder object to true:
session = new Session.Builder(context, apiKey, sessionId){ SetSessionMigration = true }.Build();
Call the otc_session_settings_set_session_migration() method, passing in OTC_TRUE as the second parameter:
otc_session_settings_set_session_migration(settings, OTC_TRUE);
Then pass the otc_session_settings struct as the settings parmeter in the call to the otc_session_new_with_settings() method.
Set the sessionMigration property of the options prop of the OTSession component to true:
<OTSession
options={{
sessionMigration: true,
// other options
}}
/>
If there are archives or broadcasts in progress for the original session, you can start new archives or broadcasts for the new session. In the case of broadcasts, you will need to send the new broadcast URL to clients consuming the broadcast.
If clients in the session cannot use version 2.30.0 or later to enable session migration, you will need to take steps to reconnect them after server rotation. When the servers for the session are rotated (one hour after the session notification event is sent), clients connected to the session that do not have session migration enabled will be forced to disconnect from the session. When your application server receives a server rotation session notification callback, it can take action to reconnect these clients to a new session:
Create a new Video API session using the Video API REST API or a Video API server SDK.
Send the session ID for the new session to the clients connected to the session. You may want to use the Video REST API or a Video API server SDK to send the signal to the connected clients. See this documentation.
The clients should immediately disconnect from the original session and reconnect to the new session.
For a more seamless transition between sessions and to minimize any potential reconnection time, clients can remain connected to the initial session and switch the video display before disconnecting from the initial session (upon connecting to the new session).
What is Video API server rotation? How frequently are Video API servers updated?
Software cloud scalability requires a continuous ability to rotate servers. Vonage maintains an 8-hour window to avoid excessive rotation of long-lived sessions. Rotations can happen daily.
There are a few main reasons for a media server to be rotated. The main reasons are maintenance, software updates, security patching, infrastructure servicing and elastic autoscaling:
Maintenance, security, and new software updates — Services are improved regularly. This can be updates to software, which is less frequent, security patches, or infrastructure updates.
Cloud servicing of troubled systems — Between infrastructure alerts, possible anomalies detection, or infrastructure procedures to refresh cloud systems, systems may be taken automatically out of service, respecting the 8-hour limits, to assure there are no prolonged issues.
Elastic autoscaling — Systems are also regularly spinning up and down to handle loads within regions and handle "follow the sun" capacities. As such, in the long term, lightly loaded servers may be scaled in to consolidate infrastructure.
Can I use the same session ID to reconnect once a session is disconnected due to server rotation?
Clients using version 2.30.0 or later of the Video API client SDKs can automatically stay connected to a session during server rotation. See Automatic session migration.
If all clients cannot use version 2.30.0 or later of the client SDKs, you can have them reconnect to a sesssion. Using a new session ID is recommended to assure that the new session is directed to a new server instance. If the session is disconnected due to server rotation, all clients will be disconnected. If the same session ID is used, the reconnection will be moved to a new server after the session is terminated, following the sessionDestroyed event.
