Room Connection: iOS SDK – Video API

Table of Contents

• Initiate a Room
• Connect to Room
• Join a Room with Stream
• Disconnect from a Room
• Handle Network Disconnection & Reconnection

Initiate a Room

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

Class: EnxRoom

Method: -(instancetype)init;

EnxRoom *room = [[EnxRoom alloc] init];

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: - (void)connect:(NSString *)token roomInfo:(NSDictionary *)roomInfo advanceOptions:(NSArray *)advanceOption;

Parameters:

• token: String. A JWT Token to connect to the Room as received using Server 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 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.
  • 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. Set to true to force Video Streams through a TURN Server.
  • chat_only: Boolean. Default: false. Set to true to enable only text-chat and disable audio-video communications.
  • 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.
    • pinned: Boolean. Default: false. Set to true to show pinned user icon.
• advanceOptions – Optional. 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.

Delegate Methods:

• - room:didConnect:  – Acknowledgment to the Client endpoint when it gets connected to the Room.
• - room:didError:– Acknowledgment to the Client endpoint when it fails to connect to the Room.
• - room:userDidJoined: – Notification to everyone in the Room when a new user is connected to the Room.
• – room:didRoomAwaited– 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" }.

NSString *token = "XXX";
NSDictionary *roomInfo = { // Re-Connect Options
 @"allow_reconnect": true,
 @"number_of_attempts": 3,
 @"timeout_interval": 10000,
 @"audio_only": false
}; 

NSDictionary *advanceDict= @{
 @"id":@"battery_updates",
 @"enable":@YES
};

NSMutableArray *advanceOptionArray = [[NSMutableArray alloc] init];

[advanceOptionArray addObject:advanceDict];

advanceDict= @{
 @"id":@"notify-video-resolution-change",
 @"enable":@YES
};

[advanceOptionArray addObject:advanceDict]; 

// Initiates Room 
EnxRoom *room = [[EnxRoom alloc] init];

// Connects with Re-Connection & Advance Options
[room connect:token roomInfo:roomInfo advanceOptions:advanveOptionArray ];
 

//Delegate methods
-(void)room:(EnxRoom *)room didConnect:(NSDictionary *)roomMetadata{
      // Connected. Delegate receives room instance and Room Meta JSON.
}

-(void)room:(EnxRoom *)room didError:(NSString *)reason{
 // Connection failed. Find error
}

-(void)room:(EnxRoom *)room userDidJoined:(NSArray *)Data{
 // A new user connected. user JSON has user information
}

-(void)room:(EnxRoom *)room didActiveTalkerList:(NSArray *)Data{
      // List of talkers in the Room
      // Received after room connected.
}

Error Codes / Exceptions:

Code	Description
5086	Unable 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: -(EnxStream *)joinRoom:(NSString *)token delegate:(id)delegate PublishStreamInfo: (NSDictionary *)publishStreamInfo;

Parameters:

• token – String. A JWT Token to connect to the Room as received using Server API Call via Application Server.
• delegate: EnxRoomDelegate object is the delegate for the EnxRoom object.
• publishStreamInfo– Optional. Stream Initialization Meta Info.

Returns: EnxStream – Published Local Stream JSON Object.

NSDictionary* publishStreamInfo = {
         video: true,
         audio: true,
         data: true,
         attributes: { name: "XX" }
}

NSString* token = "XXX";

EnxRtc *enxRtc = [[EnxRtc alloc] init];
EnxStream *localStream = [enxRtc joinRoom:token delegate:self publishStreamInfo:publishStreamInfo];

//Delegate methods
-(void)room:(EnxRoom *)room didConnect:(NSDictionary *)roomMetadata{
	// Connected. Delegate receives room instance and Room Meta JSON.
}

-(void)room:(EnxRoom *)room didError:(NSString *)reason{
	// 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: - (void)disconnect;

Delegate Methods:

• –room:didRoomDisconnect: – Acknowledgment to the user when disconnected. The Callback allows you to update the UI of the user post disconnect.
• –room:userDidDisconnected: – 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];

- (void)room:(EnxRoom *)room didRoomDisconnect:(NSArray * _Nullable)response {
    // You are disconnected
}
-(void)room:(EnxRoom *)room userDidDisconnected:(NSArray *)Data{
     // A user is disconnected
     // Data - User Information of disconnected user
}

Error Codes / Exceptions

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

Handle 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 Callbacks:

Delegate Methods:

• - room:didConnectionLost: – Notification to the Client endpoint when the endpoint loses network connection.
• - room:didConnectionInterrupted: – Notification to the Client endpoint when the connection is interrupted e.g Switch from WiFi to 4G and vice versa.

- (void)room:(EnxRoom*)room didConnectionLost:(NSArray*)data {
	// Disconnected. Handle UI 
} 

- (void)room:(EnxRoom*)room didConnectionInterrupted:(NSArray*)data{
	// Interrupted. Handle UI 
}

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:

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

Delegate Methods:

• - room:didUserReconnectSuccess:– Notification to the user when the Client endpoint successfully gets reconnected with EnableX.
• - room:didReconnect: – 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,

NSDictionary *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.

NSDictionary *advanceDict= @{
	@"id":@"battery_updates",
	@"enable":@YES
};

NSMutableArray *advanceOptionArray = [[NSMutableArray alloc] init];

[advanceOptionArray addObject:advanceDict];

advanceDict= @{
	@"id":@"notify-video-resolution-change",
	@"enable":@YES
};

[advanceOptionArray addObject:advanceDict]; 


-(void)room:(EnxRoom*)room didUserReconnectSuccess:(NSDictionary*)data{
	// Got reconnected
}

- (void)room:(EnxRoom *)room didReconnect:(NSString *)reason{
	// Reconnecting 
}

Error Codes / Exceptions:

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

---