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.

2. 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);
}

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. For example, "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:

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

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);
}

// `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);

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);
}

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: