SuperAPI AI 工具集

cometchat-js-v5-sdk

编程与开发

查看项目

更新于 10-21 20:29

技能介绍

用途

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 }) 仅作回退。

两种构建模式:

  1. 会议式(会话房间)——仅用 Calls SDK。所有加入同一 sessionId 的人进入同一通话:generateToken(sessionId) → joinSession(token, sessionSettings, containerEl),无响铃。
  2. 一对一响铃——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 无需后端即可验证接线);实际通话渲染在浏览器测试环境中验证。