Waiting Lobby - Flutter

Overview

With our Flutter SDK, you can implement a waiting lobby feature, which allows the host to control which participants can join the room by allowing or denying access. Here are the steps for implementing the waiting lobby.

Generating Tokens in Your Backend

Your server should generate access tokens using your API key and secret. Two different tokens need to be generated with different permissions:

HOST Token Payload

{
  // ...
  apikey: API_KEY, // Your API key
  permissions: ['allow_join'], // Permission to directly join the room
  // ...
}

GUEST Token Payload

{
  // ...
  apikey: API_KEY, // Your API key
  permissions: ['ask_join'], // Permission to ask the host for permission to join the room
  // ...
}

Explanation of parameters:

• apikey (Mandatory): Your API key generated from the VideoSDK Dashboard, which can be obtained here.

• permissions (Mandatory): Permissions that control participant activity. Available permissions include:

  • allow_join: Participants are allowed to join the room directly.
  • ask_join: Participants need to ask for permission to join the room. Participants with the allow_join permission can accept or reject others' join requests.
  • allow_mod: Participants are allowed to toggle webcam and mic of other participants.

Then, sign this payload with your SECRET KEY and use the HS256 algorithm. For more details on authentication and tokens, refer to Authentication and Tokens.

Generating Room ID

With the tokens ready, you can now obtain the roomId from the VideoSDK's rooms API, which can be found in Create a Room.

Refer to Generating Room ID for generating the room ID.

Initialization of Room

Create the room with VideoSDK.createRoom(), passing the token of the participant who is joining. The token you provide here decides whether the participant joins the room directly or waits in the lobby, so provide the allow_join token to a host and the ask_join token to a guest.

Also pass your own unique participantId. A waiting guest compares it with the participantId of Events.entryResponded to recognise the response to its own request.

For detailed configuration options, check Initialization of Room.

// If a participant joins as a host, provide them with the "allow_join" permission token.
// Otherwise, provide the "ask_join" permission token.
String token = isHost ? "allow_join token will be here" : "ask_join token will be here";

// Your own unique id for this participant, for example the user id in your database
String myParticipantId = "unique-participant-id";

Room room = VideoSDK.createRoom(
  roomId: "abcd-efgh-hijk",
  token: token,
  participantName: "John Doe",
  participantId: myParticipantId,
  micEnabled: true,
  camEnabled: true,
);

// Add the event handlers from the next section here, before you join.

// On Android, the SDK does not ask for camera or microphone permission.
await VideoSDK.requestPermissions();

try {
  await room.join();
} on VideoSDKError catch (error) {
  print("Join failed: ${error.code} ${error.name}");
}

note

A participant joining with the ask_join token does not enter the room when join() is called, and join() does not complete while the participant waits. It completes, and the Events.roomJoined event is emitted, once the host allows the request. Add your event handlers before you call join(), so the guest does not miss the host's response.

Events associated with Waiting Lobby

The following events are received when a participant tries to join the room.

• When a participant joins as a host, they will receive an Events.entryRequested event whenever a guest participant tries to join the room. The event provides a Map holding the participantId and name of the guest, along with the allow and deny functions the host calls to respond to the request. allow() and deny() return a Future that throws a VideoSDKError if the response cannot be sent, so await them inside try/catch. You can also answer later with room.respondEntry(participantId, decision), where decision is "allowed" or "denied".

• When the host responds to a request, both the host and the guest will receive an Events.entryResponded event with the participantId of the guest and a decision of either allowed or denied.

// Called on the host when a guest requests to join the room
room.on(Events.entryRequested, (Map<String, dynamic> data) async {
  final String participantId = data['participantId'];
  final String name = data['name'];
  final Function allow = data['allow'];
  final Function deny = data['deny'];

  try {
    // If you want to allow the entry request
    await allow();

    // If you want to deny the entry request
    // await deny();

    // Or answer by id from anywhere
    // await room.respondEntry(participantId, "allowed");
  } on VideoSDKError catch (error) {
    print("Could not respond to $name: ${error.code} ${error.name}");
  }
});

// Called when the host responds to an entry request
room.on(Events.entryResponded, (Map<String, dynamic> data) async {
  // data['participantId'] is the ID of the participant who requested to join
  if (data['participantId'] == myParticipantId) {
    // This is the response to your own request to join
    if (data['decision'] == "denied") {
      // Leave the room and navigate away from the room screen
      try {
        await room.leave();
      } on VideoSDKError catch (error) {
        print("Leave failed: ${error.code} ${error.name}");
      }
    }
    return;
  }

  // The response is for a guest's request
  if (data['decision'] == "allowed") {
    // Entry allowed
  } else {
    // Entry denied
  }
});

note

Events.entryResponded is emitted to every participant whose token includes the allow_join permission and to the participant who requested to join, including a participant receiving their own participantId with a decision of allowed. Check the participantId and the decision before treating this event as a response to a guest's request.

Compare it with the participantId you passed to createRoom(). While the guest waits, room.localParticipant.id is only the id you passed, or empty when you passed none.

caution

A guest whose request is denied is not disconnected from the room automatically. Call leave() on the guest and navigate away from the room screen when the decision is denied.

API Reference

The API references for all the methods and events utilized in this guide are provided below.

• createRoom()
• join()
• leave()
• respondEntry()
• entryRequested
• entryResponded
• roomJoined