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


const RaiseHand = () => {
    const localPeerId = useHMSStore(selectLocalPeerID);
    const metaData = useHMSStore(selectPeerMetadata(localPeerId));
    const hmsActions = useHMSActions();
    const toggleRaiseHand = useCallback(async () => {
        const newMetadata = { ...metaData, isHandRaised: !metaData.isHandRaised };
        await hmsActions.changeMetadata(newMetadata);
    }, [hmsActions, metaData]);
    return (
        <button onClick={toggleRaiseHand}>
            {metaData.isHandRaised ? 'Hand Raised' : 'Hand not Raised'}
        </button>
    );
};

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


const notification = useHMSNotifications(HMSNotificationsTypes.METADATA_UPDATED);
const peer = notification?.data;
const isHandRaised = useHMSStore(selectPeerMetadata(peer?.id ?? ''))?.isHandRaised;

useEffect(() => {
    if (isHandRaised && peer && !peer.isLocal) {
        toast(`${peer.name} raised their hand.`);
    }
}, [isHandRaised, peer]);

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


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
const hmsActions = useHMSActions();
const notification = useHMSNotifications(HMSNotificationsTypes.NEW_MESSAGE);
const localPeerId = useHMSStore(selectLocalPeerID);
const metadata = useHMSStore(selectPeerMetadata(localPeerId));

useEffect(() => {
    if (!notification) {
        return;
    }

    const message = notification.data;
    if (message?.type === LOWER_HAND) {
        const newMetadata = { ...metadata, isHandRaised: false };
        hmsActions.changeMetadata(newMetadata);
    }
}, [notification]);

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

HLS Player Session Store

Have a suggestion? Recommend changes ->