Integrate Real Time Audio and Video conferencing, Interactive Live Streaming, and Chat in your apps with 100ms React Native SDK.
With support for HLS and RTMP Live Streaming and Recording, Picture-in-Picture (PiP), one-to-one Video Call Modes, Audio Rooms, Video Player and much more, add immersive real-time communications to your apps.
| Package | Version |
|---|---|
| @100mslive/react-native-room-kit |  |
| @100mslive/react-native-hms | |
| @100mslive/react-native-video-plugin |  |
📖 Read the Complete Documentation here: https://www.100ms.live/docs/react-native/v2/foundation/basics
📲 Download the Example iOS app here: https://testflight.apple.com/join/v4bSIPad
🤖 Download the Example Android app here: https://appdistribution.firebase.dev/i/7b7ab3b30e627c35
To get a better understanding of how the example app is structured, what to do on onJoin, onTrack and onPeer listeners, creating PeerTrackNodes, how to use Redux, and what type of layouts and sorting you can implement in your app, checkout Example App's README
To run the Example app on your system, follow these steps -
- In the project root, run
npm install - Go to the example folder,
cd example - In the example folder, run
npm install - To run on Android, run
npx react-native run-android - To run on iOS, first install the pods in iOS folder,
cd ios; pod install. Then, set the Correct Development Team in Xcode Signing & Capabilities section. Then, in example folder, runnpx react-native run-ios
Troubleshooting Guide for resolving issues in running the Example app is available here.
- Support for React Native 0.64.4 or above
- Support for Java 8 or above
- Support for Android API level 24 or above
- Xcode 13 or above
- Support for iOS 12 or above
- React Native 0.68.0 or above
- Java 11 or above
- Android API level 33 or above
- Xcode 14 or above
- iOS 16 or above
-
The Android SDK supports Android API level 21 and higher. It is built for armeabi-v7a, arm64-v8a, x86, and x86_64 architectures. Devices running Android OS 11 or above is recommended.
-
iPhone & iPads with iOS version 12 or above are supported. Devices running iOS 16 or above is recommended.
npm install @100mslive/react-native-hms --save📲 Download the Sample iOS App here: https://testflight.apple.com/join/v4bSIPad
🤖 Download the Sample Android App here: https://appdistribution.firebase.dev/i/7b7ab3b30e627c35
More information about Integrating the SDK is available here.
Add following lines in Info.plist file
<key>NSCameraUsageDescription</key>
<string>Please allow access to Camera to enable video conferencing</string>
<key>NSMicrophoneUsageDescription</key>
<string>Please allow access to Microphone to enable video conferencing</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Please allow access to network usage to enable video conferencing</string>Add following permissions in AndroidManifest.xml
<uses-feature android:name="android.hardware.camera.autofocus"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />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.
We suggest using react-native-permission to acquire permissions from both platforms.
More information about Audio Video Permission on iOS & Android is available here.
The package exports all the classes and a HMSSDK class that manages everything.
First invoke the build method which returns an instance of HMSSDK. Save this instance to perform all actions related to 100ms.
import { HMSSDK } from "@100mslive/react-native-hms";
/**
* create HMSSDK instance using the build method & save it for further usage
*
* 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();We can get the authentication token using room-code from meeting URL.
Let's understand the subdomain and code from the sample URL
In this sample url: http://100ms-rocks.app.100ms.live/meeting/abc-defg-hij
- Subdomain is
100ms-rocks - Room code is
abc-defg-hij
Now to get the room-code from meeting URL, we can write our own logic or use the getCode method from here
To generate token we will be using getAuthTokenByRoomCode method available on HMSSDK instance. This method has roomCode as a required
parameter and userId & endpoint as optional parameter.
Let's checkout the implementation:
/**
* `getAuthTokenByRoomCode` returns a promise which is resolved with "auth token"
* checkout {@link https://www.100ms.live/docs/react-native/v2/how--to-guides/install-the-sdk/hmssdk#what-does-destroy-method-do}
*/
const token = await hmsInstance.getAuthTokenByRoomCode("YOUR_ROOM_CODE");
/**
* Create `HMSConfig` with the above auth token and username
*/
const hmsConfig = new HMSConfig({
authToken: token,
username: "John Appleseed",
});To test audio/video functionality, you need to connect to a 100ms Room. Please check the following steps for the same -
- Navigate to your 100ms dashboard or create an account if you don't have one.
- Use the
Video Conferencing Starter Kitto create a room with a default template assigned to it to test this app quickly. - Go to the Rooms page in your dashboard, click on the
Room Idof the room you created above, and click on theJoin Roombutton on the top right. - You will see 100ms demo URLs for the roles created when you deployed the starter kit; you can click on the 'key' icon to copy the token and update the
AUTH_TOKENvariable in "App.js" file.Token from 100ms dashboard is for testing purposes only, For production applications you must generate tokens on your own server. Refer to the Management Token section in Authentication and Tokens guide for more information.
Add Event Listeners to get notified about actions happening in the 100ms Room.
The most commonly used Events are onJoin, onPeerUpdate & onTrackUpdate. All the available actions can be found in the HMSUpdateListenerActions class.
The Event Listeners are to be used for handling any update happening in 100ms Room.
const hmsInstance = await HMSSDK.build();
// instance acquired from build() method
hmsInstance.addEventListener(
HMSUpdateListenerActions.ON_JOIN,
joinSuccess, // function that will be called Joining a Room is successful
);The detailed QuickStart Guide is available here.
To interact with peers 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 -
-
User Name - The name which should be displayed to other peers in the room.
-
Authentication Token - The Client side Authentication Token generated by the Token Service. Details about how to create Auth Tokens are available here.
Additionally, you can also pass these fields while Joining a Room -
-
Track Settings - Such as joining a Room with Muted Audio or Video using the
HMSTrackSettingsobject. More information is available here. -
Peer Metadata - This can be used to pass any additional metadata associated with the user using
metadataofHMSConfigobject. For Eg: user-id mapping at the application side. More information is available here.
NOTE: ON_JOIN Event Listener must be attached before calling join function to receive the event callback.
// create HMSSDK instance using the build function
const hmsInstance = await HMSSDK.build();
// Generate 100ms Auth Token by Room Code
const token = await hmsInstance.getAuthTokenByRoomCode("abc-defg-hij"); // Sample Room Code
// 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, any errors that occur, etc.
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoinSuccess);
hmsInstance.addEventListener(
HMSUpdateListenerActions.ON_PEER_UPDATE,
onPeerUpdate,
);
hmsInstance.addEventListener(
HMSUpdateListenerActions.ON_TRACK_UPDATE,
onTrackUpdate,
);
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);
// Next, create an object of HMSConfig class using the available joining configurations.
let config = new HMSConfig({
authToken: token, // client-side token generated by `getAuthTokenByRoomCode` method
username: "John Appleseed",
});
// Now, we are primed to join the room. All you have to do is calling join by passing the config object
hmsInstance.join(config);More information about Joining a Room is available here.
For invoking any actions simply use the HMSSDK instance created in above steps. Few common examples of using it are as follows -
// To Mute Audio of local peer - other peers will stop hearing audio
hmsInstance?.localPeer?.localAudioTrack()?.setMute(true);
// To Mute Video of local peer - other peers will stop seeing video
hmsInstance?.localPeer?.localVideoTrack()?.setMute(true);
// Switch Camera from Front to Back or vice-versa
hmsInstance?.localPeer?.localVideoTrack()?.switchCamera();
// Leave the ongoing Room (async function)
await hmsInstance?.leave();
// To send a Chat Message to all peers in Room
await hmsInstance?.sendBroadcastMessage("Hello Everyone! 👋");More information about using HMSSDK APIs is available here.
It all comes down to this. All the setup so far has been done so that we can show Live Streaming Video in our beautiful apps.
100ms React Native SDK provides HmsView component that renders the video on the screen. You can access HmsView from the HMSSDK instance created in above steps.
We simply have to pass a Video Track's trackId to the HmsView to begin automatic rendering of Live Video Stream.
We can also optionally pass props like key, scaleType, mirror to customize the HmsView component.
// get HmsView from the HMSSDK instance created earlier
const HmsView = hmsInstance.HmsView;
<HmsView trackId={videoTrackId} key={videoTrackId} style={styles.hmsView} />;
const styles = StyleSheet.create({
hmsView: {
height: "100%",
width: "100%",
},
});-
One
HmsViewcomponent can only be connected with one videotrackId. To display multiple videos you have to create multiple instances ofHmsViewcomponent. -
It's recommended to always pass the
keyproperty while creatingHmsView. If a null or undefinedtrackIdis passed inHmsViewyou will have to unmount and remount with the newtrackId. Using thekeyprop and passingtrackIdto it automatically achieves this. -
HmsViewcomponent requireswidthandheightinstyleprop to set bounds of the tile that will show the video stream. -
Once the requirement of that
HmsViewis finished it should ALWAYS be disposed. -
Recommended practice is to show maximum of 3 to 4
HmsViewon a single page/screen of the app. This avoids overloading network data consumption & video decoding resources of the device.
More information about Rendering Videos is available here.
Always 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. The following code snippet shows a simple example of attaching Track Updates Event Listener & using it to show a Video.
// In this example code snippet, We are keeping things very simple.
// You will get an overview of how to render `HMSView`s for list of `trackId`s and how to keep that list up to date.
// We don't need `ON_PEER_UPDATE` event listener for keeping track of only `trackId`s.
// So, we have registered only `ON_TRACK_UPDATE` event listener here
const [trackIds, setTrackIds] = useState<string[]>([]);
const onTrackListener = (data: { peer: HMSPeer; track: HMSTrack; type: HMSTrackUpdate }) => {
// We will only consider Video tracks for this example
if (data.track.type !== HMSTrackType.VIDEO) return;
// If Video track is added, add trackId to our list
if (data.type === HMSTrackUpdate.TRACK_ADDED) setTrackIds(prevTrackIds => [...prevTrackIds, data.track.trackId]);
// If Video track is removed, remove trackId from our list
if (data.type === HMSTrackUpdate.TRACK_REMOVED) setTrackIds(prevTrackIds => prevTrackIds.filter(prevTrackId => prevTrackId !== data.track.trackId));
};
hmsInstance.addEventListener(
HMSUpdateListenerActions.ON_TRACK_UPDATE,
onTrackListener
);
// Render multiple HMSView for trackIds inside FlatList
// Note: HMSView will render blank if video track of peer is muted, Make sure video of peers is not muted.
<FlatList
data={trackIds} // trackIds is an array of trackIds of video tracks
keyExtractor={(trackId) => trackId}
renderItem={({ item }) => <HMSView key={item} trackId={item} style={{ width: '100%', height: 300 }} {...} />}
{...}
/>More information about Rendering Videos is available here.
In the 100ms Example App we have shown how to set up the various listeners, what data to store in Redux and what all features you can implement.
We have also implemented multiple views which are commonly used. Checkout the videos & relevant code in the Example app.
📖 Read the Complete Documentation here: https://www.100ms.live/docs/react-native/v2/foundation/basics
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent