Initialise Room - iOS

To configure a VideoSDK room you need two things: a token for Authentication and a roomId that specifies which room the participant joins. Let's see each of the steps closely.

Generating Token

You can generate a token in two ways:

1. Temporary Token : You can visit Dashboard's API Key section and generate the temporary token from there.

2. Server : You can set up JWT on your backend and make an API call to get the token from your server.

To learn more about Authentication and token in detail you can follow this guide.

Swift

// Update server url here.
let LOCAL_SERVER_URL = "http://192.168.0.101:9000"

class APIService {

    class func getToken(completion: @escaping (Result<String, Error>) -> Void) {
        var url = URL(string: LOCAL_SERVER_URL)!
        url = url.appendingPathComponent("get-token")

        URLSession.shared.dataTask(with: url) { data, response, error in
            if let data = data,
               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let token = json["token"] as? String {
                completion(.success(token))
            } else if let err = error {
                completion(.failure(err))
            }
        }
        .resume()
    }
}

Generating Room ID

With the token ready, we can get the roomId from the VideoSDK's rooms API.

Swift

extension APIService {

    class func createRoom(token: String, completion: @escaping (Result<String, Error>) -> Void) {
        var url = URL(string: LOCAL_SERVER_URL)!
        url = url.appendingPathComponent("create-meeting")

        let params = ["token": token]

        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.httpBody = try? JSONSerialization.data(withJSONObject: params, options: [])

        URLSession.shared.dataTask(with: request) { data, response, error in
            if let data = data,
               let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
               let roomId = json["meetingId"] as? String {
                completion(.success(roomId))
            } else if let err = error {
                completion(.failure(err))
            }
        }
        .resume()
    }
}

Initialization of Room

Create the room with the factory method VideoSDK.createRoom(). It takes the roomId and the token together, so there is no separate setup step. It returns a Room that has not joined yet. It throws ERROR_INVALID_PARAMETER when roomId or token is empty, so call it with try.

createRoom() is responsible for initializing the room with the provided configuration, which includes the roomId, token, participantName, participantId and many more.

Let's take a deeper look at the available configuration options first.

createRoom

var room: Room?

do {
    room = try VideoSDK.createRoom(
        roomId: "abcd-efgh-hijk",
        token: "<your token>",
        participantName: "John Doe", //optional
        micEnabled: true,
        camEnabled: true,
        participantId: "JD", //optional
        mode: .SEND_AND_RECV, //optional (default mode is SEND_AND_RECV)
        customCameraTrack: customCameraTrack, //optional
        customMicrophoneTrack: customMicrophoneTrack //optional
    )
} catch {
    print("Failed to create the room: \(error)")
}

• roomId :

  • roomId is a unique identifier that lets participants join a specific room.
  • It will accept String type value.
  • It will be in the format of xxx-yyy-zzz and will be generated using the VideoSDK's Room API.

• token :

  • The authentication token you generated above.
  • It will accept String type value.

• participantId:

  • This will be the unique identifier for the participant inside the room.
  • It can be used to specify the unique identifier which can be linked with your own database service.
  • It has to be of String type.
  • If you leave it out or pass an empty string, VideoSDK generates a random 8-character ID. The local participant's id is then empty until onRoomJoined().

caution

Make sure the participantId is not repeated in the same room; otherwise VideoSDK can remove a participant that uses the same participantId.

• participantName:

  • This will represent the name of the participant in the room.
  • It will accept String type value.
  • If you leave it out or pass an empty string, a random 6-character name is used. The local participant's displayName is then empty until onRoomJoined().

• micEnabled:

  • This is a Bool flag, indicating whether a participant's microphone will be automatically enabled when they join a room.
  • Default Value: true

• camEnabled:

  • This is a Bool flag, indicating whether a participant's camera will be automatically enabled when they join a room.
  • Default Value: true

• customCameraTrack:

  • If you want to set the initial video custom track, then you can pass the track created using the createCameraVideoTrack method of VideoSDK class.

  • It has to be of CustomStreamTrack type.

• customMicrophoneTrack:

  • If you want to set the initial audio custom track, then you can pass the track created using the createMicrophoneAudioTrack method of VideoSDK class.

  • It has to be of CustomStreamTrack type.

• mode:

There are three modes available:

• SEND_AND_RECV: In this mode, both audio and video streams are sent and received.

• SIGNALLING_ONLY: In this mode, no audio or video streams are sent or received. It is used solely for signaling.

• RECV_ONLY: This mode only receives audio and video streams, without sending any.

Type: Mode
Default Value: SEND_AND_RECV

note

CONFERENCE and VIEWER were removed in 4.0.0. Use SEND_AND_RECV instead of CONFERENCE, and SIGNALLING_ONLY instead of VIEWER.

• defaultCamera:

  • The camera the default video opens on, as a FacingMode: .front or .back.
  • A customCameraTrack keeps its own facingMode.
  • Default Value: .front

• maxResolution:

  • The resolution the default camera opens at: .hd (1280x720) or .sd (960x540).
  • A customCameraTrack keeps its own encoderConfig.
  • Default Value: .hd

• autoConsume:

  • If true, you receive the audio and video of every remote participant as soon as they publish them.
  • If false, you receive nothing from a participant until you call consumeMicStreams() or consumeWebcamStreams() on that Participant. This saves bandwidth in large rooms.
  • consumeMicStreams(), consumeWebcamStreams(), stopConsumingMicStreams() and stopConsumingWebcamStreams() take effect only when the room was created with autoConsume set to false.
  • Default Value: true

• dynaCast:

  • If true, the server lowers the quality of the camera video you send while no one is watching its larger layers, and raises it again when someone is. It has no effect when multiStream is off.
  • Default Value: false

• translationLanguage and speakingLanguage:

  • Language codes for real-time translation, such as "en": the language this participant receives translations in, and the language they speak.
  • Default Value: nil

For the other options, such as multiStream, metaData and preferredProtocol, see createRoom().

API Reference

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

• createRoom()