Developer Experience Guidelines - iOS

These practices cover when to start features, how to handle errors, and how to manage resources and event subscriptions.

Initiate Key Features After Room Join Event

Start specific features only after the onRoomJoined() event has been triggered.

• Trigger Key Actions After Joining the Room : Most methods called before the room is joined throw ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED. If your application utilizes any of the following features or you want to perform any action as soon as the room is joined, it's recommended to call them only after the room has successfully started:

  • Chat Subscription: To enable in-room chat functionality, subscribe to the chat topic after the onRoomJoined() event is triggered. This ensures that messages are reliably received by participants.

    class LiveStreamViewController: UIViewController {
        var room: Room?
    
        override func viewDidLoad() {
            super.viewDidLoad()
            do {
                // initialize
                room = try VideoSDK.createRoom(
                    roomId: "roomID",
                    token: "<your token>",
                    participantName: "participantName",
                    micEnabled: true,
                    camEnabled: true,
                    participantId: "participantID"
                )
            } catch {
                print("createRoom failed: \(error)")
                return
            }
            // listener
            room?.addEventListener(self)
            // join
            Task {
                do {
                    try await room?.join()
                } catch {
                    print("join failed: \(error)")
                }
            }
            // Do not subscribe here. The room is not joined yet.
        }
    }
    
    extension LiveStreamViewController: RoomEventListener {
        /// Room Joined
        func onRoomJoined() {
            Task {
                do {
                    try await room?.pubSub.subscribe(topic: "CHAT", listener: self)
                } catch let error as VideoSDKError where error == .ERROR_INVALID_PARAMETER {
                    // Already subscribed, for example when onRoomJoined() runs again after a reconnect.
                } catch {
                    print("CHAT subscribe failed: \(error)")
                }
            }
        }
    }
    
    extension LiveStreamViewController: PubSubMessageListener {
        func onMessageReceived(_ message: PubSubMessage) {
            print("Message received: \(message.message)")
        }
    }

  • Device Management: If you need users to use specific audio or video devices when the room is first joined, you can utilize the custom track. Pass a camera's deviceId from getCameras() as cameraId to the createCameraVideoTrack() method for video, and a microphone's deviceId from getMics() as microphoneId to the createMicrophoneAudioTrack() method for audio. Both methods are async throws, so call them with try await inside a Task. Once the track is created, provide it to the createRoom() method.

  • Recording and Transcription: To automatically start recording or transcription as soon as the room begins, configure the autoStartConfig in the Create Room API. For detailed information, refer to the documentation here.

Listen for Error Events

Listening to error events enables your application to handle unexpected issues efficiently, providing users with clear feedback and potential solutions. Error codes pinpoint specific problems, whether from configuration settings, account restrictions, permission limitations, or device constraints.

Most methods are async throws. When a call you make fails, the method throws a VideoSDKError, so call it with try await inside do / catch. The onError event still reports errors that are not thrown, such as a camera or microphone that fails to open, and errors the SDK raises on its own. Some failures, such as a failed join(), are thrown and also sent to onError, so show each error to the user only once. See Error Events for details.

Here are recommended solutions based on common error categories:

1. Errors associated with Organization: If you encounter errors related to your organization (e.g., account status or participant limits), reach out to support at support@videosdk.live or reach out to us on Discord for assistance.

2. Errors associated with Token: For errors related to authentication tokens, ensure the token is valid and hasn’t expired, then try the request again.

3. Errors associated with Room and Participant: Check that roomId and participantId are correctly passed and valid. Also, ensure each participant has a unique participantId to avoid duplicate entries.

4. Errors associated with Add-on Service: If you encounter errors with add-on services (such as recording or streaming), try restarting the service. For example, if startRecording() throws START_RECORDING_FAILED, call it again. If you're using webhooks, you can also retry on recording-failed hook.

5. Errors associated with Media: Inform the user about media access issues, such as microphone or camera permissions. Design the UI to clearly indicate what is preventing the mic or camera from enabling, helping the user understand the problem.

6. Errors associated with Actions: If you need to perform actions as soon as you join a room, only initiate them after receiving the onRoomJoined() event. A method called before that throws ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED.

• Here's how to listen for the error event:

import VideoSDKRTC

extension LiveStreamViewController: RoomEventListener {
    func onError(error: VideoSDKError) {
        switch error {
        case .INVALID_TOKEN:
            print("Invalid Token")
        case .ERROR_CAMERA_ACCESS_DENIED_OR_DISMISSED, .ERROR_CAMERA_PERMISSION_DENIED_BY_OS:
            print("Camera access was denied")
        default:
            print("\(error.name) (\(error.code)): \(error.message)")
        }
    }
}

• Here's how to catch an error thrown by a method:

Task {
    do {
        try await room?.join()
    } catch let error as VideoSDKError {
        print("\(error.name) (\(error.code)): \(error.message)")
    } catch {
        print("error: \(error)")
    }
}