Change Mode - iOS

In a live stream, audience members usually join in RECV_ONLY mode, meaning they can only view and listen to the hosts. However, if a host invites an audience member to actively participate (e.g., to speak or present), the audience member can switch their mode to SEND_AND_RECV using the changeMode() method.

This guide explains how to use the changeMode() method and walks through a sample implementation where a host invites an audience member to become a host using PubSub.

caution

changeMode() only ever changes the mode of the participant who calls it. There is no form of changeMode() that takes another participant's id, and a host cannot change an audience member's mode directly.

Promotion therefore takes two pieces of code, one on each side, and neither does anything on its own:

1. On the host — publish a request to the invited participant over PubSub. Step 1 and Step 2 below.
2. On the invited participant — subscribe to that same topic and, in the message handler, call changeMode() yourself. Step 3 below. Without this subscriber the request reaches nobody and no mode ever changes.

An implementation that only publishes the request looks finished and does nothing.

changeMode()

• The changeMode() method from the Meeting class switches the calling participant's own mode during a live stream — for example, an audience member becoming a host.
• It takes only the target mode. To move a different participant between modes, send them a PubSub request and let their client call changeMode() itself, as shown in the Implementation Guide below.

Example: a participant changing its own mode

@IBAction func changeModeTapped(_ sender: UIButton) {
    meeting?.changeMode(to: "SEND_AND_RECV") { error in
        if let error = error {
            print("Failed to change mode: \(error.localizedDescription)")
        } else {
            print(" Mode changed to SEND_AND_RECV")
        }
    }
}

Implementation Guide

Step 1 : Create a Pubsub Topic

• Set up a PubSub topic to send a mode change request from the host to a specific audience member.

func inviteParticipantAsHost(participantId: String) {
    let topic = "REQUEST_TO_JOIN_AS_HOST_\(participantId)"
    let message = "SEND_AND_RECV"
    meeting?.pubSub.publish(topic: topic, message: message, options: nil)
    print("Invitation sent to participant: \(participantId)")
}

Step 2 : Create an Invite Button

• Add an "Invite on Stage" button for each audience member. When clicked, it publishes a PubSub message with the mode "SEND_AND_RECV" to that participant.

@objc func inviteButtonTapped(for participant: Participant) {
    // Only invite participants who are in RECV_ONLY mode
    guard participant.mode == "RECV_ONLY" else { return }
    inviteParticipantAsHost(participantId: participant.id)
}

Step 3 : Create a Listener to Change the Mode

• On the audience side, subscribe to the specific PubSub topic. When a mode request is received, update the participant’s mode using changeMode().

func setupModeChangeListener() {
    guard let localParticipantId = meeting?.localParticipant?.id else { return }
    
    // Subscribe to the specific topic for this participant
    let topic = "REQUEST_TO_JOIN_AS_HOST_\(localParticipantId)"
    
    meeting?.pubSub.subscribe(topic: topic) { message in
        if let mode = message.message as? String {
            // When a request is received, change the mode
            self.meeting?.changeMode(to: mode) { error in
                if let error = error {
                    print("Failed to change mode: \(error.localizedDescription)")
                } else {
                    print("Mode changed to \(mode)")
                }
            }
        }
    }
}

API Reference

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

• changeMode()
• Participant
• Meeting
• PubSub