React Native Quickstart Guide

Architecture

100ms is a cloud platform that allows developers to add video and audio conferencing to Web, Android and iOS applications.

The platform provides REST APIs, SDKs, and a dashboard that makes it simple to capture, distribute, record, and render live interactive audio, video.

Any application built using 100ms' SDK has 2 components.

  • Client: Use 100ms android, iOS, Web SDKs to manage connections, room states, render audio/video.

  • Server: Use 100ms' APIs or dashboard to create rooms, setup room templates, trigger recording or RTMP streaming, access events.

Architecture

Basic Concepts

  • Room A room is the basic object that 100ms SDKs return on successful connection. This contains references to peers, tracks and everything you need to render a live a/v app
  • Peer A peer is the object returned by 100ms SDKs that contains all information about a user - name, role, video track etc.
  • Track A track represents either the audio or video that a peer is publishing
  • Role A role defines who can a peer see/hear, the quality at which they publish their video, whether they have permissions to publish video/screenshare, mute someone, change someone's role.
  • Template A template is a collection of roles, room settings, recording and RTMP settings (if used), that are used by the SDK to decide which geography to connect to, which tracks to return to the client, whether to turn on recording when a room is created, etc. Each room is associated with a template.
  • Recording Recording is used to save audio/video calls for offline viewing. 100ms supports 2 kinds of recording - SFU recording and Browser recording.
  • RTMP RTMP streaming is used to live stream your video conferencing apps to platforms like YouTube, Twitch, MUX, etc.
  • Webhooks Webhook is an HTTP(S) endpoint used for pushing the notifications to your application. It will be invoked by 100ms servers to notify events of your room.

What are the steps to build a live app with 100ms?

  1. Create a template: Create a template and define roles, room settings - You can do this using the dashboard.
  2. Create a room using the above template: You can do this using the dashboard or our API.
  3. Integrate client SDK and join the above room: You'll need to generate a token for each peer that connects to a room.
  4. [Optional] Receive events: Create a webhook endpoint to receive server-side notifications about room usage (peer joining/leaving) or recording, RTMP out starting/ending.

Where should I start?

React Native QuickStart Guide

Getting started

Hello there! In this guide, we'll build a video conferencing application using our React Native SDK. We'll be using functional components with the powerful hooks provided by our SDK and build an app where you can have video call with your friends.

Prerequisites

To get started you should be familiar with basics of React Native.

Installing the dependencies

npm install --save @100mslive/react-native-hms

Permissions

For Android Permissions

Add following permissions in AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.INTERNET" />

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow Android Documentation for runtime permissions.

For iOS Permissions

Add following lines in Info.plist file

<key>NSCameraUsageDescription</key> <string>Please allow access to Camera to enable video conferencing</string> <key>NSLocalNetworkUsageDescription</key> <string>Please allow access to network usage to enable video conferencing</string> <key>NSMicrophoneUsageDescription</key> <string>Please allow access to Microphone to enable video conferencing</string>

Concepts

  • Room: When we join a conference call, the participants are said to be in a video call room.
  • Peer: A participant in the video call. You are the local peer while others are remote peers.
  • Track: Media. There are two types of track a peer can have - audio and video.

Initializing the SDK

Call the function given below to initialise the SDK

import HmsManager from '@100mslive/react-native-hms'; const hmsInstance = await HmsManager.build();

This function will return the instance of HMSSDK that will be used for calling various functions and accessing data.

Add event listeners

Add event listeners for all the events you want updates from such as onPreview, onJoin, onError etc. The actions can be found in HMSUpdateListenerActions class.

The event handlers are the way of handling any update happening in hms. It is advised to attach all the event listeners so you don't miss any update.

import HmsManager, { HMSUpdateListenerActions } from 'react-native-hms'; // instance acquired from build() method hmsInstance.addEventListener( HMSUpdateListenerActions.ON_PREVIEW, onPreview // function that will be called on Preview success ); hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError); hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoin);

Joining a room

To join a room 3 fields are required:

  • username: The name of the user. This is the value that will be set on the peer object and be visible to everyone connected to the room.
  • authToken: A client-side token that is used to authenticate the user. You can read about how to generate this token here.
  • userID: A unique ID that will be used to identify user.
  • roomID (optional): The ID of the room that you wanna join
import HmsManager, { HMSUpdateListenerActions, HMSConfig, } from 'react-native-hms'; // instance acquired from build() method const HmsConfig = new HMSConfig({ authToken, userID, roomID, userName }); hmsInstance.preview(HmsConfig); // to start preview // or hmsInstance.join(HmsConfig); // to join a room

Leaving the room

Before we go ahead with adding video, let us add a way to leave the room as well. We can call the leave method on hmsActions to leave the room.

Once you're done with a call and want to exit, call leave on the HMSSDK instance you created to join it. Also you can always acquire instance of HMS using build() method.

hmsInstance.leave();

Render video

Let us next add a way to show a tile for every participant in the room. We use HmsView component to render video on screen. This component takes sink, trackId and scaleType of HMSVideoTrack and renders the corresponding track. The prop scaleType can be selected from HMSVideoViewMode as required. When sink is true the video will be visible and when it is false video would be removed. It is ios only prop for android it is handled by the package itself. We can also add mirror a boolean prop as true to flip videos horizontally. Here is a code snippet explaining the way to link a videoTrack to HmsView.

import { HmsView, HMSVideoViewMode } from 'react-native-hms'; const styles = StyleSheet.create({ hmsView: { height: '100%', width: '100%', }, }); <HmsView sink={true} style={styles.hmsView} trackId={trackId} mirror={true} scaleType={HMSVideoViewMode.ASPECT_FILL} />;

There are 2 types of Peers - a localPeer & remotePeers. To extract trackId from peers we can use following code snippet.

const localTrackId = hmsInstance.localPeer.videoTrack.trackId; const remoteTrackId = hmsInstance.remotePeers[index].videoTrack.trackId;

These track IDs can directly be passed to HmsView component

A Pro tip: for fastest updates we can use ON_PEER_UPDATE and ON_TRACK_UPDATE listeners, these listeners get updated localPeer and remotePeers whenever there is any event related to these values.

HmsInstance.addEventListener( HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener ); HmsInstance.addEventListener( HMSUpdateListenerActions.ON_TRACK_UPDATE, onTrackListener ); const onPeerListener = ({ remotePeers, localPeer, }: { room?: any, localPeer: any, remotePeers: any, }) => { updateVideoIds(remotePeers, localPeer); // this function can be used to update local and remotePeers on React-Native side }; const onTrackListener = ({ remotePeers, localPeer, }: { room?: any, localPeer: any, remotePeers: any, }) => { updateVideoIds(remotePeers, localPeer); };

Mute/Unmute local Audio/Video tracks

Mute is something that applies to both audio and video. When you mute audio, you can't be heard by other people. When you mute video, you will not be broadcasting your video to other people.

It can be invoked only on local (you) peers' audio or video tracks.

You get a reference to your own local peer from localPeer on HMSSDK instance.

// instance acquired from build() method hmsInstance.localPeer.localAudioTrack().setMute(true); // audio track hmsInstance.localPeer.localVideoTrack().setMute(true); // video track