Room Connection: Android SDK – Video API

Table of Contents

Initiate a Room

An RTC session takes place in a Virtual Room hosted on the Portal and 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 EnxRoom.init() method.

Class: EnxRoom

Method: public void init( Context context )

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

Connect to Room

The EnxRoom.connect() method connects the client application to the virtual Room hosted on the Video 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, The Portal 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: public void connect(String token, JSONObject roomInfo, JSONObject advanceOptions)

Parameters: 

  • token: String. A JWT Token to connect to the Room as received using Video API Call via Application Server.
  • roomInfo – 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 the Portal.
    • 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 the Portal.
    • timeout_interval: Numeric. Timeout Interval in Millisecond required by the Client endpoint to wait before attempting to reconnect.
    • audio_only: Boolean. Set to true if you want to join as an audio-only call.
  • advanceOptions – Optional. JSON Object with an array of advanced options. Each element of the array consists of a key-value pair as given below:
    • battery_updates: Boolean. Set to true to enable Auto-Battery Update feature.
    • notify-video-resolution-change: Boolean. Set to true to enable Video Resolution Change Notification feature.

Callbacks:

  • onRoomConnected – Acknowledgment to the Client endpoint when it gets connected to the Room.
  • onRoomError – Acknowledgment to the Client endpoint when it fails to connect to the Room.
  • onUserConnected – Notification to everyone in the Room when a new user is connected to the Room.
  • onRoomAwaited – Notification to the Client endpoint when it awaits the Moderator’s permission to enter a Knock-enabled Room or awaits the Moderator to enter the Room first in a Wait-for-Moderator enabled Room. The event’s JSON structure provides information on whether the Room is Knock-enabled { "event_type": "knock" } or Wait-for-Moderator enabled { "event_type": "wait_for_moderator" }.
  • onUserAwaited – Notification to the Moderator when a user awaits their permission to enter the Room. Refer to Moderate Participant’s entry to a Session for more details.
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 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 / Exceptions:

CodeDescription
5086Unable to connect to Room.

Join a Room 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: public EnxStream joinRoom(String token, JSONObject publishStreamInfo, JSONObject roomInfo, JSONArray advanceOptions)

Parameters:

  • token – String. A JWT Token to connect to the Room as received using Video API Call via Application Server.
  • publishStreamInfo– Optional. Stream Initialization Meta Info.
  • roomInfo – 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 the Portal.
    • 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 the Portal.
    • timeout_interval: Numeric. Timeout Interval in Millisecond required by the Client endpoint to wait before attempting to reconnect.
    • activeviews: Enum. Values: list or view. Set to view to get a predefined view of all the video Streams in a session. Set to list to get individual streams to create your own view with the video streams.
    • forceTurn: Boolean. Default: false. If enabled, Video Streams are forced through a TURN Server.
    • chat_only: Boolean. Default: false. Set to true to allow only text-chat in the Stream thus disabling audio/video streams.
    • playerConfiguration: JSON Object with Video Player configurations.
      • audiomute: Boolean. Default: true. Set to true to show and false to hide the Audio Mute/Unmute button.
      • videomute: Boolean. Default: true. Set to true to show and false to hide the Video Mute/Unmute button.
      • bandwidth: Boolean. Default: true. Set to true to show and false hide the Low-Bandwidth notification button.
      • screenshot: Boolean. Default: true. Set to true to show and false to hide the Screenshot button.
      • avatar: Boolean. Default: true. Set true to show and false to hide Avatar for No-Video Stream.
      • iconColor: String. Default: #FFFFFF. HEX color code for icons.
      • iconHeight: Number. Default: 30. Icon height in pixel.
      • iconWidth: Number. Default: 30. Icon width in pixel.
      • avatarHeight: Number. Default: 200. Avatar height in pixel.
      • avatarWidth: Number. Default: 200. Avatar width in pixel.
  • advanceOptions – Optional. JSON Object with an array of advanced options. Each element of the array consists of a key-value pair as given below:
    • battery_updates: Boolean. Set to true to enable Auto-Battery Updates feature.
    • notify-video-resolution-change: Boolean. Set to true to enable Video Resolution Change Notification feature.

Returns: Published Local Stream JSON object.

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 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: public void disconnect() – No parameter required.

Observers:

  • onRoomDisconnected – Acknowledgment to the user when disconnected. The Callback allows you to update the UI of the user post disconnect.
  • onUserDisconnected – 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();

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

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

Error Codes / Exceptions

CodeDescription
5031Repeated disconnect() call made while previous disconnection request is in process.
5032When the user tries to disconnect after getting disconnected from the Room.

Handle Disconnection & Reconnection

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

Callbacks:

  • onConnectionLost – Notification to the Client endpoint when the endpoint loses network connection.
  • onConnectionInterrupted – Notification to the Client endpoint when the connection is interrupted e.g Switch from WiFi to 4G and vice versa.
public void onConnectionLost(JSONObject json){
	// Disconnected. Handle UI 
} 

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

For disconnected endpoints, Portal 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:

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

Callbacks:

  • onUserReconnectSuccess – Notification to the user when the Client endpoint successfully gets reconnected with the Portal.
  • onReconnect – Notification to the user when the Client endpoint attempts to reconnect within the given time period.
//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 / Exceptions

CodeDescription
5073Connection is switched to the current network.
5074Network disconnected. Reconnection attempt timed-out.
5086When any method is called while the Room is not connected.
5087Reconnection failed.

← Create Local Stream

Index

Quality Adaption with Bandwidth →