用途
CometChat Calls SDK v5 是一个 headless(无预置 UI Kit)的语音与视频通话 SDK,包名为 @cometchat/calls-sdk-javascript@5。它用于从零为任意 Web 应用添加通话能力,适合需要自建通话界面、独立语音/视频通话、按会话 ID 加入会议室,以及一对一响铃通话的场景。若需要预置的即插即用通话 UI,应改用 cometchat-react-v7-calls。
主要能力
SDK 提供以下方法(来自封闭符号目录 web-calls-v5.json,共 83 个符号):
- 生命周期:
CometChatCalls.init、CometChatCalls.initFromSettings、CometChatCalls.login、CometChatCalls.loginWithAuthToken、CometChatCalls.logout、CometChatCalls.getLoggedInUser、CometChatCalls.isUserLoggedIn - 会话:
CometChatCalls.generateToken、CometChatCalls.joinSession、CometChatCalls.leaveSession(startSession已废弃) - 事件:
CometChatCalls.addEventListener(eventName, cb, { signal? })返回unsubscribe() - 通话内操作(仅用于自定义控件):muteAudio/unmuteAudio/toggleAudio、pauseVideo/resumeVideo/toggleVideo、setLayout、startRecording/stopRecording、startScreenSharing/stopScreenSharing、raiseHand/lowerHand、switchCamera、pinParticipant/unpinParticipant、showParticipantList/hideParticipantList
- 设备:getAudioInputDevices、getAudioOutputDevices、getVideoInputDevices、getCurrent*Device
- 通话记录:
CometChatCalls.CallLogRequestBuilder→fetchNext()(分页) - 常量:
CometChatCalls.constants.LAYOUT(TILE/SIDEBAR/SPOTLIGHT)、.TYPE(VOICE/VIDEO)、.CAMERA_FACING
目录中还包含 toggleHand/toggleParticipantList/endSessionForAll/muteParticipant/pauseParticipantVideo/setChatButtonUnreadCount/switchToVideoCall、设备设置方法、虚拟背景方法、startStreaming/stopStreaming(RTMP 直播,配合 SessionSettings 中的 streamUrl/streamKey/hideStreamingButton)、startTranscription/stopTranscription(v5.0.5)以及 TranscriptRequestBuilder 等。
使用方式
安装:
npm install @cometchat/calls-sdk-javascript@5
一对一响铃额外需要 Chat SDK 做信令:
npm install @cometchat/chat-sdk-javascript@4
凭据与环境:App ID、Region、Auth Key(仅开发用)。生产环境应在服务端生成 auth token,切勿泄露 Auth Key。摄像头/麦克风(getUserMedia)需要 HTTPS 或 localhost。
初始化与登录顺序(固定不变):CometChatCalls.init(...)(一次,先 resolve)→ CometChatCalls.login(uid, authKey) 或 loginWithAuthToken(token) → 然后才能 generateToken / joinSession / 注册监听器。
默认使用 CometChatCalls.initFromSettings(settings)(ai-agent 遥测路径,持久化 integrationSource="ai-agent"),该路径有意未公开文档,settings 对象形状内联传入。公开文档的 CometChatCalls.init({ appId, region }) 仅作回退。
两种构建模式:
- 会议式(会话房间)——仅用 Calls SDK。所有加入同一 sessionId 的人进入同一通话:
generateToken(sessionId)→joinSession(token, sessionSettings, containerEl),无响铃。 - 一对一响铃——Chat SDK 做信令,Calls SDK 承载媒体:
CometChat.initiateCall→ 对端CallListener.onIncomingCallReceived→ acceptCall/rejectCall →CometChatCalls.generateToken(call.getSessionId())→joinSession(...)。
最简示例(会议式,框架无关):
import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
import type { SessionSettings } from "@cometchat/calls-sdk-javascript";
await CometChatCalls.initFromSettings({ appId, region: region as "us"|"eu"|"in", credentials: { authKey: AUTH_KEY }, callsSDK: {}, chatSDK: {}, uiKit: {} })
await CometChatCalls.login(uid, AUTH_KEY)
const { token } = await CometChatCalls.generateToken(sessionId)
const unsub = CometChatCalls.addEventListener("onSessionLeft", () => cleanup())
const callSettings: SessionSettings = { sessionType: "VIDEO", layout: "TILE" }
await CometChatCalls.joinSession(token, callSettings, containerEl)
// 清理:unsub(); CometChatCalls.leaveSession()
监听器生命周期:addEventListener 返回 unsubscribe 函数,需全部收集并在卸载时调用,同时调用 CometChatCalls.leaveSession()。监听器应在 joinSession 之前注册。也可通过 { signal } 选项传入 AbortSignal 批量清理。
框架说明:上述配方框架无关,唯一因框架而异的是注册监听器、挂载容器和清理的位置。已在 React 和 Angular 上验证。React 中在 useEffect 内注册监听器并 joinSession,在 effect cleanup 中清理。Angular 中需注意 NgZone/变更检测问题:SDK 回调在 Angular zone 外触发,需通过 BehaviorSubject + async pipe 或 this.zone.run() / ChangeDetectorRef.detectChanges() 驱动模板。
适用场景
- 从零添加通话、不使用 UI Kit
- 独立语音/视频通话
- 自建通话界面
- headless 通话 SDK
- 按会话 ID 加入会议室
- 一对一响铃通话
限制与注意事项
- 不要重复内置通话控件:joinSession 会渲染完整通话 UI(静音、摄像头开关、屏幕共享、举手、参与者列表、布局切换、离开按钮)。muteAudio/pauseVideo/leaveSession 等方法仅用于自定义控件,仅在用户明确要求替换默认控件时使用(可先通过 SessionSettings 的 hideControlPanel 或 hideToggleAudioButton/hideRaiseHandButton/hideChatButton 等隐藏内置控件)。
- 容器零尺寸:joinSession 挂载到 containerEl,若高度为 0 则通话不可见,需显式设置尺寸(如 height: 500px / 100dvh)。
- HTTP(非 HTTPS):getUserMedia 需要安全上下文,非 localhost 下摄像头/麦克风会静默失败。
- 在 init+login resolve 前加入:generateToken/joinSession 会 reject,必须先 await init 再 login。
- 监听器泄漏/未调用 leaveSession:每个 unsubscribe 必须在清理时执行,卸载时调用 leaveSession()。
- startSession 已废弃,使用 joinSession;不要传入旧的 CallSettings builder。
- 与 Chat SDK 共存时登录会重置主机:Chat SDK/UI Kit 登录后需重新初始化 Calls SDK。
- 版本冲突:Calls SDK 是主版本 5,与 Chat SDK 的 v4 不同,不要将 Chat SDK 升级到不存在的 v7。
- 不要假设签名:事件名、SessionSettings 字段和操作参数需从文档获取,不可猜测。
- 一对一响铃中,仅将 CometChat.Call 用作类型会触发 TS6133,应导入具体类型
import type { Call } from "@cometchat/chat-sdk-javascript"。 - 严格 TS 拓宽问题:文档中的裸对象形式在严格 TS 下无法编译,需导入
SessionSettings类型并注解,region 收窄为 "us"|"eu"|"in"。
验证
- Tier-1 目录:所有发出的 CometChatCalls.* 符号出现在 web-calls-v5.json 中。
- Tier-2 类型检查:发出的代码对已安装的 @cometchat/calls-sdk-javascript@5 .d.ts 通过类型检查。
- Tier-3b headless 冒烟:node 冒烟脚本运行 init→login→generateToken→(join 接线)→监听器清理。媒体/joinSession 需要真实 WebRTC/DOM 上下文,node 冒烟覆盖 token+监听器往返(--dry 无需后端即可验证接线);实际通话渲染在浏览器测试环境中验证。