User Experience Guidelines - React Native

These practices help you guide participants through setup on mobile devices, keep them informed about what is happening in the live stream, and offer fallbacks when something goes wrong.

Configure Precall & Permissions

Set up a precall flow where users can preview their audio and video devices, toggle their microphone or camera, and test network quality. Always request camera, microphone, and Bluetooth permissions before joining the room, and provide a friendly reminder when a permission is denied so users know how to enable it from device settings. Screen sharing asks the user for consent when sharing starts, so it needs no request before joining.

Use requestPermission() and, on Android, requestBluetoothPermission() from useMediaDevice. On Android, the SDK does not ask for camera and microphone access itself, so without this step the camera and microphone stay off. requestPermission() does not throw when the user refuses: a denied permission is false in the Map it returns. The Precall Setup guide shows each step, including the network test.

Surface Room State Changes

Listen to room-level events of useRoom (onRoomStateChanged, onRoomJoined, onRoomLeft, onRecordingStateChanged, etc.) and mirror those changes in the UI. Showing banners or subtle toasts when recording starts, when the stream goes live, or when a moderator changes participant roles keeps everyone aligned without interrupting the session.

Notify Users About Participant Activity

Send lightweight notifications when participants join or leave, are invited on stage, or raise their hands. This helps presenters respond quickly, and gives the audience confidence that their actions were acknowledged.

Handle Device Transitions Gracefully

Expose controls that let users switch between available microphones, cameras, and speakers during the session. When no device is detected (for example, an external mic is unplugged), provide clear UI prompts describing how to recover—such as reconnecting hardware or enabling the device again from system settings.

React to Errors Immediately

Pass an onError callback to useRoom so that issues such as token failures, recording limits, or track errors can be surfaced to the user with actionable next steps. SDK methods also return a Promise that rejects when they fail, so catch those errors too. Offer retry buttons whenever possible, and log diagnostic information that can be shared with support. The Developer Experience Guidelines list recommended fixes for each error category.

Monitor Quality & Bandwidth

Collect local statistics (bitrate, packet loss, frame rate) and expose them to power users or support teams. If you detect degraded quality, nudge users to switch to audio-only, reduce the number of on-stage participants, or pause screen sharing until the connection stabilizes.