Peer Metadata
Looking for persistent state that can be set on a peer and updated anytime, for everyone in the room? Peer metadata it is.
Metadata can be set initially in the HMSConfig
object that's passed into the join method and update post join by
following the API below. You can imagine metadata as a persistent object attached to the peer which has more details about
them.
We'll explain the API using an example of implementing raise hand. For this, we'll use the below interface for metadata -
interface CustomMetadata { isHandRaised: boolean; }
Getting and Setting metadata
Note that peer.metadata
is a string, it can be used to keep a stringified JSON. The string will be converted properly
to a json object however if you use the selector described below.
Metadata update post join can be achieved by calling hmsActions.changeMetadata(metadata)
, the below example shows implementing a toggle raise
hand function for the local peer.
async function toggleRaiseHand() { const localPeerId = hmsStore.getState(selectLocalPeerID); const metadata = hmsStore.getState(selectPeerMetadata(localPeerId)); const newMetadata = { ...metadata, isHandRaised: !metadata.isHandRaised }; await hmsActions.changeMetadata(newMetadata); }
Peer Metadata update Notification
Once the metadata is updated, all the peers will receive a notification
with type METADATA_UPDATED
and HMSPeer
object as notification data.
hmsNotifications.onNotification((notification) => { const peer = notification.data; const { isHandRaised } = hmsStore.getState(selectPeerMetadata(peer.id)); if (isHandRaised && !peer.isLocal) { toast(`${peer.name} raised their hand.`); } }, HMSNotificationsTypes.METADATA_UPDATED);
Updating Remote Peer Metadata
Say if a guest has raised hand, host might want to lower their hand after a while. We don't have a direct method available to do this currently but it can be done using custom events. The host can send a message to the peer who raised their hand, and the peer can lower their hand on getting the message.
const LOWER_HAND = 'LOWER_HAND'; // don't save messages with this type in store hmsActions.ignoreMessageTypes([LOWER_HAND]); // host can send a custom message to the peer who has raised hand await hmsActions.sendDirectMessage('', peerIdWithRaisedHand, LOWER_HAND); // the peer on receiving the event can lower their hand hmsNotifications.onNotification((notification) => { const msg = notification.data; if (msg && msg.type === LOWER_HAND) { const localPeerId = hmsStore.getState(selectLocalPeerID); const metadata = hmsStore.getState(selectPeerMetadata(localPeerId)); const newMetadata = { ...metadata, isHandRaised: false }; hmsActions.changeMetadata(newMetadata); } }, HMSNotificationTypes.NEW_MESSAGE);
Ideas
- Implementing raise hand
- Multiplayer games like chess, scribble, quizzes etc.
- Store extra information such as profile picture for every peer which can be updated mid call