React Native 快速开始与功能指南

React Native：前置条件、安装、Token、加入频道、发布订阅、事件、错误处理与排障；接口名与签名在构建时取自公开 SDK 接口定义。

接口小节由公开 SDK 接口定义生成

版本 v1.1.0 · 更新于 2026-10-26 · 修订 1

React Native 端是 RtcEngine + IRtcEngineEventHandler 形状，通过原生桥接（Android 走 Kotlin/Java，iOS 走 Objective-C）暴露给 JS。

前置条件

React Native 0.74+、Node.js ≥ 22、Xcode 16+ / Android SDK 35。
Android 需要 CAMERA、RECORD_AUDIO 运行时权限；iOS 需要 NSCameraUsageDescription / NSMicrophoneUsageDescription。
已拿到 appId 与 Token 服务（见控制台开通服务与获取凭证）。

安装

bash

# 包名以发布版本为准
npm install react-native-nimeet-rtc
cd ios && pod install

Expo 项目需要 prebuild（npx expo prebuild）后才能接入原生模块。

获取 Token

Token 由你的后端签发（POST /v1/tokens），RN 侧只保存 { appId, rtcToken, rtcUid }；不要把 customerSecret 打进 JS bundle。

typescript

const { appId, rtcToken, rtcUid } = await fetch('/api/rtc-token?channel=weekly-sync&uid=10001').then(r => r.json());

加入频道

typescript

import {
  createAgoraRtcEngine,
  ChannelProfileType,
  ClientRoleType,
  IRtcEngineEventHandler,
} from 'react-native-nimeet-rtc';

const engine = createAgoraRtcEngine();

const handler: IRtcEngineEventHandler = {
  onJoinChannelSuccess: (connection, elapsed) => console.log('joined', connection.channelId),
  onUserJoined: (connection, remoteUid, elapsed) => console.log('remote joined', remoteUid),
  onUserOffline: (connection, remoteUid, reason) => console.log('remote left', remoteUid),
  onTokenPrivilegeWillExpire: () => refreshToken(),
  onError: (err) => console.warn('rtc error', err),
};

engine.initialize({ appId, logConfig: { level: 1 } });
engine.registerEventHandler(handler);
engine.setChannelProfile(ChannelProfileType.ChannelProfileLiveBroadcasting);
engine.enableVideo();
engine.startPreview();

engine.joinChannel(rtcToken, 'weekly-sync', rtcUid, {
  clientRoleType: ClientRoleType.ClientRoleBroadcaster,
});

发布与订阅

typescript

engine.muteLocalAudioStream(true);
engine.muteLocalVideoStream(true);
engine.enableLocalVideo(false);
engine.updateChannelMediaOptions({ clientRoleType: ClientRoleType.ClientRoleAudience });

屏幕共享依赖原生能力：Android 用 MediaProjection（前台服务），iOS 用 Broadcast Upload Extension；方法名见同端 API 参考（startScreenCapture、getScreenCaptureSources 等）。

事件

IRtcEngineEventHandler 是普通对象，把需要的方法填进去即可。常用：onJoinChannelSuccess、onUserJoined、 onUserOffline、onFirstRemoteVideoDecoded、onTokenPrivilegeWillExpire、onError、onConnectionStateChanged。

错误处理

同步方法返回数字错误码，0 成功，负值为声网错误号；
异步错误走 onError；
未实现能力返回 -4（ERR_NOT_SUPPORTED）。

排障

现象	原因	处理
`TurboModule` 报错	新架构未适配版本	确认 RN 版本与包支持矩阵
iOS 构建失败	Pod 未安装	`cd ios && pod install`
安卓黑屏	缺运行时权限	请求 `CAMERA` / `RECORD_AUDIO`
热重载后收不到事件	handler 未重新注册	在组件挂载时注册、卸载时 `unregisterEventHandler`
Expo Go 崩溃	Expo Go 不含原生模块	用 dev client / prebuild

下一步

完整接口与重载：同端 API 参考
错误码与排障：错误码全表、FAQ
服务端签发 Token：Token 鉴权

平台信息

项	值
平台	React Native
语言	TypeScript / Java / Objective-C
SDK 包	`react-native-nimeet-rtc`
接口版本	`4.6.4`
兼容参考	声网 rn 端 API

本端公开接口与声网 rn 端 API 对齐；安装与运行要求见上面前置条件。

可用性

该端 SDK：正式可用。本页代码片段使用公开 API；运行时的能力边界以实际发布的 SDK 包为准。

加入频道链路

下列方法名、参数类型与返回值与同端 API 参考一致。一个平台若有多个重载，这里展示最常用的那一个；完整重载见同端 API 参考页。

步骤	接口	方法	重载数
订阅远端媒体	`IBaseSpatialAudioEngine`	`muteRemoteAudioStream`	1
创建实例 / 初始化	`ILocalSpatialAudioEngine`	`initialize`	1
续期 Token	`IMusicContentCenter`	`renewToken`	1
开启视频与本地预览	`IRtcEngine`	`enableVideo`	1
加入频道	`IRtcEngine`	`joinChannel`	1
离开频道	`IRtcEngine`	`leaveChannel`	1
频道场景	`IRtcEngine`	`setChannelProfile`	1
切换角色	`IRtcEngine`	`setClientRole`	1

typescript

muteRemoteAudioStream(uid: number, mute: boolean): number
initialize(): number
renewToken(token: string): number
enableVideo(): number
joinChannel(token: string, channelId: string, uid: number, options: ChannelMediaOptions): number
leaveChannel(options?: LeaveChannelOptions): number
setChannelProfile(profile: ChannelProfileType): number
setClientRole(role: ClientRoleType, options?: ClientRoleOptions): number

事件与回调

回调注册在 IRtcEngineEventHandler 上；不同端的命名可能不同，完整清单见同端 API 参考页。

回调	签名	用途
`onConnectionStateChanged`	`onConnectionStateChanged(connection: RtcConnection, state: ConnectionStateType, reason: ConnectionChangedReasonType): void`	入会结果 / 连接状态变化：据此更新 UI 并决定是否重连。
`onUserJoined`	`onUserJoined(connection: RtcConnection, remoteUid: number, elapsed: number): void`	远端用户加入：分配画面容器。
`onFirstRemoteVideoDecoded`	`onFirstRemoteVideoDecoded(connection: RtcConnection, remoteUid: number, width: number, height: number, elapsed: number): void`	远端视频状态：首帧解码后即可渲染。
`onUserOffline`	`onUserOffline(connection: RtcConnection, remoteUid: number, reason: UserOfflineReasonType): void`	远端用户离开：释放容器与订阅。
`onRequestToken`	`onRequestToken(connection: RtcConnection): void`	Token 即将过期：调用服务端续期后 `renewToken`。
`onError`	`onError(err: ErrorCodeType, msg: string): void`	运行时错误：`err` 为声网错误号，按错误码表分流。
`onNetworkQuality`	`onNetworkQuality(connection: RtcConnection, remoteUid: number, txQuality: QualityType, rxQuality: QualityType): void`	网络质量：上报到水晶球或提示用户。

错误码

常量	值
`ErrAborted`	`20`
`ErrAdmGeneralError`	`1005`
`ErrAdmInitPlayout`	`1008`
`ErrAdmInitRecording`	`1011`
`ErrAdmStartPlayout`	`1009`
`ErrAdmStartRecording`	`1012`
`ErrAdmStopPlayout`	`1010`
`ErrAdmStopRecording`	`1013`
`ErrAlreadyInUse`	`19`
`ErrBitrateLimit`	`115`
`ErrBufferTooSmall`	`6`
`ErrCertRaw`	`1001`
`ErrClientIsBannedByServer`	`123`
`ErrConnectionInterrupted`	`111`
`ErrConnectionLost`	`112`
`ErrDatastreamDecryptionFailed`	`122`
`ErrDecryptionFailed`	`120`
`ErrEncryptedStreamNotAllowedPublish`	`130`
`ErrFailed`	`1`
`ErrInitNetEngine`	`21`
`ErrInvalidAppId`	`101`
`ErrInvalidArgument`	`2`
`ErrInvalidChannelName`	`102`
`ErrInvalidState`	`8`
`ErrInvalidToken`	`null`
`ErrInvalidUserAccount`	`134`
`ErrInvalidUserId`	`121`
`ErrJoinChannelRejected`	`17`
`ErrLeaveChannelRejected`	`18`
`ErrNoPermission`	`9`
`ErrNoServerResources`	`103`
`ErrNotInChannel`	`113`
`ErrNotInitialized`	`7`
`ErrNotReady`	`3`
`ErrNotSupported`	`4`
`ErrOk`	`0`
`ErrPcmsendBufferoverflow`	`201`
`ErrPcmsendFormat`	`200`
`ErrRefused`	`5`
`ErrResourceLimited`	`22`
`ErrSetClientRoleNotAuthorized`	`119`
`ErrSizeTooLarge`	`114`
`ErrStreamMessageTimeout`	`117`
`ErrTimedout`	`10`
`ErrTokenExpired`	`109`
`ErrTooManyDataStreams`	`116`
`ErrVdmCameraNotAuthorized`	`1501`
`IRtcEngine`	`null`

平台 REST 层用 REST 错误码；SDK 层把连接/鉴权失败映射成声网错误号，映射表见各端 SDK 错误标识。

React Native 快速开始与功能指南

前置条件#

安装#

获取 Token#

加入频道#

发布与订阅#

事件#

错误处理#

排障#

下一步#

平台信息

可用性

加入频道链路

事件与回调

错误码

前置条件

安装

获取 Token

加入频道

发布与订阅

事件

错误处理

排障

下一步