100ms Logo

100ms

Docs

Search docs
/

Change Role

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

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

  1. Check what this Role is allowed to publish, that is can it publish a video (and at what resolution)? Can it publish audio? Can it share a screen? Who can this role subscribe to?

For example, a Student Role can only see the Teacher's video. This is can be discovered by checking publishSettings and subscribeSettings properties.

  1. Check what actions this Role can perform. i.e can it change someone else's current Role, End the Meeting, or remove someone from the room. This is can be discovered by checking the 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 a listener can only subscribe.

Now at some point, the speaker may decide to nominate some listener to become a speaker.

This is where Change Role capabilities come in play.

You may choose to do either:

  1. Single Peer Role Change: Change the role of a single peer to a specified one using the changeRoleOfPeer API

  2. Bulk Role Change: Change the role of all peers with a certain role, to a specified one using the changeRoleOfPeersWithRoles API

Single Peer Role Change

To invoke the API you will need 3 parameters -

  • forPeer: An instance of HMSPeer of the peer who's role you want to change.

  • toRole: The HMSRole instance for the target role.

  • force: Whether you want to change their role without asking them or give them a chance to accept/reject.

All the peers that are in the current room are accessible via the peers property of the HMSRoom instance.

A list of all available roles in the current room can be accessed via the getRoles method of HMSSDK instance.

Now with all the parameters you can invoke the changeRoleOfPeer API:

import { HMSRole, HMSRemotePeer } from '@100mslive/react-native-hms'; try { const force = false; // instance acquired from build() method const result = await hmsInstance.changeRoleOfPeer(peer, newRole, force); // request role change, not forced console.log('Change Role Success: ', result); } catch (error) { console.log('Change Role Error: ', error); }

Note: changeRoleOfPeer success doesn't mean that the role was changed, it just means that the server accepted the request as valid.

Note: 🔑 changeRoleOfPeer is the same as changeRole but we have deprecated changeRole and it will be removed in future releases. So, Please use changeRoleOfPeer.

If the changing role succeeds, you will get an update in the HMSUpdateListenerActions.ON_PEER_UPDATE event with HMSPeerUpdate.ROLE_CHANGED update type:

const onPeerListener = ({ peer, type }: { peer: HMSPeer, type: HMSPeerUpdate }) => { if (type === HMSPeerUpdate.ROLE_CHANGED) { // Role was changed of {peer}, New role is {peer.role} // Update your app UI here } }; hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

Registered HMSUpdateListenerActions.ON_PEER_UPDATE event listener will receive the same peer, you passed as targetPeer and an HMSPeerUpdate.ROLE_CHANGED update type.

Accept Single Peer Role Change request

When a peer wishes to change the role of another peer it calls changeRoleOfPeer with a parameter force.

  • When force is set to true - role is directly changed and the peers receives an HMSUpdateListenerActions.ON_PEER_UPDATE event with HMSPeerUpdate.ROLE_CHANGED update type.

  • When force is set to false - This is a polite request e.g. "Would you like to change your role from listener to speaker?". Which can be ignored by the peer. The way it works is that the target peer will first receive a "Role Change Request" by HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST event. If the request is accepted, the peers receives an HMSUpdateListenerActions.ON_PEER_UPDATE event with HMSPeerUpdate.ROLE_CHANGED update type otherwise nothing happens.

Let's understand this with a diagram:

accept-change-role

Now let's do it step-by-step:

PeerA calls changeRoleOfPeer with force as false

try { const force = false; // instance acquired from build() method const result = await hmsInstance.changeRoleOfPeer(peer, newRole, force); // request role change, not forced console.log('Change Role Success: ', result); } catch (error) { console.log('Change Role Error: ', error); }

PeerB receives Role Change Request

PeerB receive a "Role Change Request" by HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST event -

// `HMSRoleChangeRequest` is a class that contains info about the role change request. interface HMSRoleChangeRequest { requestedBy: HMSPeer; // This is an `HMSPeer` object which contains info about the peer who performed the role change suggestedRole: HMSRole; // This is an `HMSRole` object which contains info about the destination role } ... const onRoleChangeRequest = ({ requestedBy, suggestedRole }: HMSRoleChangeRequest) => { // open a prompt to accept or reject the request }; hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST, onRoleChangeRequest);

At this point, the app should show a prompt to the user asking for permission to accept or deny role change request.

PeerB accepts Role Change request

Role Change request can be accepted by calling acceptRoleChange method on HMSSDK instance -

try { // call `acceptRoleChange` if you want to accept role change else close the prompt await hmsInstance.acceptRoleChange(); console.log('Accept change role Success'); } catch (error) { console.log('Accept change role Error: ', error); }

If the user wants to ignore the request, he/she can just dismiss the prompt.

All the peers receive Peer Role Change update

Now, all peers in the room will receive an HMSUpdateListenerActions.ON_PEER_UPDATE event with HMSPeerUpdate.ROLE_CHANGED update type so that they can do the necessary UI updates. PeerB will have all the permissions of new role.

const onPeerListener = ({ peer, type }: { peer: HMSPeer, type: HMSPeerUpdate }) => { if (type === HMSPeerUpdate.ROLE_CHANGED) { // Role was changed of {peer}, New role is {peer.role} // Update your app UI here } }; hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

Force Role Change Request case

Now let's imagine the newly nominated speaker is not behaving nicely and we want to move him back to the listener without a prompt. This is where the force parameter comes in.

When force is set to true the other party will not receive a confirmation HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST event, but instead will straight away receive a new set of updated permissions and will stop publishing audio. Note that HMSUpdateListenerActions.ON_PEER_UPDATE event with HMSPeerUpdate.ROLE_CHANGED update type will still be emitted so that the app can update the user's UI state.

Bulk Role Change

Bulk Role Change is used when we want to change the role of peers with a specific role to another role.

For example, if peers join a room with a waiting role and now you want to change all these peers to viewer role then use the changeRoleOfPeersWithRoles method.

It takes fewer parameters than for a single peer. Here is the method signature:

changeRoleOfPeersWithRoles = async (ofRoles: HMSRole[], toRole: HMSRole) => { ... };
  1. toRole is the HMSRole they should be changed to.
  2. ofRoles is a list of HMSRole whose role should be changed.

Here's how the method could be called to change all waiting and guest roles to host:

// fetch all available Roles in the room const roles = await hmsInstance.getRoles(); // get the Host Role object const hostRole = roles.find((role) => role.name === 'host'); // get list of Roles to be updated - in this case "Waiting" and "Guest" Roles const rolesToChange = roles.filter((role) => role.name === 'waiting' || role.name === 'guest'); // now perform Role Change of all peers in "Waiting" and "Guest" Roles to the "Host" Role await hmsInstance.changeRoleOfPeersWithRoles(rolesToChange, hostRole);

Edge cases with bulk role change

  1. Note that if an empty list is sent to ofRoles, no roles will be changed. This is to avoid accidentally changing roles you may not have intended such as the bots that provide recording and streaming with the roles beam.

  2. Also, Bulk Role Changes are always forced, that is no option will be given for the peer to accept it, they will just be changed immediately.

Bulk Role Change Errors

You may get the following errors for bulk role change:

MessageMeaning
invalid roleA role in the list of roles to change does not exist in this room.
target role clash with requested rolesthe 'toRole' is also listed as one to change to 'toRole'
role does not have required permissionPeer does not have role change permission.
peer leftThe peer who's role was to be changed has left.
role invalidThe 'toRole' is invalid.

Have a suggestion? Recommend changes ->

Was this helpful?

1234