HandRaise, Peer count and Support for Large Rooms

Handle Raise and Lower Hand

Previously, We had to implement hand raise functionality with peer metadata. But that is no more required, We have made raising/lowering hand as first class API on HMSSDK.

Requirements

SDK version 1.9.0 or higher

How to Raise Hand

You can use raiseLocalPeerHand method available on HMSSDK instance to raise hand of local peer.

// `hmsInstance` is an instance of `HMSSDK` class

await hmsInstance.raiseLocalPeerHand();

How to Lower Hand

You can use lowerLocalPeerHand method available on HMSSDK instance to lower hand of local peer.

// `hmsInstance` is an instance of `HMSSDK` class

await hmsInstance.lowerLocalPeerHand();

How to Lower Hand of Remote Peer

You can use lowerRemotePeerHand method available on HMSSDK instance to lower hand of remote peer. It accepts a peer (an instance of the HMSPeer class) of whom you want to lower the hand.

// `hmsInstance` is an instance of `HMSSDK` class
// `peer` is a remote peer of whom we want to lower the hand

await hmsInstance.lowerRemotePeerHand(peer);

How to know when a Peer raises or lowers hand

Whenever local/remote peer raises or lowers hand, HMSUpdateListenerActions.ON_PEER_UPDATE event is emitted with HMSPeerUpdate.HAND_RAISED_CHANGED update type. You can subscribe to this event and update the UI for updated peer.

const onPeerListener = (data: { peer: HMSPeer; type: HMSPeerUpdate; }) => {
    const { peer, type } = data;

    if (type === HMSPeerUpdate.HAND_RAISED_CHANGED) {
        // {peer} has either raised or lowered its hand
        // Update UI for the {peer}

        // Parsing the updated Metadata
        const isHandRaised = peer.isHandRaised;
    }
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

Get current hand raise status of peer

Now, HMSPeer instance has isHandRaised property on it. It will be true when peer has raised it's hand and false otherwise. You can use peer.isHandRaised property to get the current status.

hmsPeer.isHandRaised;

How to get Total Peer count of the Room

You can use peerCount property of HMSRoom instance to get the latest peer count of the room. Whenever peer count is updated, HMSUpdateListenerActions.ON_ROOM_UPDATE event is emitted with HMSRoomUpdate.ROOM_PEER_COUNT_UPDATED update type.

const roomUpdateHandler = (data: {
  room: HMSRoom;
  type: HMSRoomUpdate;
}) => {
  if (data.type === HMSRoomUpdate.ROOM_PEER_COUNT_UPDATED) {
    // Update UI of `room.peerCount`
  }
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_ROOM_UPDATE,
  roomUpdateHandler
);

Large Room changes

Get list of peers on join

When local peer join a room, it will not receive ON_PEER_UPDATE with type === HMSPeerUpdate.PEER_JOINED for each remote peer like it used to. Now, ON_PEER_LIST_UPDATED event is emitted with list of all the peers present in the room.

You can subscribe to ON_PEER_LIST_UPDATED event to get list of added or removed peers -

const peerListUpdateHandler = (data: {
  addedPeers: HMSPeer[];
  removedPeers: HMSPeer[];
}) => {
  // here,
  // `data.addedPeers` is list of added peers in room
  // `data.removedPeers` is list of removed peers from room
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PEER_LIST_UPDATED,
  peerListUpdateHandler
);

Note that on subsequent peer joins, both ON_PEER_LIST_UPDATED and ON_PEER_UPDATE with type === HMSPeerUpdate.PEER_JOINED events are emitted.

Peer List Iterator API

You don't want to fetch every peer if the room is very large, use the peer list iterator instead.

How to get peer list iterator

You call getPeerListIterator method on HMSSDK instance to get HMSPeerListIterator.

getPeerListIterator method has following HMSPeerListIteratorOptions options -

• byRoleName?: string - filter by role of the peers
• byPeerIds?: string[] - peerIDs of the peers you want to fetch with iterator.
• limit?: number - number of peers fetched by the iterator in next method call. Default value is 10

// calling `getPeerListIterator` without any options
const peerListIterator = hmsInstance.getPeerListIterator();

// calling `getPeerListIterator` with some options
const peerListIterator = hmsInstance.getPeerListIterator({
    limit: 10,
    byRoleName: 'viewer-realtime'
});

If you wish to filter peers based on role name or peer ids, you can pass them in HMSPeerListIteratorOptions.

limit is the number of peers you want to fetch in one go.

Now with peerListIterator instance you can incremently load peers.

How to use peer iterator to load peers incremently

You can use next method on HMSPeerListIterator instance to fetch the next set of peers.

try {
    const peers = await peerListIterator.next();

    // store newly loaded peers to show in UI
} catch (error) {
    // handle error returned by `next` method here
}

How to check if more peers are available to load

You can use hasNext method on HMSPeerListIterator instance to check if there are more peers available to fetch.

try {
    const hasNext = await peerListIterator.hasNext();

    if (hasNext) {
        // can fetch more peers by calling `next` method
    } else {
        // There are no more peers available to fetch right now
    }
} catch (error) {
    // handle error returned by `hasNext` method here
}

How to check the total count of peers in the peer list

You use totalCount property on HMSPeerListIterator instance to know how many peers are there in the peer list. This property is updated whenever you can next method, initially it is zero. so, ensure you have called peerListIterator.next() method before using totalCount property.

try {
    await peerListIterator.next();

    // `totalCount` is the number of peers in the room
    const totalCount = peerListIterator.totalCount;
} catch (error) {
    // handle error returned by `next` method here
}