React Native SDK reference: hooks and errors

The complete surface of @voltkit-rtc/react-native 0.1.0. For how to use it, start with the React Native SDK guide and its call screen; React Native with Expo covers the config plugin. The client underneath is @voltkit-rtc/client, whose methods, events and options are on the JavaScript SDK page.

Errors

Every failure is an RpcError from @voltkit-rtc/client, with the same codes as every VoltKit SDK.

isTerminalError(code) and errorInfo(code) from @voltkit-rtc/client read the shared registry: whether a join refused with the code may be retried with the same token, and whether retrying later can help.

These are the codes the React Native SDK raises itself. Everything else, from the service and the client, is on Errors.

import { RpcError } from "@voltkit-rtc/client";

type MediaProblem = {
  permission?: "camera" | "microphone";
  status?: "denied" | "blocked";
  reason?: string;
  feature?: string;
  platform?: string;
};

/** Words for a media-unavailable error, or null for any other error. */
export function mediaProblem(err: unknown): string | null {
  if (!(err instanceof RpcError) || err.code !== "media-unavailable") return null;
  const data = (err.data ?? {}) as MediaProblem;
  if (data.permission) return data.status === "blocked" ? `Allow the ${data.permission} in Settings.` : `The ${data.permission} is needed.`;
  if (data.reason === "webrtc-missing") return "This build cannot make calls. Install the latest version of the app.";
  if (data.feature === "callService") return "Calls may stop when you leave the app.";
  return "The camera or microphone is not available.";
}

API reference

VoltkitProvider

<VoltkitProvider> holds one StreamClient for the components below it: it makes it with the options of reactNativeClientOptions, connects it, holds the phone's call audio and the call service while it is connected, and closes it on unmount. It is the React SDK's provider underneath, so every re-exported hook works below it.

The client it makes has the options reactNativeClientOptions({ background, clientOptions }) returns. Where react-native-webrtc's native code is missing, it makes no client: onError gets media-unavailable (webrtc-missing) and the hooks keep their defaults.

Hooks from the React SDK

Re-exported unchanged from @voltkit-rtc/react 0.1.1; the React SDK's hooks describe each.

useLocalMedia

useLocalMedia(): LocalMedia: the React SDK's useLocalMedia, with two additions.

VideoTrack

<VideoTrack> shows one video track in react-native-webrtc's RTCView.

One native stream per track, shared by its views and released before the connection it came on closes.

AudioTrack

<AudioTrack> renders nothing: remote sound plays without it.

useAudioOutput, setSpeakerphoneOn and selectAudioOutput

useAudioOutput(): AudioOutput returns where call audio plays and the calls that change it. Android only.

setSpeakerphoneOn(on): Promise<void> and selectAudioOutput(deviceId): Promise<void> are the same calls as functions. They work before any client exists, and the choice holds for the calls joined later. They reject with media-unavailable on iOS (data.platform "ios") and where the SDK's native module is missing.

useCallService

useCallService() returns the call service's state, for a settings screen or a warning.

The provider starts it when a call connects, if declared and callService is not false, and stops it when the call ends. Its notification has a Leave button, which ends the call, and swiping the app away ends the call too.

requestMediaPermissions, checkMediaPermissions and usePermissions

PermissionKind is "camera", "microphone" or "notifications" (the call's notification, Android 13 and later), and PermissionStatus is "granted", "denied" (the dialog may still show) or "blocked" (only the app's settings can grant it).

publish() asks for the camera and microphone by itself; these are for asking earlier, on a screen before the call. The SDK's own captures afterwards, such as a reconnect, only check and never ask: a dialog must not open in the background. On Android they use PermissionsAndroid; on iOS, react-native-webrtc's permission requests, where a refusal is blocked from then on. Below Android 13 there is no notification permission to ask for.

createClient and reactNativeClientOptions

createClient(wsUrl: string, token: string, options?: CreateClientOptions): StreamClient makes a StreamClient for React Native, not yet connected. CreateClientOptions is { background?: BackgroundOptions; clientOptions?: ClientOptions }, where BackgroundOptions is { pauseCamera?: boolean; pauseMic?: boolean } (defaults true and false). Pass the client to the provider's client prop, or call connect() yourself, and close() it when you are done: the provider never closes a client it was given. It throws media-unavailable (webrtc-missing) where react-native-webrtc's native module is missing. Never make one with new StreamClient(...) alone, which would look for a browser.

reactNativeClientOptions(options?: CreateClientOptions): ClientOptions returns the options such a client is made with: handlerName: "ReactNative106", platform: reactNativePlatform(), pauseCameraInBackground and pauseMicInBackground from background, and then your clientOptions, which win.

reactNativePlatform

reactNativePlatform(): ClientPlatform is the platform the client runs on in React Native (ClientOptions.platform of @voltkit-rtc/client 0.9.12): capture, devices and audio routing, streams and their release order, the app's visibility from the process lifecycle, the network, and native timers. One object per process, shared by every client. createClient and the provider pass it for you.

preflight

preflight(wsUrl: string, token: string, options?: ReactNativePreflightOptions): Promise<PreflightReport> is the pre-call check: it joins with a client of its own, publishes for a few seconds (5 s unless durationMs says otherwise) and leaves. React Native cannot make a test tone or picture, so without media it publishes the microphone when its permission is already granted, and otherwise tests the join alone; it never asks for a permission. The options are the client's PreflightOptions (media, durationMs, clientOptions) and background. It never rejects: read ok, then steps, path, rttMs, lossPct, uploadKbps, level and warnings. Give it a token for a test room of its own.

registerVoltkitGlobals

registerVoltkitGlobals(): boolean registers react-native-webrtc's globals, which mediasoup-client needs. Importing the package calls it, and calling it again does nothing. It returns false, without throwing, where react-native-webrtc's native module is missing.

SDK_VERSION

SDK_VERSION is this package's version, "0.1.0": what getDiagnostics() reports, beside react-native-webrtc's version and the Android version. When the app's native code was built from another version, the SDK warns in the log to build the app again.

Types

One import covers a component. This package's own: VoltkitProviderProps, AudioSessionOptions, CallServiceText, CallServiceState, BackgroundOptions, CreateClientOptions, ReactNativePreflightOptions, LocalMedia, LocalPublishOptions, VideoTrackProps, AudioTrackProps, MediaStreamLike, MediaStreamTrackLike, MediaTrackSettingsLike (react-native-webrtc's stream, track and track settings by shape: what useLocalMedia().stream and the track props are, with no DOM library needed), AudioOutput, PermissionKind, PermissionStatus, PermissionStatuses and Permissions. The React SDK's: RoomState, RemoteTrackFilter and WalletLowState. The client's: StreamClient, ClientOptions, ClientPlatform, ClosedReason, ConnectionState, ErrorCode, JoinResult, MediaDevice, AudioDeviceType, CameraFacing, DeviceKind, ParticipantInfo, PublishOptions, PreflightReport, RemoteTrack, Role, ChatMessage and the rest. They are types only: import values such as RpcError, ChatClient and isTerminalError from @voltkit-rtc/client.

The Expo config plugin

"@voltkit-rtc/react-native" in app.json's plugins, with the options cameraPermission, microphonePermission, android.camera, android.callService, android.callServiceCamera, android.screenShare, android.audioMode, android.hardwareEchoCancellation, ios.backgroundAudio and ios.voip. Defaults and what each writes: Configure the plugin.

Android manifest

What an app without Expo writes by hand, all in android/app/src/main/AndroidManifest.xml:

INTERNET, ACCESS_NETWORK_STATE, MODIFY_AUDIO_SETTINGS and the startup provider come with the SDK's own manifest. The full blocks are in the guide: Calls in the background and Audio routing.