Room Connection

The Android SDK provides the following methods for room connection:

• init(): To initiate a room.
• connect(): To connect a client application to the virtual room.
• joinRoom(): To join a room quickly.
• disconnect(): To close the session and disconnect the client endpoint from the room.

Initiate a Room

An RTC session takes place in a virtual room hosted at EnableX. The Android SDK allows the client endpoint application to connect to it. The process starts with initializing a room object using the EnxRoom class.

Constructor: EnxRoom room = new EnxRoom( EnxRoomObserver-Instance, EnxStreamObserver-Instance)

After the room object is instantiated, call the EnxRoom.init() method.

Class: EnxRoom

Method: public void init( Context context )

Sample Code

EnxRoom room = new EnxRoom(
         EnxRoomObserver-Instance, 
         EnxStreamObserver-Instance
     );
room.init( activity-class-context );

Connect to a Room

The EnxRoom.connect() method connects a 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 bidirectional 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 causes the communication to fail. In such cases, EnableX offers the option to automatically reconnect with the room.

Note: The automatic reconnection 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.

Class: EnxRoom

Method: public void connect(String token, JSONObject roomInfo, JSONObject advanceOptions)

Callbacks:

Sample Code

String token = "XXX":
JSONObject roomInfo = {
	"allow_recnnect": true,
	"number_of_attempts": 3,
	"timeout_interval": 10000,
	"audio_only": true
}

JSONObject advancedOptions = {
	[
		{
			"id": " battery_updates",
    			"enable": true,
		},
		{
			"id": " notify-video-resolution-change",
    			"enable": true,
		}
	]
}

// Initiates a Room 
EnxRoom room = new EnxRoom(this, this, this); 

// Connects with Re-Connection & Advance Options
room.connect(token, roomInfo, advanceOptions);  

public void onRoomConnected(EnxRoom room, JSONObject roomMetaData) {
 // Connected. 
 //Callback received with room object and Room Meta JSON
}

public void onRoomError(JSONObject roomError) {
 // Connection failed. Find error
}

public void onUserConnected(JSONObject userData) {
 // Notification to all that a new user is connected. 
 // userData json has user information
}

Error Codes and Exceptions

Join a Room with a Stream

The typical process to connect to a room involves the following steps:

1. Initiate a room and connect to it.
2. Initiate streaming after connecting to the room, which requires you to check media accessibility.
3. Publish a 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 step, thus making it a complex process. The EnxRtc.joinRoom() method allows you to quickly join a room and get started without following every step of this procedure.

Class: EnxRtc

Method: public EnxStream joinRoom(String token, JSONObject publishStreamInfo, JSONObject roomInfo, JSONArray advanceOptions)

Returns: JSON object containing the details of the published local stream.

Sample Code

JSONObject publishStreamInfo = {
         video: true,
         audio: true,
         data: true,
         attributes: { name: "XX" }
};

JSONObject roomInfo = {
	allow_reconnect: true,
	number_of_attempts: 3,
	timeout_interval: 15,
	activeviews: "view",
	forceTurn: false,
	chat_only: false,
	playerConfiguration: {
		audiomute: true,
		videomute: true,
		bandwidth: true,
		screenshot: true,
		avatar: true,
		iconColor: "#FFFFFF",
		iconHeight: 30,
		iconWidth: 30,
		avatarHeight: 200,
		avatarWidth: 200
	}
};

JSONObject advanceOptions = [
	{​	"id": "notify-video-resolution-change",
		"enable": true
	}​​​​​,
	{​​​​​	"id": "battery_updates",
		"enable": true
	}
]

String token = "XXX";

EnxRtc enxRtc = new EnxRtc(
                  Current-Class-Context, 
                  EnxRoomOberver-Instance, 
                  EnxStreamObserver-Instance);


EnxStream localStream = enxRtc.joinRoom(token, publishStreamInfo, roomInfo, advanceOptions);

public void onRoomConnected(EnxRoom room, JSONObject roomMetaData) {
   // Connected. 
   //Callback received with room object and Room Meta JSON
}

public void onRoomError(JSONObject roomError) {
   // Connection failed. Find error
}

Disconnect from a Room

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

Class: EnxRoom

Method: public void disconnect()

Observers:

Sample Code

room.disconnect();

public void onRoomDisConnected( JSONObject jsonobject) {
 // You are disconnected
}

public void onUserDisconnected( JSONObject userData ) {
 // A user is disconnected
 // User Information of disconnected user
}

Error Codes and Exceptions

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 failure through the following callbacks:

Sample Code

public void onConnectionLost(JSONObject json){
	// Disconnected. Handle UI 
} 

public void onConnectionInterrupted(JSONObject json){
	// Interrupted. Handle UI 
}

EnableX provides the Auto-Reconnection functionality for disconnected endpoints to 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.

Callbacks

Sample Code

//To receive and handle reconnection events, 
// you need to pass an argument called roomInfo (its is an optional parameter) while connecting to the room through the room api - joinRoom() or connect(). For example,

JSONObject roomInfo = { 
    "allow_reconnect": true,
    "number_of_attempts": 3,
    "timeout_interval": 10000,
    "audio_only": false
};

//This will helps the end-point user to auto-reconnect to the same room.


public void onUserReconnectSuccess(EnxRoom room, JSONObject roomMetaData){
 // Got reconnected
}

public void onReconnect(String message){
 // Reconnecting 
}

Error Codes and Exceptions

Video Quality Adaption based on Bandwidth

EnableX offers Automatic Bandwidth Detection (ABWD) to ensure optimum audio or video communication based on the available bandwidth at the client endpoint. The ABWD detects a change in the available bandwidth when it cannot continue to support all the videos being received and notifies the client endpoint with callback onRoomBandwidthAlert. You can handle this event by reducing the number of Active Talker videos received or switching to audio-only mode. It helps users facing deplorable network conditions to go into audio-only mode without disrupting the session.

Callback: onRoomBandwidthAlert

• Notification is sent to the affected client endpoint when:
  • Bandwidth at the endpoint reduces to a level where all videos being received cannot be supported;
  • Bandwidth at the endpoint increases to a level where more videos than those currently being received can be supported.
• Notification is not triggered for any bandwidth fluctuation that does not affect the number of videos being received at the client endpoint.

Sample Code

// To receive callback
-public void onRoomBandwidthAlert(JSONObject jsonObject) {
	// jsonObject examplel given below
}

onRoomBandwidthAlert JSON Payload:

Sample Code

[
	{ 	"bandwidth": 240,
		"stream_bandwidth": 80,
		"number_of_videos": 2
	}
]