Session Management

The React Native SDK provides the following methods for managing video sessions:

• startRecord(): To start session recording on demand.
• stopRecord(): To stop session recording.
• hardMute(): To put a room into a hard mute state.
• hardUnmute(): To hard unmute a room.
• hardMuteAudio(): To hard mute the audio of a participant.
• hardMuteVideo(): To hard mute the video of a participant.
• hardUnMuteAudio(): To hard unmute the audio of a participant.
• hardUnMuteVideo(): To hard unmute the video of a participant.
• lockRoom(): To lock a room.
• unLockRoom(): To unlock a room.
• approveAwaitedUser(): To approve a user's entry.
• denyAwaitedUser(): To decline a user's entry to a session.
• dropUser(): To disconnect/force-drop one or more participants from a session.
• extendConferenceDuration(): To trigger session extension by a user.
• destroy(): To conclude an ongoing session.
• switchUserRole(): To change a participant's role.
• pinUsers(): To pin a user to the Active Talker list.
• unpinUsers(): To unpin a user from the Active Talker list.
• addSpotlightUsers(): To spotlight a user.
• removeSpotlightUsers(): To remove the spotlight from a user's stream.
• switchRoomMode(): To switch the room mode.

Record a Session

Using EnableX, you can get an RTC session recorded as an individual stream and transcoded it through a post-session service to create a single video file that can be retrieved and re-played using a video player. You can configure a room for auto-recording or invoke APIs to start recording when required.

Auto-Recording a Session

You can define a room to start recording automatically when a session starts in the room. For automatic recording, pass { settings: { auto_recording: true }} in the JSON payload while creating the room.

On-Demand Recording

Use the client API call to start and stop recording when needed. The API methods are accessible to moderators only. Therefore, on the moderator endpoint, you may need to create a UI to use the methods to start or stop recording a session.

Start Recording a Session

To start recording a session, use the Enx.startRecord() method. On successful initiation of the recording, the moderator receives a notification using startRecordingEvent callback. All other participants receive notifications using the roomRecordingOn callback.

Method: Enx.startRecord()

Callbacks

Sample Code

Enx.startRecord(); // Start Recording

// To moderator: Recording started
startRecordingEvent : event=>{
	// event = { result: 0, msg: "success"}
}

// To participants: Recording started
roomRecordingOn :event =>{
	// event = { result: 0, msg: "Room recording On"}
}

Note: There is not limit to the number of times a moderator can start recording during a session.

Stop Recording a Session

To stop recording a session, use the Enx.stopRecord() method. The moderator of the session receives the stopRecordingEvent callback notification. All other participants receive notifications using the roomRecordingOff callbacks.

Method: Enx.stopRecord()

Callbacks

Sample Code

Enx.stopRecord(); // Stop Recording

// To moderator: Recording stopped
stopRecordingEvent : event=>{
	// event = { result : 0, msg : "success"}
}

// To participants: Recording stopped
roomRecordingOff :event =>{
	// event = { result: 0, msg: "Room recording Off"}
}

Note: There is not limit to the number of times a moderator can stop recording during a session. A moderator can also stop recording in a room defined with the auto-recording feature. For information about obtaining the recording files, see Post-Session Reporting API.

Play a Recorded File

The recored files on the EnableX server are password protected. EnableX has implemented HTTP Basic authentication to secure the storage of recorded files. Therefore, a video player must provide access credentials to pass through the authentication process to play the file from the EnableX server.

Sample Code

npm install --save react-native-video

var username = 'Username';
var password = 'Password';
var videoFilePath = 'URL';

var basicAuth = ='Basic' + binaryToBase64(
	utf8.encode(username + ':' + password)
);

<Video source={{
	uri: videoFilePath,
	headers: {
		'Authorization': basicAuth
	}
}}

ref={(ref) => {
	this.player = ref
}}

onBuffer={this.onBuffer}                
onError={this.videoError}/>

Note: As an alternate way, download the files from the EnableX server to your server and play the files with or without any security measures you may like to deploy. Files are deleted after 72 hours of creation from from the EnableX storage. So, playing the files directly from the EnableX server beyond 72 hours is not guaranteed.

Hard Mute a Room

The Enx.hardMute() method allows moderators to hard-mute a room where all the participants are muted. A new participant joining a room in a hard-mute state is muted by default. The right to unmute a hard-mute room lies only with the moderator, and participants cannot unmute their local streams either. The moderator of the room is notified with the mutedAllUser callback. The participants of the room are notified with the hardMutedAll callback.

Method: Enx.hardMute()

Callbacks

Sample Code

Enx.hardMute (); // To hard mute room

// To Moderator - Room is hard muted 
mutedAllUser: event=>{
	// event= { result: 0, msg : "room muted" }
}

// To Participants - Room is hard muted 
hardMutedAll :event =>{
	// event= { msg : "Room is muted", status: true }
}

Hard Unmute a Room

To hard unmute a room, use the EnxRoom.hardUnmute() method. The moderator of the room is notified with the unmutedAllUser callback. All the participants are notified with the hardUnmuteAllUser callback.

Method: Enx.hardUnmute()

Callbacks

Sample Code

Enx.hardUnmute (); // To hard un-mute room

// To Moderator - Room is hard unmuted 
unMutedAllUser : event=>{
	// event= { result: 0, msg : "room un-muted" }
}

// To Participants - Room is hard unmuted 
hardUnmuteAllUser :event =>{
	// event= { msg : "Room is un-muted", status: false }
}

Hard Mute a Participant

A moderator may enforce hard muting on any participant in a room. The affected participant is not able to talk and publish video until the imposed state is lifted. The React Native toolkit offers hard muting audio and force-dropping the video of selected participants by using Enx.hardMuteAudio() and Enx.hardMuteVideo() methods. The affected participants are notified using onHardMutedAudio and onHardMutedVideo events. All other participants are notified about the mute status of the affected participants using onReceivedHardMuteAudio and onReceivedHardMuteVideo events.

Class: EnxStream

Methods: Enx.hardMuteAudio(), Enx.hardMuteVideo()

Callbacks

Sample Code

Enx.hardMuteAudio(streamId,clientId);	// To hard mute user's audio

// To Moderator: User's audio is hard muted
hardMuteAudio : event=>{
	// event = {result: 0 }
}

// To affected Participant: Your audio is hard muted
receivedHardMutedAudio :event =>{
	// { result: 0, clientId: "XXX", msg: "user audio hard muted" }
}

// Similar coding for User's video mute

Hard Unmute a Participant

The React Native toolkit offers hard unmuting of audio and video of selected participants by using Enx.hardUnMuteAudio() and Enx.hardUnMuteVideo() methods. The affected participant is notified using onHardUnMutedAudio and onHardUnMutedVideo events. All other participants are notified about the mute status of the affected participant using onReceivedHardUnMuteAudio and onReceivedHardUnMuteVideo events.

Class: EnxStream

Methods: Enx.hardUnMuteAudio(), Enx.hardUnMuteVideo()

Callbacks

Sample Code

Enx.hardUnmuteAudio(streamId,clientId);	// To hard unmute user's audio

// To Moderator: User's audio is hard unmuted
hardUnmuteAudio : event=>{
	// event = {result: 0 }
}

// To affected Participant: Your audio is hard unmuted
receivedHardUnmutedAudio :event =>{
	// { result: 0, clientId: "XXX", msg: "user audio hard unmuted" }
}

// Similar coding for User's video unmute

Room Entry Restrictions

Lock a Room

The Enx.lockRoom() method allows moderators to lock a room, which forbids new users from joining the session.

Class: Enx

Method: Enx.lockRoom()

Callbacks

Sample Code

Enx.lockRoom().       //Lock room 

ackLockRoom:event=>{
       // Moderator is acknowledged that room has been locked
              }
lockedRoom:event=>{
       // Participants are notified that room has been locked
              }

Error Codes and Exceptions

Unlock a Room

Moderators can unlock a room by using Enx.unLockRoom() method to allow subsequent users to join the session.

Class: Enx

Method: Enx.unLockRoom()

Callbacks

Sample Code

Enx.unLockRoom().    //Unlock room

ackUnLockRoom:event=>{
      // Moderator is acknowledged that room has been unlocked
              }
unLockedRoom:event=>{
        // Participants are notified that room has been unlocked
              }

Error Codes and Exceptions

Moderate Participants' Entry to a Session

In a Knock-enabled Room, users need to wait until the moderator of the room grants them permission to join the session.

Approve a User's Entry

The Enx.approveAwaitedUser() method allows moderators to approve a user's entry to a knock-enabled room.

Method: Enx.approveAwaitedUser(clientId)

Parameter: clientId: String. The client ID of the user awaiting moderator's approval.

Callbacks

Sample Code

Enx.approveAwaitedUser(clientId)

userAwaited:event=>{
   // Moderator is notified about awaited user
              }
roomAwaited:event=>{
     // Notification to the user when they await Moderator's permission to join Room
              }

Decline a User's Entry

The Enx.denyAwaitedUser() method is used to decline a user's entry to a session.

Method: Enx.denyAwaitedUser(clientId)

Parameter: clientId: String. The client ID of the user awaiting moderator's approval.

Callbacks

Sample Code

Enx.denyAwaitedUser(clientId)

userAwaited:event=>{
   // Moderator is notified about awaited user
              }
roomAwaited:event=>{
     // Notification to the user when they await Moderator's permission to join Room
              }

ackForDenyAwaitedUser:event=>{
    // User has been denied entry
              }

Disconnect a User

The Enx.dropUser() method allows moderators to disconnect/force-drop one or more participants from a session.

Method: Enx.dropUser(clientIds)

Parameter: clientIds: Array. Required
List of Client IDs of users to be disconnected from a session.

Callbacks

Sample Code

Enx.dropUser(clientIds)
ackDropUser:event=>{
     // Moderator is acknowledged that user has been dropped
              }
roomDisconnected:event=>{
      // Notification to the affected user with the reason to be disconnected from the Room
              }

Error Codes and Exceptions

Session Extension and Closure

Extend a Session

The duration of a room is limited. It is specified in minutes and defined during the room creation. This time is counted as soon as the first user joins the session. The session is dropped when the session duration elapses.

For practical reasons, a session may need to get extended. The EnxRoom.extendConferenceDuration() allows you to extend the duration of a session beyond the configured value. The extension process is explained below.

1.An Extension window opens 10 minutes before the specified closure time of a session. All the connected users are notified of this event. 2. Users can trigger an extension of the session by calling extendConferenceDuration(). Once triggered, the Extension Window is closed, thus preventing subsequent extension requests. 3. If the extension is not triggered, the final Extension window opens 5 minutes before the scheduled closure of the session. All the connected users are notified of this event. 4. The session can be extended by 10 to 30 minutes. The extended period can vary as there is no restriction on the number of times a session is extended. 5. When a session is extended, the previous steps are repeated.

Method: extendConferenceDuration(): To trigger extension by a user. Extension is possible only when an Extension Window is open.

Callbacks

Sample Code

// Listen to event to know when Extension Window is open
window.EnxRtc.addEventListner("onConferenceRemainingDuration", function (data) {}); // Extend Session

window.EnxRtc.extendConferenceDuration(); // Extend Session

// Listen when Session is extended
window.EnxRtc.addEventListner("onConferencessExtended", function (data) {});

Destroy a Session

The Enx.destroy() method allows moderators to conclude an ongoing session.

Method: Enx.destroy()

Callbacks

Sample Code

conferenceRemainingDuration:event =>{
	// Listen to event to know when Extension Window is open
}

Enx.extendConferenceDuration(); // Extend Session

conferencessExtended: event =>{
	// Listen when Session is extended
}

Error Codes and Exceptions

Switch Participant Roles

The EnxRoom.switchUserRole() method allows moderators to promote a participant to act as a moderator in the ongoing session. This newly appointed moderator gets access to moderator controls, and the former moderator becomes a participant in the session. If desired, the new moderator can grant the moderator role to another participant.

Method: Enx.switchUserRole(clientId)

Parameter: clientId: String. Client ID of the participant who is designated as the moderator.

Callbacks

Sample Code

Enx.switchUserRole(clientId); // Role Change Request from Moderator

acknowledgeSwitchUserRole: event => {
	// Moderator is acknowledged
}

userRoleChanged: event => {
	// All Participants are notified - event jsonObject
	/*
	{	"moderator": false, // You are not a moderator
		"clientId": "XXX"   // New Moderator's Client ID
	}
	*/
    
	// New Moderator is notified  - jsonObject
	/*
	{   "moderator": true,  // You are a moderator
		"clientId": "XXX",  // New Moderator's Client ID i.e. You
		"raisedHands":[],   // List of Client IDs requested Floor Access
		"approvedHands":[]  // List of Client IDs with Floor Access
	}
	*/
}

Pin a User

The EnxRoom.pinUsers() method allows moderators to pin a user to the Active Talker list irrespective of the user's activity level. A pinned user's stream is always published in the room, even if the user is not talking. The inactive pinned users are placed in the Active Talker list after the actively talking users in a descending order based on their activity level, with the most active talker on top of the list. Based on the Room configuration, the total number of pinned users in a room is restricted to (max_active_talkers – 1).

On joining a room, a user is notified with Room Meta Information through the onRoomConnected event. This event provides the list of pinned users as "pinnedUsers": [ /*client-ids*/ ].

Class: Enx

Method: Enx.pinUsers(clientIds)

Parameter: clientIds: String. Client ID of the participant who is designated as the moderator.

Callbacks

Sample Code

ackPinUsers:event=>{
   // Moderator is acknowledged for pinning user

              }

pinnedUsers:event=>{
   // Everyone is notified wtih updated pinned lis 
              }

Error Codes and Exceptions

Unpin a User

The Enx.unpinUsers() method is used to unpin the users.

Class: Enx

Method: Enx.unpinUsers(clientIds)

Parameter: clientIds: String. Client ID of the participant who is designated as the moderator.

Callbacks

Sample Code

ackUnpinUsers:event=>{
     // Moderator is acknowledged for unpinning user

              }

pinnedUsers:event=>{
   // Everyone is notified wtih updated pinned lis 
              }

Error Codes and Exceptions

Spotlight a User

The Enx.addSpotlightUsers() method method allows the moderator to spotlight a user, pushing the user's stream to the top of the Active Talker List irrespective of the user's activity level. Spotlighting publishes the chosen user's stream in the room even if the user is not talking. The moderator can spotlight as many users as max_active_talkers defined in the Room Configuration.

On joining a room, a user is notified with Room Meta Information through the onRoomConnected event. This event provides the list of spotlightUsers.

Subsequent active talkers list (JSON) received with the onActiveTalkersUpdated callback includes a "spotlight" key with a boolean value. This key is set to true for spotlighted users.

Class: Enx

Method: Enx.addSpotlightUsers(clientIds)

Parameter: clientIds: Array. An array of Client IDs of users whose streams are spotlighted or removed from the spotlight.

Callbacks

Sample Code

ackAddSpotlightUsers
updateSpotlightUsers

Enx.addSpotlightUsers(clientIds)    //Add spotlight to user


ackAddSpotlightUsers:event=>{
 // Moderator who spotlights users is acknowledged

              }

updateSpotlightUsers:event=>{
// Everyone is notified with updated Spotlight list
 
              }

Remove the Spotlight from a User

The Enx.removeSpotlightUsers() method removes the spotlight from user streams.

Class: Enx

Method: Enx.removeSpotlightUsers(clientIds)

Parameter: clientIds: Array. An array of Client IDs of users whose streams are spotlighted or removed from the spotlight.

Callbacks

Sample Code

ackRemoveSpotlightUsers
updateSpotlightUsers

Enx.removeSpotlightUsers(clientIds) //Remove spotlight to user


ackRemoveSpotlightUsers:event=>{
 // Moderator who removes users from Spotlight is acknowledged 

              }

updateSpotlightUsers:event=>{
// Everyone is notified with updated Spotlight list
 
              }

Switch the Room Mode

A room defined with either group or lecture mode may be switched to the other mode at runtime during an ongoing session. The EnxRoom.switchRoomMode() method is executed by the moderator to switch to another mode instantly.

When a room is switched from group or lecture mode:

• The audio/video streams of all the participants are dropped from the room with a notification to each participant.
• All the features of Lecture mode, such as Floor Access Control are activated.

On the other hand, when a room is switched from group or lecture mode:

• A notification is sent to each participant, allowing the participants to publish their audio/video streams into the room.
• Due to privacy concerns, SDK does not automatically start publishing audio/video streams in such cases, but application developers must decide whether to publish them automatically or to prompt the participants to publish them.

Class: Enx

Method: Enx.switchRoomMode(roomMode)

Parameter: roomMode: String. Enumerated values lecture, group.
Use the mode that you want to switch to.

Callbacks

Sample Code

Enx.switchRoomMode(roomMode). //To switch to group mode, mode=group/lecture

ackSwitchedRoom:event=>{
 // Moderator is acknowledged
 
              }
RoomModeSwitched:event=>{
 // Everyone is notified
 
              }

Error Codes and Exceptions