Join Room

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. settings: {isAudioMuted, isVideoMuted} - you can use this to set the initial audio/video state at time of join.
2. User metadata - this can be used to pass any additional metadata associated with the user.
3. ICE server config - you can use custom STUN/TURN servers for media connection. A sample config is defined below:

iceServers: [{
  urls: ["turn:turn-in.abc.live:1234"], // supports multiple URLs
  userName: "userName",
  password: "password"
}]

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

import { hmsActions } from './hms';

const config = {
    userName: 'Jon Snow',
    authToken: '<Auth token>', // client-side token generated from your token service
    settings: {
        isAudioMuted: true,
        isVideoMuted: false
    },
    metaData: JSON.stringify({city: 'Winterfell', knowledge: 'nothing'}),
    rememberDeviceSelection: true,  // remember manual device change
};

await hmsActions.join(config);

import { useHMSActions } from '@100mslive/react-sdk';

function Join() {
  const hmsActions = useHMSActions();

  const config = {
    userName: 'Jon Snow',
    authToken: '<Auth token>', // client-side token generated from your token service
    settings: {
        isAudioMuted: true,
        isVideoMuted: false,
    },
    metaData: JSON.stringify({city: 'Winterfell', knowledge: 'nothing'}),
    rememberDeviceSelection: true,  // remember manual device change
  };

  async function onJoinClick() {
    await hmsActions.join(config)
  }

  return <
        // form with input and join button
  />;
}

That's it. You have joined a room successfully 🥳. You should now be able to have an audio only call with this.

Getting Current Room State

You might want to hide your join form from the UI or navigate to another page when the join has completed. We provide some selectors which operate upon the room state to give the relevant information. One such selector is selectIsConnectedToRoom. Here's how to use it -

import { hmsStore } from './hms';
import { selectIsConnectedToRoom } from '@100mslive/hms-video-store';

// use getState to get the state at any time
console.log('isConnected - ', hmsStore.getState(selectIsConnectedToRoom));

function onRoomStateChange(connected) {
    console.log('isConnected - ', connected);
}

// you can also subscribe to the state and get your function called whenever the state changes
hmsStore.subscribe(onRoomStateChange, selectIsConnectedToRoom);

import { useHMSStore, selectIsConnectedToRoom } from '@100mslive/react-sdk';

// if the connection state changes, the store hook will take care of rerendering the component
function ConnectionState() {
    const isConnected = useHMSStore(selectIsConnectedToRoom);

    return <div>{isConnected ? 'connected' : 'not connected, please join.'}</div>;
}

Refreshing the auth token in long-running sessions

The SDK reuses the auth token passed to join every time it reconnects after a network disconnection. If the call outlives the token's expiry (24 hours in the sample token server code), the next reconnect is rejected and the peer is removed from the room.

For sessions that can run longer than the token's validity, fetch a fresh token from your token service before the current one expires and pass it to updateAuthToken. The call stays connected; the new token is used for the next reconnect.

import { hmsActions } from './hms';

function getExpiry(token) {
    const payload = JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')));
    return payload.exp * 1000;
}

function scheduleTokenRefresh(token) {
    // refresh 10 minutes before expiry
    const refreshIn = getExpiry(token) - Date.now() - 10 * 60 * 1000;
    setTimeout(async () => {
        const newToken = await fetchTokenFromYourServer(); // same room and user_id
        hmsActions.updateAuthToken(newToken);
        scheduleTokenRefresh(newToken);
    }, Math.max(refreshIn, 0));
}

await hmsActions.join({ userName: 'Jon Snow', authToken: token });
scheduleTokenRefresh(token);

In React, call updateAuthToken on the actions returned by useHMSActions().

Leaving a room

Leaving a room should be quick. Once a user wishes to end their interaction in the room, they can choose to leave the meeting. 👋

We provide a simple, no fuss API to do exactly that. Invoke the leave method using hmsActions. You can use the current room state to render the UI accordingly post leave.

hmsActions.leave();

Leave on Navigating Away

If the user closes the tab without calling leave you might seem them as stuck for a few seconds for remote peers. This is because our server assumes that there might be a network issue and keeps a buffer waiting for the peer to rejoin. For this reason, it is important to call the leave api if we detect the user navigating away from the page. This includes, refreshing or closing the tab. We can set up leave to be called on window unload event.

window.addEventListener('beforeunload', () => hmsActions.leave());
window.addEventListener('onunload', () => hmsActions.leave());

Leave on tab close is automatically done when using HMSRoomProvider from our @100mslive/react-sdk. If you don't want to leave on page leave or tab close, you can opt out of this by passing the following prop.

<HMSRoomProvider leaveOnUnload={false} />