100ms Logo

100ms

Docs

Search docs
/

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.

Create HMSSDK instance

First, create an instance of HMSSDK using the build function.

import { HMSSDK } from '@100mslive/react-native-hms'; // create HMSSDK instance using the build function const hmsInstance = await HMSSDK.build();

Attach Event Listeners

You'll need to add Event Listeners for HMSUpdateListenerActions, which are invoked to notify about updates happening in the room like a peer joins/leaves, a track got muted/unmuted, etc.

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

Create HMSConfig object

Next, create an object of HMSConfig class using the available joining configurations.

let config = new HMSConfig({ authToken: 'eyJH5c...', // client-side token generated from your token service username: 'John Appleseed' });

Invoke Join

Now, we are primed to join the room. All you have to do is calling join by passing the config object.

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.

Create Track Settings object

First, create an instance of HMSTrackSettings, it will be used when we initialize our SDK.

For joining a Room with Muted Audio and/or Video, We set initialState property of HMSAudioTrackSettings and/or HMSVideoTrackSettings with HMSTrackSettingsInitState.MUTED as follows -

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

Create HMSSDK instance

Now, create an instance of HMSSDK by passing the HMSTrackSettings object created above to the build function -

import { HMSSDK } from '@100mslive/react-native-hms'; // 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 });

Rest all the steps are same as above.

Now, the user joins the room with the microphone and the camera turned off.

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

Have a suggestion? Recommend changes ->

Was this helpful?

1234