用途
本技能用于在 React Native 应用中「从零」接入 CometChat Calls SDK v5(包名 @cometchat/calls-sdk-react-native@5),即无头(headless)路径,不使用预置 UI Kit。适用场景包括:不使用 UI Kit 添加通话、在 React Native 中实现独立语音/视频、自建通话界面、无头 Calls SDK、通过 session id 加入会议房间、一对一响铃通话。若应用同时需要聊天与预置通话 UI,则应改用 cometchat-react-native-core + cometchat-react-native-calls,而非本技能。
主要能力
- 两种构建模式:
- 会议式(session room):仅用 Calls SDK。渲染相同 sessionId 的人进入同一通话,无响铃。
- 1:1 响铃:Chat SDK 负责信令,Calls SDK 承载媒体。
- 生命周期方法:
init、initFromSettings、login、loginWithAuthToken、logout、getLoggedInUser、getUserAuthToken、isUserLoggedIn、addLoginListener/removeLoginListener。 - 会话方法:
generateToken、Component(渲染即加入)、leaveSession、endSessionForAll。 - 事件:
addEventListener(eventName, cb, { signal? })返回 unsubscribe 函数。 - 通话内操作(仅用于自定义控件):静音/取消静音、暂停/恢复视频、切换摄像头、设置布局、录制、推流、转写、举手、固定参与者、静音参与者、暂停参与者视频、参与者列表、聊天按钮未读数等。
- 音频路由(RN 专有):
setAudioMode、AUDIO_MODE。 - 画中画(RN 专有):
enablePictureInPictureLayout/disablePictureInPictureLayout。 - 通话记录:
CometChatCalls.CallLogRequestBuilder,每次fetchNext()都需.setAuthToken(...);转写可选.setHasTranscriptions(true)。 - 转写:
CometChatCalls.Transcription、TranscriptRequestBuilder、Transcript。
使用方式
安装:
npm install @cometchat/calls-sdk-react-native@5
# 6 个必需 peer 依赖,版本由 SDK 固定,不要浮动
npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
react-native-webrtc@124.0.7
1:1 响铃还需 Chat SDK 用于信令:npm install @cometchat/chat-sdk-react-native@4。
iOS:cd ios && pod install && cd ..,并在 ios/<App>/Info.plist 添加 NSCameraUsageDescription 与 NSMicrophoneUsageDescription;Xcode 中开启 Background Modes 的 Audio, AirPlay, and Picture in Picture(响铃还需 Voice over IP)。
Android:在 android/app/src/main/AndroidManifest.xml 添加 INTERNET、CAMERA、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS、ACCESS_NETWORK_STATE、BLUETOOTH(android:maxSdkVersion="30")、BLUETOOTH_CONNECT。API 23+ 还需在开始通话前发起运行时权限请求(PermissionsAndroid.requestMultiple([CAMERA, RECORD_AUDIO]) 或 react-native-permissions)。需在后台存活还需 FOREGROUND_SERVICE* 系列 + WAKE_LOCK + POST_NOTIFICATIONS。
初始化与登录顺序(固定不变):CometChatCalls.initFromSettings(...)(一次,检查结果)→ CometChatCalls.login(uid, authKey) 或 loginWithAuthToken(token) → 之后才 generateToken / 渲染 / 监听。默认使用 initFromSettings(settings),公开文档的 init({ appId, region }) 仅作回退。两个 init 入口都返回结果对象 { success, error },不是 reject 的 Promise,必须判断 .success。v5 自行认证,generateToken(sessionId) 不再接收 auth token。
最小代码(会议式):
import { useEffect, useState } from "react";
import { View } from "react-native";
import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
const res = await CometChatCalls.initFromSettings({
appId: APP_ID, region: REGION, credentials: { authKey: AUTH_KEY },
});
if (!res.success) throw new Error(res.error.message);
await CometChatCalls.login(UID, AUTH_KEY);
function CallScreen({ sessionId }: { sessionId: string }) {
const [callToken, setCallToken] = useState<string | null>(null);
useEffect(() => {
const controller = new AbortController();
const { signal } = controller;
CometChatCalls.addEventListener("onSessionLeft", () => {}, { signal });
CometChatCalls.addEventListener("onParticipantJoined", (p) => {}, { signal });
return () => { controller.abort(); CometChatCalls.leaveSession(); };
}, []);
useEffect(() => {
CometChatCalls.generateToken(sessionId)
.then(({ token }) => setCallToken(token))
.catch((e) => console.error(e.errorCode, e.errorDescription));
}, [sessionId]);
if (!callToken) return null;
return (
<View style={{ flex: 1 }}>
<CometChatCalls.Component
callToken={callToken}
sessionSettings={{ sessionType: "VIDEO", layout: "TILE" }}
/>
</View>
);
}
凭证/环境:App ID、Region、Auth Key(仅开发用)。生产环境应在服务端签发 auth token,切勿下发 Auth Key。安装后需重新原生构建(npx react-native run-ios / run-android),仅 Metro 重载不会加载新原生模块。
框架说明:裸 React Native 直接使用上述配方;Expo 需 prebuild / dev-client,无法在 Expo Go 运行,权限在 app.json 声明;导航上通话页应作为独立路由,离开路由必须 leaveSession()。
适用场景与限制
- 适用:自建通话界面、无头集成、会议式房间、1:1 响铃通话。
- 限制与注意:
CometChatCalls是单例,只有一个活动会话,只能挂载一个 Component;切换通话需先leaveSession()→ 等待onSessionLeft→generateToken(next)→ 重新渲染。不要重复内置通话控件(Component 已渲染完整 UI)。RN 上不存在joinSession,加入即渲染 Component。父容器必须有尺寸(flex: 1或显式高度)。不要向generateToken传 auth token(v4 模式)。Android 23+ 仅有清单权限而无运行时请求会导致通话失败。不要使用已废弃的 v4 兼容接口(CallSettingsBuilder、CallAppSettingsBuilder、OngoingCallListener、startSession、endSession、switchToVideoCall、getCallDetails)。RN 上不存在 joinSession、屏幕共享、虚拟背景、音视频设备枚举等方法。peer 依赖版本必须严格按给定版本安装,不要浮动。
关于具体 sessionSettings 字段、事件名与动作签名,资料要求从官方文档获取,本介绍未逐一列出;资料未提供的收费、价格等信息暂未提供。