Join Room

Overview

To join and interact with others in audio or video call, the user needs to join a room.

When user indicates that they want to join the room, your app should have -

1. User Name - The name which should be displayed to other peers in the room.
2. Auth Token - The Client side Authentication Token generated by the Token Service.

You can also optionally pass these fields -

1. Track Settings - Such as joining a Room with Muted Audio or Video using the HMSTrackSettings object. More information available here

2. User Metadata - This can be used to pass any additional metadata associated with the user using metadata of HMSConfig object. For Eg: user-id mapping at the application side. More information is available here.

Join a Room

We'll call the join method on HMSSDK object with a config containing above fields to join the room.

import { HMSSDK } from '@100mslive/react-native-hms';

// create HMSSDK instance using the build function

/**
 * Important Note: Don't build new `HMSSDK` instance before destroying the previous one.
 * for more info checkout {@link https://www.100ms.live/docs/react-native/v2/how--to-guides/install-the-sdk/hmssdk#what-does-destroy-method-do}
 */
const hmsInstance = await HMSSDK.build();

// Use Room Code for your room here
const roomCode = 'abc-defg-hij'; // Sample Room Code

const token = await hmsInstance.getAuthTokenByRoomCode(roomCode);

// add Event Listeners to subscribe to Join Success or Failure updates
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoin);

let config = new HMSConfig({
    authToken: token, // client-side token generated from `getAuthTokenByRoomCode` method
    username: 'John Appleseed'
});

hmsInstance.join(config);

After calling join your app will be provided an update from the 100ms SDK.

✅ If successful, the onJoin function which is listening for HMSUpdateListenerActions.ON_JOIN event will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the onError function which is listening for HMSUpdateListenerActions.ON_ERROR event will be invoked with exact failure reason.

Once you get onJoin callback, You have joined a room successfully 🥳

Join with Muted Audio / Video

Joining with Muted Audio / Video is a customization that sets the microphone and camera state before joining the room.

By default 100ms SDK keeps the microphone and camera ON but by using this feature you can decide their state according to your use case.

HMSSDK provides this capability using initialState property of Audio & Video Track Settings.

Here, initialState property of HMSAudioTrackSettings and HMSVideoTrackSettings is an Enum of type HMSTrackSettingsInitState which has only two possible values as -

enum HMSTrackSettingsInitState {

    // If the track needs to be kept mute while joining
    MUTED,

    // If the track needs to be kept unmute while joining
    UNMUTED
}

Let's see how this can be achieved in the following steps.

// Customize Audio & Video initial states as per user discretion
const getTrackSettings = () => {
    let audioSettings = new HMSAudioTrackSettings({
        initialState: HMSTrackSettingsInitState.MUTED
    });

    let videoSettings = new HMSVideoTrackSettings({
        initialState: HMSTrackSettingsInitState.MUTED
    });

    return new HMSTrackSettings({
        video: videoSettings,
        audio: audioSettings
    });
};

// Get the Track Settings object
const trackSettings = getTrackSettings();

import { HMSSDK } from '@100mslive/react-native-hms';

/**
 * Important Note: Don't build new `HMSSDK` instance before destroying the previous one.
 * for more info checkout {@link https://www.100ms.live/docs/react-native/v2/how--to-guides/install-the-sdk/hmssdk#what-does-destroy-method-do}
 */

// Pass the Track Settings object to the build function
c̶o̶n̶s̶t̶ ̶h̶m̶s̶I̶n̶s̶t̶a̶n̶c̶e̶ ̶=̶ ̶a̶w̶a̶i̶t̶ ̶H̶M̶S̶S̶D̶K̶.̶b̶u̶i̶l̶d̶(̶)̶;̶
const hmsInstance = await HMSSDK.build({ trackSettings });

Update Listeners

100ms SDK provides multiple Event Listeners - HMSUpdateListenerActions which notifies about the updates happening in the room like a peer joins/leaves, a track got muted/unmutes, etc.

After calling join your app will be provided an update from the 100ms SDK.

✅ If successful, the HMSUpdateListenerActions.ON_JOIN event will be triggered with information about the room encapsulated in the HMSRoom object.

❌ If failure, the HMSUpdateListenerActions.ON_ERROR event will be triggered with exact failure reason in HMSException object.

Depending on your use case, you'll need to implement a selective set of the Update Listener actions. The most common ones are ON_JOIN, ON_PEER_UPDATE, ON_TRACK_UPDATE & ON_ERROR.

You'll need to implement these listeners to perform UI Actions, update App State, etc. These updates can be used to render the video on screen or to display other info regarding the room.

const hmsInstance = await HMSSDK.build();

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoinListener);

// gets triggered when join is successful
const onJoinListener = (data: { room: HMSRoom }) => {
    handleJoin(data.room);
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

const onPeerListener = ({ peer, type }: { peer: HMSPeer, type: HMSPeerUpdate }) => {
    // gets triggered when peer leaves, joins, peer's audio or video is muted, starts or stops speaking, role is changed or becomes dominant speaker.
    // use these objects to update your local and remote peers.
};

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_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.ON_ROOM_UPDATE, onRoomListener);

const onRoomListener = ({ room, type }: { room?: HMSRoom, type?: HMSRoomUpdate }) => {
    // gets triggered when room is muted or unmuted.
    // use these objects to update your local and remote peers.
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_PREVIEW, onPreviewListener);

// gets triggered when we call preview function before joining a room
const onPreviewListener = ({ previewTracks }) => {
    const videoTrack = previewTracks.videoTrack;
    const videoTrackId = videoTrack.trackId;
};

hmsInstance.addEventListener(HMSUpdateListenerActions.RECONNECTING, onReconnectingListener);

const onReconnectingListener = (data) => {
    // triggered whenever local peer is trying to reconnect to room in a bad network
};

hmsInstance.addEventListener(HMSUpdateListenerActions.RECONNECTED, onReconnectedListener);

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

hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST,
    onRoleChangeRequestListener
);

const onRoleChangeRequestListener = (data: HMSRoleChangeRequest) => {
    // 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: HMSLeaveRoomRequest) => {
    // 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: HMSChangeTrackStateRequest) => {
    // 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.
};