Room Connection

A client endpoint must connect to a video room for Real-Time Communication (RTC), among others connected to the same room. Network fluctuations may disconnect an endpoint from the room. However, staying connected to the video room for effective communication is essential.

• connect(): To connect a client application to the virtual room.
• joinRoom(): To join a room quickly.

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 must pass a created token using the Create Token and an optional Speaker ID to play the video.

Sample Code

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

Connect to a Room

The EnxRoom.connect() method connects a client application to a 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 bidirectional communication channel over a web socket.

As the communication takes place over web sockets using socket events, any network issue leading to the disconnection of the web sockets causes the communication to fail. In such cases, EnableX offers the option to automatically reconnect with the room.

Note: The automatic reconenction is not applicable when:

• The last participant has disconnected from the adhoc room.

• The moderator has dropped the participant from the room.

• The participant has explicitly disconnected from the room.

• Method: EnxRoom.connect(ReConnectOpt)

• Parameters:

  • ReConnectOpt : JSON Object. Optional. Reconnection Options.
    • allow_reconnect : Boolean. Set false to deny auto-reconnect. Default is true.
    • number_of_attempts : Number. Maximum number of Re-attempts done by Client Endpoint to reconnect. Range: 1 - Any number. Default Max Value: 3. The maximum number of attempts that a client endpoint can try to reconnect.
    • timeout_interval : Number. The timeout interval in milliseconds required by Client Endpoint to wait before attempting to reconnect.

• Event Notificationss:

  • room-connected : Acknowledgment to a client endpoint when it is connected to a room with complete runtime Meta Information of the Room. However, if the room is knock-enabled or requires the moderator to join first, the users need to wait till they are allowed to join the session.
  • room-error : Acknowledgment to the client endpoint when it fails to connect to a room.
  • user-connected : Notification to everyone in a room when a new user is connected to the room.
  • user-awaited : Notification to a moderator when a user awaits the moderator's permission to enter a room.
  • room-allowed : Notification to a user when the user is allowed to join the session after waiting in a knock-enabled or wait-for-moderator-enabled room.
  • active-talkers-updated : Notification to a client endpoint about the list of talkers after the client endpoint receives the room-connected event. For more information, see how to handle Active Talkers.

Sample Code

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 );		// Connects Room 

/*
// Alternate ways to connect Room 
room.connect();				// Default reconnection option.
room.connect({});			// Default reconnection option.
room.connect({"allow_recnnect": false});// Without reconnection option. 
*/

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

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

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

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

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

Error Codes

Join a Room With or Without a Stream

Below is a typical process to connect to a room:

1. Initiate a room and connect to it.
2. Initiate streaming after connecting to a room, which requires you to check the media accessibility.
3. Publish the 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 following these steps.

• Method: EnxRtc.joinRoom( Token, StreamOpt, Callback, ReConnectOpt )
• Parameters:
  • Token: String. A JWT to connect to the room. The JWT is received using the Server API call throug the application server.
  • StreamOpt : String. Optional. Stream Initialization Meta Information. If you do not want to publish your local stream, pass a blank JSON object, that is, { }
  • ReConnectOpt : JSON Object. Optional. Reconnection Options.
    • allow_reconnect : Boolean. Set false to deny auto-reconnect. Default is true.
    • number_of_attempts : Number. Maximum number of Re-attempts done by Client Endpoint to reconnect. Range: 1 - Any number. Defautl Max Value: 3. The maximum number of attempts that a client endpoint can try to reconnect.
    • timeout_interval : Number. The timeout interval in milliseconds required by Client Endpoint to wait before attempting to reconnect.
• Returns: Published Local Stream JSON Object

Sample Code

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 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

Disconnect from a Room

The EnxRoom.disconnect() method closes the session and disconnects the client endpoints from the room. The media and signaling sockets are also released in this process.

• Method: EnxRoom.disconnect()
• Event Notifications:
  • room-disconnected : Acknowledgment to a user when the user is disconnected. The callback allows you to update the UI of the user post disconnection.
  • user-disconnected : Notification to everyone in a room when a user is disconnected from the room. The callback allows you to update the UI of other connected users.

Sample Code

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

Handle Network Disconnection and Reconnection

A client endpoint is connected with EnableX over a secured web socket, which is susceptible to network failures. The client endpoint is notified of the network failure and reconnection status through the following callbacks:

• Event Notification:
  • network-disconnected: Notification to a client endpoint when the endpoint is disconnected.
  • network-reconnected : Notification to the user when the client endpoint is successfully reconnected.
  • network-reconnect-timeout : Notification to the user when the client endpoint fails to reconnect within the specified period of time.
  • network-reconnect-failed : Notification to the user when the client endpoint fails to reconnect due to other reasons.

Sample Code: Network Disconnected

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

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

• The last participant has disconnected from the adhoc room.
• The moderator has dropped the participant from the room.
• The participant has explicitly disconnected from the room using the EnxRoom.disconnect() method.

To receive and handle reconnection events, you need to add reconnection options while connecting to the room Re-connect options. This helps the endpoint to automatically reconnect. Use it with joinRoom() or connect().

Sample Code: Network Reconnection

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){  
     // Reconnect attempt timed-out 
});

room.addEventListener('network-reconnect-failed', function(event){
     // Reconnect attempt failed 
});

Error Codes