Change Role

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. Learn more about roles here.

Each HMSPeer instance has a role property which returns an HMSRole instance. You can use this property to do following:

1. Check what this role is allowed to publish. I.e can it send video (and at what resolution)? can it send audio? can it share screen? Who can this role subscribe to? (I.e student can only see the teacher's video) This is can be discovered by checking publishSettings and subscribeSettings properties
2. Check what actions this role can perform. i.e can it change someone else's current role, end meeting, remove someone from the room. This is can be discovered by checking permissions property

In certain scenarios you may want to change someone's role. Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the changeRole API comes in.

To invoke the api you will need 2 things. An instance of HMSPeer of the peer who's role you want to change and the HMSRole instance for the target role. All the peers that are in the current room are accessible via peers property of HMSRoom instance that you can get via room property of HMSSDK instance after successful room join. A list of all available roles in the current room can be accessed via roles property of HMSSDK

Once you have both you can invoke

 
 hmsSDK.changeRole(for: targetPeer, role: targetRole)

If the change role succeeds you will get a

 
func on(peer: HMSPeer, update: HMSPeerUpdate)

delegate callback with the the same peer you passed as targetPeer and a roleUpdated update type.

changeRole has an optional force parameter which is false by default meaning that changeRole is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a

 
func on(roleChangeRequest: HMSRoleChangeRequest)

delegate callback. At which point app can choose to show a prompt to the user asking for permission. If the user accepts, app should call

 
hmsSDK.accept(changeRole: roleChangeRequest)

which completes the changeRole loop. Both parties will receive a roleUpdated callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically.

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in. When it is set to true the other party will not receive a confirmation roleChangeRequest but instead will straight away receive a new set of updated permissions and stop publishing. roleUpdated callback will still be fired so that the app can update the user's UI state.