Room Connection: Web SDK – Video API

An Client End Point must connect to a Video Room for Real Time Communication among others connected to the same Room. There may be network fluctuation disconnects the End Point from the Room. Its important to connect and stay connected to the Video Room for effective communication.

Table of Contents

• Initiate a Room
• Connect to Room
• Join a Room without or with Stream
• Disconnect from a Room
• Handle Network Disconnection & Reconnections

Initiate a Room

An RTC session takes place in a Virtual Room hosted at EnableX and the Web SDK allows the Client endpoint application to connect to it. The process starts with initializing a Room Object using the EnxRoom Class.

To initialize a Room, you need to pass a token that is created using Create Room Server API and an optional Speaker ID to play the Video.

var room = EnxRtc.EnxRoom({token:'xxxx', speakerId: 'SPEAKER_ID' });

Connect to Room

The EnxRoom.connect() method connects the client application to the virtual Room hosted on the EnableX server where the RTC session takes place. After initializing the room, the client endpoint must connect to the room to establish a bi-directional communication channel over a Web Socket.  

As the communication takes place over the Web Sockets using Socket Events, any network issue leading to the disconnection of the Web Sockets would cause the communication to fail. In such cases, EnableX offers the option to Auto-Reconnect.

Note that Auto-Reconnect is not applicable under the following circumstances:

• The last participant disconnected from Adhoc Room.
• The participant is dropped from the Room by the Moderator.
• The user disconnects explicitly.

Class: EnxRoom

Method: EnxRoom.connect(ReConnectOpt)

Parameters:

ReConnectOpt – Optional. JSON Object with Reconnection Options. JSON keys are explained below:

• allow_reconnect: Boolean. Default: true. Set to true to enable Auto-Reconnect feature. When set to false, the Client endpoint does not try to reconnect to EnableX.
• number_of_attempts: Numeric. Min Value: 1. Max Value: Not specified, use any number. Default: 3. A maximum number of attempts made by the Client endpoint to reconnect to EnableX.
• timeout_interval: Numeric. Timeout Interval in Millisecond required by the Client endpoint to wait before attempting to reconnect.

Event Notifications:

• room-connected – Acknowledgment to the Client endpoint when it gets connected to the Room with complete run-time Meta Information of the Room. However, if the Room is knock-enabled or requires Moderator to join first, the user needs to wait till they are allowed to join the Session.
• room-error – Acknowledgment to the Client endpoint when it fails to connect to the Room.
• user-connected – Notification to everyone in the Room when a new user is connected to the Room.
• user-awaited – Notification to the Moderator when a user awaits their permission to enter the Room.
• room-allowed – Notification to the user when they are allowed to join the session after waiting in a knock-enabled or wait-for-moderator enabled Room.
• active-talkers-updated – Notification to the Client Endpoint with list of Talkers after receiving room-connected event. Refer how to handle Active Talkers

var initOpt = { "token": "XXX" };
var room = EnxRtc.EnxRoom(initOpt); // Initiates Room 

var reConnectOpt = {
    "allow_reconnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
};

room.connect( reConnectOpt );

/*
// Alternate Connection 
room.connect();    // Connects with Default Re-Connection Option
room.connect({})   // Connects with Default Re-Connection Option 
room.connect({"allow_recnnect": false})   // Connects  without Re-Connection feature 
*/

room.addEventListener("room-connected", function(event) {
     // Connected. event receives Room Meta JSON
});

room.addEventListener("room-error", function(error) {
     // Connection failed. Find error
});
 
room.addEventListener("room-allowed", function(event) {
	// User is allowed into the room after being awaited
});

room.addEventListener("user-connected", function(event, user) {
     // A new user connected. user JSON has user information
});

room.addEventListener("user-awaited", function(event, user) {
     // A new user awaited permission to get connected
     // user JSON has user information
});

room.addEventListener("active-talkers-updated", function(event) {
     // List of talkers in the Room
     // Received after room-connected
});

Error Codes / Exceptions

Code	Description
1130	Wait for Moderator to join first.
1171	Room not connected.
1172	Failed to connect to the Room.

Join a Room without or with Stream

A typical process to connect to a room is as follows: 

1. Initiate a room and connect to it. 
2. Initiate streaming after connecting which requires you to check media accessibility.
3. Publish local stream.
4. Check if the stream is successfully published. 

To successfully join a Room, you need to ensure the success of each step before proceeding to the next thus making it a complex process.

The EnxRtc.joinRoom() method allows you to quickly join a room and get started without having to follow the above procedure step by step.

Class: EnxRtc

Method: EnxRtc.joinRoom( Token, StreamOpt, Callback, ReConnectOpt )

Parameters:

• Token – String. A JWT Token to connect to the Room as received using Server API Call via Application Server.
• StreamOpt – Stream Initialization Meta Info. Optional. If you don’t want to publish your local Stream, pass blank JSON object i.e { }.
• ReConnectOpt – Optional. JSON Object with Reconnection Options. JSON keys are explained below:
  • allow_reconnect: Boolean. Default: true. Set to true to enable Auto-Reconnect feature. When set to false, Client endpoint does not try to reconnect to EnableX.
  • number_of_attempts: Numeric. Min Value: 1. Max Value: Not specified, use any number. Default: 3. A maximum number of attempts made by the Client endpoint to reconnect to EnableX.
  • timeout_interval: Numeric. Timeout Interval in Millisecond required by the Client endpoint to wait before attempting to reconnect.

Returns: Published Local Stream JSON Object

var VideoSize = {
     "HD": [320, 180, 1280, 720], 
     "SD": [320, 180, 640, 480],
     "LD": [80, 45, 640, 360]
};

var StreamOpt = {
         video: true,
         audio: true,
         data: true,
         videoSize: VideoSize.HD,
         attributes: { name: "XX" }
};

var reConnectOpt = {
    "allow_recnnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
}; 

localStream = EnxRtc.joinRoom(Token, StreamOpt, function (success, error) {
     if (error && error != null) {
         // Look for error.type and error.msg.name to handle Exception
         if(error.type == "media-access-denied") {
              // Media Media Inaccessibility
         }
     }
    
     if (success && success != null) { 
		room = success.room;
		if (room.waitRoom && room.me.role != "moderator") {
			// Wait for Moderator
		} else {
			remoteStreams = success.room.streams; 
		}
     }
 },
 reConnectOpt
)

Error Codes / Exceptions

Code	Description
1000	Unsupported browser.
1142	OverconstrainedError: Invalid Device Id.
1130	Moderator not present/Wait for Moderator.
1144	NotAllowedError: The request is not allowed by the user agent or the platform in the current context.
1145	NotReadableError: Could not start video source.
1146	TypeError: At least one of the audio and video must be requested.
1149	One of the constraints (Height, Width, Device Id) is not satisfied.
1153	Non-supported browser.
1152	Only Audio-only calls are allowed with your current browser version.
1170	Feature is not supported under current Service subscription or not enabled in the Room’s setting.
1171	Room not connected.
1172	Failed to connect Room.
1176	Moderator declined right to control media devices.
2109	Allowed Concurrent Session limit has reached. This is applicable only when Concurrent Session Capacity is restricted.
2108	Another Session is active with the same User License. This is applicable only to Agency License based Billing Model
2110	Room is defined with a non-existing or inactive License. This is applicable only to Agency License based Billing Model

Disconnect from a Room

The EnxRoom.disconnect() method is used to close the session and disconnect the client endpoint from the Room. The media and signaling sockets are also released in this process.  

Class: EnxRoom

Method: EnxRoom.disconnect() – No parameter required.

Notification Events:

• room-disconnected – Acknowledgment to the user when disconnected. The Callback allows you to update the UI of the user post disconnect.
• user-disconnected – Notification to everyone in the Room when a user gets disconnected. The Callback allows you to update the UI of other connected users.

room.disconnect();

room.addEventListener("room-disconnected", function(event) {
     // You are disconnected
});

room.addEventListener("user-disconnected", function(event) {
     // One user is disconnected
     // event - User Information of disconnected user
 });

Error Codes / Exceptions:

Code	Reason
2001	Disconnected by Moderator.
2002	Unexpected disconnection.
2003	Conference expired.
2004	Network failure.
2005	Media handshake failure.
2006	Room access denied.

Handle Network Disconnection & Reconnection

A Client endpoint is connected with EnableX over Secured Web Socket, which is susceptible to network failures. The Client endpoint is notified of the failure through the following Callback:

Event Notification:

network-disconnected – Notification to the Client Endpoint when Endpoint gets disconnected.

room.addEventListener('network-disconnected', function(event){ 
      // Handle UI or prompt user. 
});

For disconnected endpoints, EnableX provides Auto-Reconnection functionality to ensure a better user experience. To use the Auto-Reconnection feature, you must Connect to Room with Reconnection options. Note that Auto-Reconnect is not applicable under the following circumstances:

• Last Participant disconnected from Adhoc Room.
• User is dropped from Room by Moderator.
• User disconnects explicitly using EnxRoom.disconnect() method.

Event Notifications:

• network-reconnected – Notification to the user when the Client Endpoint successfully gets reconnected with EnableX.
• network-reconnect-timeout – Notification to the user when the Client Endpoint fails to reconnect within the specified time period.
• network-reconnect-failed – Notification to the user when the Client Endpoint fails to reconnect due to other reasons.

//To receive and handle reconnection events, 
// you need to add re-connect options while connecting to the room

// Re-connect options. This helps the end-point to auto-reconnect.
// Use it with joinRoom() or connect()

var reConnectOpt = {              
    "allow_reconnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000
}; 

room.addEventListener('network-reconnected', function(event){
     // Got reconnected
});
 
room.addEventListener('network-reconnect-timeout', function(event){  
     // Re-Connect Attempt timed-out 
});

room.addEventListener('network-reconnect-failed', function(event){
     // Re-Connect Attempt failed 
});

Error Codes / Exceptions

Code	Description
1163	Network disconnected.
1164	Network reconnected.
1165	Network reconnect attempt timed out.
1167	Failed to publish and subscribe to streams after reconnection.
1178	Auto-Reconnection option not available for a Room with no participant.
4118	Reconnect failed as the Room is deleted.

---