Event Listeners

Common Events Implementation Lifecycle

The below diagram shows an overview of which Events are emitted and at what time when you Join or Preview a Room.

You will start receiving event updates after you call preview or join method on HMSSDK instance.

All Available Event Listeners

You can easily add or remove an event listener by using the addEventListener() or removeEventListener() method. HMSUpdateListenerActions is an enum class which has all the types of event listeners.

import {
    HMSSDK,
    HMSUpdateListenerActions,
    HMSException,
    HMSMessage,
    HMSLeaveRoomRequest,
    HMSSpeaker,
    HMSPeer,
    HMSTrack,
    HMSSessionStore,
    HMSRole,
    HMSRoom,
    HMSRoomUpdate,
    HMSPeerUpdate,
    HMSTrackUpdate,
    HMSAudioDevice,
    HMSTranscript,
    HMSPermission,
} from '@100mslive/react-native-hms';

const hmsInstance = await HMSSDK.build();

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PREVIEW, onPreviewListener);

const onPreviewListener = ({ room: HMSRoom, previewTracks: HMSTrack[] }) => {
    const videoTrack = previewTracks.videoTrack;
    const videoTrackId = videoTrack.trackId;
    // Event emitted when the local preview is available.
    // This event is triggered once the local user's video preview becomes available.
    // It allows the application to display the local video stream to the user,
    // ensuring they can see their own feed before interacting with others in the room.
    // You can set your camera and mic on/off while joining.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoinListener);

const onJoinListener = ({ room: HMSRoom }) => {
    // Event emitted when the local user joins the room. You can navigate to other screens.
    //
    // This event signifies that the local user has successfully connected to the room and is now part of the session.
    // It is a critical event for initiating further actions within the room, such as fetching current participants,
    // subscribing to tracks, or sending messages. Handling this event properly is essential for setting up the user's
    // environment and ensuring a smooth experience in the room.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

const onPeerListener = ({ peer, type }: { peer: HMSPeer, type: HMSPeerUpdate }) => {
    // Event emitted when there is an update related to a peer in the room.
    //
    // This event is triggered whenever a peer's state changes within the room, such as when a peer's video or audio track is enabled or disabled,
    // or when a peer's metadata is updated. It provides a way for the application to react to changes in a peer's status, ensuring that the UI
    // and application state can be updated to reflect the current state of peers in the room.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_LIST_UPDATED, onPeerListListener);

const onPeerListListener = ({ addedPeers, removedPeers }: { addedPeers: HMSPeer[], removedPeers: HMSPeer[] }) => {
    // Event emitted when there is an update related to the list of peers in the room.
    //
    // This event is triggered whenever the list of peers in the room changes, such as when a new peer joins the room or an existing peer leaves.
    // It provides a way for the application to react to changes in the list of peers, ensuring that the UI and application state can be updated to
    // reflect the current state of peers in the room.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_TRACK_UPDATE, onTrackListener);

const onTrackListener = ({
    track,
    peer,
    type
}: {
    track: HMSTrack,
    peer: HMSPeer,
    type: HMSTrackUpdate
}) => {
    // gets triggered when track is added, removed, muted, unmuted, degraded and restored back.
    // use these objects to update your local and remote peers.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ROOM_UPDATE, onRoomListener);

const onRoomListener = ({ room, type }: { room: HMSRoom, type: HMSRoomUpdate }) => {
    // Event emitted when there is an update related to the room.
    //
    // This event is triggered by various room-related changes, such as updates to the room's metadata, changes in the room's state,
    // or modifications to the list of available tracks. It serves as a general notification to the application that some aspect of the
    // room's configuration or status has changed, enabling the application to respond appropriately, such as updating the UI or querying
    // for new information to reflect the current state of the room.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onErrorListener);

const onErrorListener = (data: HMSException) => {
    // gets triggered whenever some error occours with a error description. You can either log it or navigate to some error screen.
    // data contains a error code and message due to which error occoured.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_MESSAGE, onMessageListener);

const onMessageListener = (data: HMSMessage) => {
    // gets triggered whenever you receive a direct message, broadcasted message or role-based message.
    // whenever local peer receives a message this is triggered. Add the message to reducer.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.ON_SPEAKER, onSpeakerListener);

const onSpeakerListener = (data: HMSSpeaker[]) => {
    // gets triggered whenever someone speaks
    // an array of speakers is received. Use it to highlight the speakers.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.RECONNECTING, onReconnectingListener);

const onReconnectingListener = () => {
    // triggered whenever local peer is trying to reconnect to room, that is bad network.
};


hmsInstance.addEventListener(HMSUpdateListenerActions.RECONNECTED, onReconnectedListener);

const onReconnectedListener = () => {
    // triggered when local peer is reconnected to the room.
};


hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST,
    onRoleChangeRequestListener
);

const onRoleChangeRequestListener = (data: {
    requestedBy?: HMSPeer;
    suggestedRole: HMSRole;
}) => {
    // triggered when someone requests a role change for local peer. We can get data.requestedBy.name, data.suggestedRole.name
    // You can show a modal allowing user to accept or decline the role change request whenever this is triggered.
};


hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_REMOVED_FROM_ROOM,
    onRemovedFromRoomListener
);

const onRemovedFromRoomListener = (data: {
    requestedBy?: HMSPeer | null;
    reason?: string;
    roomEnded?: boolean;
    }) => {
    // triggered whenever someone removes local peer from the room or the room is ended.
    // You can navigate to home screen, clear all reducers and reset all the states whenever this is triggered
};


hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_CHANGE_TRACK_STATE_REQUEST,
    onChangeTrackStateRequest
);

const onChangeTrackStateRequest = (data: {
    requestedBy?: HMSPeer;
    trackType: string;
    mute: boolean;
}) => {
    // triggered when someone requests a unmute for local peer. We can get data.requestedBy.name, data.trackType
    // You can show a modal allowing user to accept or decline the role change request whenever this is triggered.
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_SESSION_STORE_AVAILABLE,
    onSessionStoreAvailableListener,
);

const onSessionStoreAvailableListener = ({
    sessionStore,
}: {
    sessionStore: HMSSessionStore;
}) => {
    // You can use the SessionStore object provided here according to your app logic
    // For example, below we are saving `sessionStore` reference in `Redux`
    dispatch(saveUserData({hmsSessionStore: sessionStore}));
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_SESSION_STORE_CHANGED,
    onSessionStoreChangedListener,
);

const onSessionStoreChangedListener = ({
    sessionStore,
}: {
    sessionStore: HMSSessionStore;
}) => {
    // You can use the SessionStore object provided here according to your app logic
    // For example, below we are saving `sessionStore` reference in `Redux`
    dispatch(saveUserData({hmsSessionStore: sessionStore}));
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_TRANSCRIPTS,
    onTranscriptsListener,
);

const onTranscriptsListener = (data: {
    transcripts: HMSTranscript[];
}) => {
    // This will be triggered whenever the transcripts are received.
    // You can use this to show the transcripts in the UI.
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_AUDIO_DEVICE_CHANGE,
    onAudioDeviceChangeListener,
);

const onAudioDeviceChangeListener = (data: {
    audioDevice: HMSAudioDevice;
}) => {
    // This will be triggered whenever the audio device changes. Android only.
    // You can use this to update the UI to show the current audio device.
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_PERMISSIONS_REQUESTED,
    onPermissionsRequestedListener,
);

const onPermissionsRequestedListener = (data: {
    requestedBy: HMSPeer;
    permissions: HMSPermission[];
}) => {
    // This will be triggered whenever the permissions are requested. Android only.
    // You can use this to show the permissions dialog to the user.
};


hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_LOCAL_AUDIO_STATS,
    onChangeLocalAudioStats
);

const onChangeLocalAudioStats = (data: {
    localAudioStats: HMSLocalAudioStats,
    track: HMSLocalAudioTrack,
    peer: HMSPeer
}) => {
    // This contains stats related to local audio track.
};

hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_LOCAL_VIDEO_STATS,
    onChangeLocalVideoStats
);

const onChangeLocalVideoStats = (data: {
    localVideoStats: HMSLocalVideoStats,
    track: HMSLocalVideoTrack,
    peer: HMSPeer
}) => {
    // This contains stats related to local video track.
};

hmsInstance?.addEventListener(HMSUpdateListenerActions.ON_RTC_STATS, onChangeRtcStats);

const onChangeRtcStats = (data: { rtcStats: HMSRTCStatsReport }) => {
    // This will contain the combined stats for the room.
};

hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_REMOTE_AUDIO_STATS,
    onChangeRemoteAudioStats
);

const onChangeRemoteAudioStats = (data: {
    remoteAudioStats: HMSRemoteAudioStats,
    track: HMSRemoteAudioTrack,
    peer: HMSPeer
}) => {
    // This contains stats related to remote audio track.
};

hmsInstance?.addEventListener(
    HMSUpdateListenerActions.ON_REMOTE_VIDEO_STATS,
    onChangeRemoteVideoStats
);

const onChangeRemoteVideoStats = (data: {
    remoteVideoStats: HMSRemoteVideoStats,
    track: HMSRemoteVideoTrack,
    peer: HMSPeer
}) => {
    // This contains stats related to remote video track.
};

Check out the Event Listener Enums docs to understand the Update Types emitted by the SDK for events like ON_PEER_UPDATE, ON_TRACK_UPDATE, ON_ROOM_UPDATE, etc.