React Native Video SDK
The EnableX React Native SDK (package: enx-rtc-react-native) brings real-time audio and video
to cross-platform mobile apps built with React Native. It uses a JSX component-driven approach — you
declare the video room as an <EnxRoom> component in your render tree — while
imperative actions are called through the Enx API class. The SDK handles all WebRTC internals
and signalling; your code focuses on what users see and do.
- SDK v2.3.54 — Released: February 4, 2026
- Cross-platform: runs on iOS and Android from a single codebase
- Tested with React Native 0.83 (New Architecture) — see Requirements
- iOS target: iOS 13+ (real device only) / Android: API 24+
- Bundles EnxRTCiOS 3.1.5 and EnxRtcAndroid 3.0.3
React Native SDK v2.3.54 — Released February 4, 2026
Before writing any React Native code, your backend server must have three things in place. These are server-side responsibilities — none of these credentials or operations should ever be performed inside the mobile app itself.
1. App Credentials
Log in to the EnableX Portal and create a project
to obtain your app_id and app_key. These credentials authenticate your server
when calling the EnableX Video API. Never embed them in the React Native app — treat
them as server secrets.
2. A Room
A Room is a virtual session space. Create it via the Video REST API from your server and store the returned
room_id. The room persists until you delete it, so you typically create it once per meeting
and reuse it across participants.
3. A Token per Participant
Each participant who joins the session needs their own short-lived token. Your server generates the token
by calling the Create Token API with the room_id and participant details, then passes it to
the React Native app. The app uses this token when connecting to the room via the
<EnxRoom> component.
app_key is required to generate tokens
— if it is embedded in the app, it can be extracted and abused to create unauthorized sessions.
This section walks you through adding enx-rtc-react-native to your own React Native app, from
a fresh npm install to a working build on both iOS and Android. Follow the steps in order.
The step that matters most is the iOS Podfile configuration — it prevents a static/dynamic framework
conflict that otherwise breaks pod install or crashes the app at launch.
Requirements
The plugin has been tested against the versions below. Older toolchains may work, but these are the versions EnableX verifies each release against.
| Item | Requirement / Tested Version |
|---|---|
| Node.js | 18 or newer (tested with Node 20) |
| React Native | Tested with React Native 0.83.0 and React 19.1.1, New Architecture enabled |
| Xcode + CocoaPods | Latest Xcode; CocoaPods 1.16 or newer |
| iOS deployment target | iOS 13.0 minimum (the sample app uses 15.0) |
| iOS test device | A real iPhone or iPad — the iOS Simulator is not supported |
| Android | minSdkVersion 24, compileSdkVersion / targetSdkVersion 35, Android Gradle Plugin 8.12, Gradle 8.13 (tested) |
| EnableX account | An EnableX project and an application server that creates room tokens (see Prerequisites) |
How the Plugin Is Packaged
The plugin is a thin React Native bridge. The real-time audio and video work is done by the EnableX native SDKs, which in turn depend on WebRTC and Socket.IO. You do not add these native SDKs yourself — they are pulled in automatically when you install the plugin. Understanding what gets pulled in, and how each piece is linked, explains why the iOS setup below looks the way it does.
| Platform | Component | Version | How It Gets into Your App | Linkage |
|---|---|---|---|---|
| iOS | RNEnxRtc (plugin bridge) | 2.3.54 | Autolinked from node_modules | Static (like other RN pods) |
| iOS | EnxRTCiOS | 3.1.5 | Dependency of the RNEnxRtc podspec | Dynamic (prebuilt xcframework) |
| iOS | EnablexWebRTC | 2.0.2 | Dependency of EnxRTCiOS | Dynamic (prebuilt xcframework) |
| iOS | Socket.IO-Client-Swift | 16.1.1 | Dependency of the RNEnxRtc podspec | Must be dynamic (Podfile hook) |
| iOS | Starscream | 4.0.8 | Dependency of Socket.IO-Client-Swift | Must be dynamic (Podfile hook) |
| Android | EnxRtcAndroid | 3.0.3 (.aar) | Bundled inside the plugin | Gradle sub-project |
| Android | libwebrtc | .aar | Bundled inside the plugin | Gradle sub-project |
| Android | io.socket:socket.io-client | 2.1.1 | Downloaded from Maven Central | Regular dependency |
Why iOS Needs Mixed Framework Linkage
- Recent React Native versions — and most community libraries — expect CocoaPods to build pods as static frameworks.
EnxRTCiOSandEnablexWebRTCare shipped as prebuilt dynamic xcframeworks, and they needSocket.IO-Client-Swift(and its dependencyStarscream) to also be dynamic so that all of them share a single copy at runtime.- If everything is static, Socket.IO is linked into the wrong place and you get duplicate-symbol or
Library not loaded: @rpath/...errors. If everything is dynamic, many React Native libraries fail to build. - The fix is to build all pods as static and switch only
Socket.IO-Client-SwiftandStarscreamto dynamic using apre_installhook. This is exactly what the iOS Setup configures.
.aar files
inside the plugin. You only need to register those two modules in your app's settings.gradle
(see Android Step 1).
Install the NPM Package
From the root folder of your React Native project, run:
npm install enx-rtc-react-native --save
or, if you use Yarn:
yarn add enx-rtc-react-native
React Native autolinking detects the plugin on both platforms. Do not run
react-native link — it is no longer needed and may create duplicate links.
iOS Setup
iOS setup consists of configuring the Podfile linkage, adding privacy permissions, installing pods, and building on a real device. Complete each step before moving to the next.
Step 1 — Update ios/Podfile
Open ios/Podfile and make it look like the example below. Replace YourAppName
with the name of your iOS target (the same name you see in Xcode). Three parts of this file matter:
- (A)
use_frameworks! :linkage => :static— builds all pods as static frameworks. - (B) The
pre_installhook — turnsSocket.IO-Client-SwiftandStarscreaminto dynamic frameworks. - (C) The
post_installhook — keeps the standard React Native post-install step and sets the C++ language standard to C++20.
# Resolve react_native_pods.rb with node to allow for hoisting
require Pod::Executable.execute_command('node', ['-p',
'require.resolve(
"react-native/scripts/react_native_pods.rb",
{paths: [process.argv[1]]},
)', __dir__]).strip
platform :ios, min_ios_version_supported
prepare_react_native_project!
# Do NOT use the USE_FRAMEWORKS environment-variable block from the
# default template. Leave it commented out:
# linkage = ENV['USE_FRAMEWORKS']
# if linkage != nil
# use_frameworks! :linkage => linkage.to_sym
# end
target 'YourAppName' do
config = use_native_modules!
# (A) Build all pods as STATIC frameworks
use_frameworks! :linkage => :static
use_react_native!(
:path => config[:reactNativePath],
:app_path => "#{Pod::Config.instance.installation_root}/.."
)
# (B) Build Socket.IO and Starscream as DYNAMIC frameworks
pre_install do |installer|
installer.pod_targets.each do |pod|
if [
'Socket.IO-Client-Swift',
'Starscream'
].include?(pod.name)
def pod.build_type
Pod::BuildType.dynamic_framework
end
end
end
end
# (C) Standard React Native post-install + C++20
post_install do |installer|
react_native_post_install(
installer,
config[:reactNativePath],
:mac_catalyst_enabled => false
)
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'c++20'
end
end
end
end
pod 'EnxRTCiOS' or
pod 'Socket.IO-Client-Swift' to your Podfile. Both are declared by the plugin's podspec with
the exact versions it was built against (EnxRTCiOS 3.1.5, Socket.IO-Client-Swift ~> 16.1.1).
Adding them yourself with different versions causes resolution errors.
USE_FRAMEWORKS=dynamic. Setting this environment variable when
running pod install overrides the static linkage set in (A).
pre_install or
post_install block (for example, from another library), do not add a second one —
CocoaPods allows only one of each. Merge the code into your existing block. If another library in your app
also needs to be dynamic, add its pod name to the list in hook (B).
Step 2 — Xcode 26 or Newer Only: fmt Build Fix
With Xcode 26, React Native's fmt pod can fail to compile with a
call to consteval function ... is not a constant expression error. This is a compiler issue,
not an EnableX issue. If you see it, add the following lines inside your post_install block,
directly after the react_native_post_install(...) call. Skip this step on older Xcode versions.
fmt_base_h = File.join(installer.sandbox.root, 'fmt/include/fmt/base.h')
if File.exist?(fmt_base_h)
content = File.read(fmt_base_h)
old_guard = '__apple_build_version__ < 14000029L'
new_guard = '(__apple_build_version__ < 14000029L || __apple_build_version__ >= 21000000L)'
if content.include?(old_guard) && !content.include?(new_guard)
File.write(fmt_base_h, content.gsub(old_guard, new_guard))
Pod::UI.puts 'Patched fmt/base.h for Xcode 26+'
end
end
Step 3 — Add Camera and Microphone Permissions to Info.plist
iOS requires a usage description for every privacy-sensitive resource your app accesses. Without these
keys, iOS terminates the app the first time the camera or microphone is used. Open
ios/YourAppName/Info.plist and add:
<key>NSCameraUsageDescription</key>
<string>This app uses the camera for video calls.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone for audio and video calls.</string>
Step 4 — Install the Pods
cd ios
pod install --repo-update
cd ..
At the end of the output, CocoaPods should list RNEnxRtc, EnxRTCiOS,
EnablexWebRTC, Socket.IO-Client-Swift, and Starscream among the
installed pods.
Step 5 — Verify the Linkage (Recommended)
A quick check in Xcode confirms that the Podfile hooks took effect before you spend time on a full build:
- Open
ios/YourAppName.xcworkspace— always the.xcworkspace, never the.xcodeproj. - In the Project navigator, select the Pods project → target Socket.IO-Client-Swift → Build Settings, and search for Mach-O Type. It must be Dynamic Library. Repeat for Starscream.
- Any other React Native library target (for example,
react-native-screens) should show Static Library.
Step 6 — Build and Run on a Real Device
- Connect an iPhone or iPad, select it as the run destination, and set your signing team under Signing & Capabilities.
- Press Run in Xcode, or run the following from the project root:
npx react-native run-ios --device
AppDelegate, and the plugin's Swift code is
compiled inside its own pod.
Android Setup
Android setup consists of registering the bundled native SDK modules, checking SDK levels, enabling AndroidX and Jetifier, and declaring permissions. Unlike iOS, there is no linkage conflict to resolve.
Step 1 — Register the Bundled Native SDKs in android/settings.gradle
The plugin ships the EnableX Android SDK and WebRTC as two local .aar modules,
EnxRtcAndroid and LibWebRtc. The plugin depends on them by project name, so your
app must include them. Add these lines at the end of android/settings.gradle:
include(":EnxRtcAndroid")
project(":EnxRtcAndroid").projectDir = file('../node_modules/enx-rtc-react-native/android/EnxRtcAndroid')
include(":LibWebRtc")
project(":LibWebRtc").projectDir = file('../node_modules/enx-rtc-react-native/android/LibWebRtc')
Project with path ':EnxRtcAndroid' could not be found. In a monorepo where
node_modules is hoisted to a parent folder, adjust the ../node_modules/... path
accordingly.
Your complete settings.gradle should look similar to this:
pluginManagement { includeBuild("../node_modules/@react-native/gradle-plugin") }
plugins { id("com.facebook.react.settings") }
extensions.configure(com.facebook.react.ReactSettingsExtension) { ex ->
ex.autolinkLibrariesFromCommand()
}
rootProject.name = 'YourAppName'
include ':app'
includeBuild('../node_modules/@react-native/gradle-plugin')
include(":EnxRtcAndroid")
project(":EnxRtcAndroid").projectDir = file('../node_modules/enx-rtc-react-native/android/EnxRtcAndroid')
include(":LibWebRtc")
project(":LibWebRtc").projectDir = file('../node_modules/enx-rtc-react-native/android/LibWebRtc')
Step 2 — Check android/build.gradle
Make sure minSdkVersion is 24 or higher:
buildscript {
ext {
minSdkVersion = 24
compileSdkVersion = 35
targetSdkVersion = 35
// ...
}
}
Step 3 — Enable AndroidX and Jetifier in android/gradle.properties
android.useAndroidX=true
android.enableJetifier=true
Jetifier is required because one of the SDK's transitive libraries still uses the old Android Support packages. Without it, the build fails with duplicate-class errors.
Step 4 — Add Permissions to AndroidManifest.xml
Add the following inside the <manifest> tag of
android/app/src/main/AndroidManifest.xml. Bluetooth and network-state permissions are
already merged in from the EnableX SDK, so you do not need to add them.
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<!-- Foreground service: needed for screen share and calls in background -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
FOREGROUND_SERVICE_CAMERA and FOREGROUND_SERVICE_MICROPHONE.
Step 5 — Request Runtime Permissions Before Joining a Room
On Android 6 and above, camera and microphone permissions must be granted at runtime — declaring
them in the manifest is not enough. Ask for them before rendering <EnxRoom>; if the
user declines, the session connects with black video or no audio.
import { PermissionsAndroid, Platform } from 'react-native';
async function requestCallPermissions() {
if (Platform.OS !== 'android') return true;
const result = await PermissionsAndroid.requestMultiple([
PermissionsAndroid.PERMISSIONS.CAMERA,
PermissionsAndroid.PERMISSIONS.RECORD_AUDIO,
PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT,
]);
return Object.values(result).every(
v => v === PermissionsAndroid.RESULTS.GRANTED,
);
}
On iOS, the system shows the permission prompts automatically the first time the camera or microphone is
used, using the texts from Info.plist.
Step 6 — Build and Run
npx react-native run-android
No changes to MainApplication are needed — EnxRtcPackage is registered
automatically by autolinking.
Troubleshooting
Most installation problems trace back to a missed step above. Find the symptom you are seeing, then apply the fix. After changing the Podfile or Gradle files, do a clean reinstall to clear stale build artifacts.
iOS
-
pod install: "Unable to find a specification for EnxRTCiOS"
Your local CocoaPods spec repo is out of date. Runpod install --repo-update. -
pod install: "target has transitive dependencies that include statically linked binaries"
The linkage is not set as described. Useuse_frameworks! :linkage => :statictogether with thepre_installhook from iOS Step 1. -
App crashes at launch: "dyld: Library not loaded: @rpath/SocketIO.framework" (or Starscream)
Socket.IO or Starscream was built static or was not embedded. Check the pod names in thepre_installhook, then do a clean reinstall. -
Duplicate symbol errors mentioning SocketIO or Starscream
Socket.IO is linked both statically and dynamically. Remove any manualpod 'Socket.IO-Client-Swift'line, then do a clean reinstall. -
Build fails only for the iOS Simulator
EnxRTCiOSships only a device (arm64) slice. Run on a real iPhone or iPad. -
Xcode 26: "call to consteval function ... is not a constant expression" in
fmt
This is an Xcode 26 compiler issue in React Native'sfmtpod. Add the patch from iOS Step 2. -
Changed the Podfile but errors persist
StalePodsor DerivedData are still in use. Do a clean reinstall.
Android
-
"Project with path ':EnxRtcAndroid' could not be found"
The bundled.aarmodules are not registered. Add theincludelines from Android Step 1 tosettings.gradle. -
"Duplicate class android.support..." or "android.arch.lifecycle"
Jetifier is disabled. Setandroid.enableJetifier=trueingradle.properties. -
Manifest merger fails on
${applicationId}.provider
Your app already declares aFileProviderwith the same authority. Use a single provider, or addtools:replace="android:authorities"to your own provider.
Both Platforms
-
Black video or no audio
Camera or microphone permission was not granted. Check theInfo.plistkeys on iOS and the runtime permission request on Android.
Clean Reinstall
When configuration changes do not seem to take effect, clear all cached build output and reinstall:
# iOS
cd ios
rm -rf Pods Podfile.lock build
rm -rf ~/Library/Developer/Xcode/DerivedData/*
pod install --repo-update
cd ..
# Android
cd android
./gradlew clean
cd ..
# Metro cache
npx react-native start --reset-cache
Final Checklist
Before you move on to writing session code, confirm every item below.
Both platforms
enx-rtc-react-nativeadded withnpm install(oryarn add).
iOS
- Podfile uses
use_frameworks! :linkage => :static. - The
pre_installhook makesSocket.IO-Client-SwiftandStarscreamdynamic. - No manual
pod 'EnxRTCiOS'orpod 'Socket.IO-Client-Swift'lines; theUSE_FRAMEWORKSenvironment variable is not set. NSCameraUsageDescriptionandNSMicrophoneUsageDescriptionare present inInfo.plist.pod install --repo-updatesucceeded, and you are testing on a real device.
Android
:EnxRtcAndroidand:LibWebRtcare included insettings.gradle.minSdkVersionis 24 or higher;android.useAndroidXandandroid.enableJetifierare set totrue.- Manifest permissions are added, and runtime permissions are requested before joining a room.
At the top of any component that uses the SDK, import the classes you need from the package. A typical session screen uses these four exports:
import { Enx, EnxRoom, EnxStream, EnxPlayerView } from 'enx-rtc-react-native';
Here is what each export provides:
-
Enx— The main API class. All imperative actions — publish, mute, record, disconnect, and more — are called as static methods on this class. You do not instantiate it; you callEnx.someMethod()directly. -
EnxRoom— A JSX component that represents the video session. You render it in your component tree, passing the session token and configuration as props. When it mounts, it connects to the room and begins firing callbacks via theeventHandlersprop. -
EnxStream— Publishes the local camera and microphone stream. Place it inside<EnxRoom>. It wraps audio and video track metadata and is referenced when publishing, subscribing, or muting. -
EnxPlayerView— A JSX component for rendering a local or remote video stream on screen. Embed one instance for each participant whose video you want to display, and attach the corresponding stream to it. -
EnxToolBarView— An optional, ready-made in-call toolbar you can drop into your call screen instead of building your own controls.
Minimal Example
The example below shows how the components fit together. <EnxRoom> connects to the room
with a token created by your application server, <EnxStream> inside it publishes the local
stream, and once the local stream ID is known, <EnxPlayerView> renders it on screen.
import { EnxRoom, EnxStream, EnxPlayerView, Enx } from 'enx-rtc-react-native';
// token: room token created by your application server
<EnxRoom
token={token}
eventHandlers={roomEventHandlers}
localInfo={localStreamInfo}
roomInfo={roomInfo}>
<EnxStream
style={{ width: 0, height: 0 }}
eventHandlers={streamEventHandlers}
/>
</EnxRoom>
{localStreamId ? (
<EnxPlayerView
streamId={String(localStreamId)}
isLocal="local"
style={{ width: 100, height: 100 }}
/>
) : null}
requestCallPermissions() and wait
for it to resolve before rendering <EnxRoom>.
Unlike browser-based SDKs that use addEventListener, the EnableX React Native SDK uses
callbacks (also called event handlers) to deliver asynchronous notifications. This is
how the SDK tells your app that the room connected, a new participant joined, a stream was added, or
any other session event occurred.
You provide your callbacks by passing an eventHandlers prop to the <EnxRoom>
component. This prop accepts a plain JavaScript object where each key is a callback name and the
corresponding value is the handler function. When an event occurs, the SDK invokes the matching handler
and passes an event data object as the argument.
The general pattern looks like this:
const eventHandlers = {
roomConnected: (data) => {
console.log('Connected to room:', data);
},
streamAdded: (data) => {
console.log('New stream:', data);
},
userDisconnected: (data) => {
console.log('User left:', data.clientId);
}
};
<EnxRoom
token={sessionToken}
eventHandlers={eventHandlers}
// ... other props
/>
EnxRoom component mounts. Define them
in state or as stable references (useCallback in function components, or class methods in
class components) to prevent unnecessary re-renders and ensure the SDK always has a consistent reference
to your handlers.
The specific callbacks available for each feature — connection, streams, recording, moderation,
and so on — are documented on the relevant topic pages. The pattern above applies universally:
all callbacks are delivered through the single eventHandlers prop.
The SDK does not throw exceptions for session-level errors. Instead, it signals failures through dedicated error callbacks. When something goes wrong — connection is refused, an operation is not permitted for your role, or a network issue occurs — the SDK calls the relevant error callback and passes a structured error payload.
The two most common error callbacks to implement are roomError, which fires for
room-level failures, and eventError, which fires for failures on specific operations
like recording or moderation. Both follow the same payload structure.
The error payload always includes:
-
result— A numeric error code. A non-zero value indicates failure;0means the operation succeeded. -
msg— A human-readable string describing what went wrong.
A minimal error handler looks like this:
const eventHandlers = {
roomError: (error) => {
console.error('Room error:', error.msg, '| Code:', error.result);
}
};
roomError in your eventHandlers. Without it, silent
failures during connection or session setup will be invisible to your app and extremely difficult to debug.
Individual topic pages document additional error callbacks specific to each feature area, such as recording errors, floor access errors, and stream errors.
The React Native SDK documentation is organized into the following topics: