SuperAPI AI 工具集

cometchat-react-v7-calls

编程与开发

查看项目

更新于 10-21 20:30

技能介绍

用途

本技能用于在已经完成 CometChat 聊天集成的 React 应用中,添加语音与视频通话功能。它假设聊天核心(安装、凭据、init→login→render、CometChatProvider)已经就绪,通话能力复用同一套初始化与登录流程。

主要能力

  • 在 React 应用中启用 1:1 语音与视频通话。
  • 通过消息头部自动呈现通话按钮。
  • 在应用根部挂载来电振铃界面。
  • 提供可选的通话记录(历史)界面。
  • 说明群组通话的加入机制(发送会议消息,成员加入,而非整组振铃)。

依赖与安装

通话 UI 内置于 @cometchat/chat-uikit-react@7,没有单独的 calls-UI 包。WebRTC 引擎是独立且未被打包的依赖:

  • @cometchat/chat-uikit-react@^7
  • @cometchat/chat-sdk-javascript@^4.1.9
  • @cometchat/calls-sdk-javascript@^5(主版本 5,区别于聊天 SDK 的 v4)

安装命令:

npm install @cometchat/calls-sdk-javascript@5

Calls SDK 不会被 UI Kit 打包;若未安装,所有通话入口都会保持隐藏。不要将 @cometchat/chat-sdk-javascript 升级到不存在的 v7,它保持 ^4.1.9。

启用通话(两部分契约)

通话默认关闭,必须同时满足两个条件才会开启:Calls SDK 已安装,且在初始化设置中开启通话。核心通过 CometChatUIKit.initFromSettings 初始化时,需在同一个 settings 对象中提供真值的 uiKit.callsSDK:

import { CometChatUIKit } from "@cometchat/chat-uikit-react";

await CometChatUIKit.initFromSettings({ appId: APP_ID, region: REGION, credentials: { authKey: AUTH_KEY }, // dev-only; prod → server-minted auth token chatSDK: { presenceSubscription: { type: "ALL_USERS" } }, uiKit: { callsSDK: {} }, // ← turns calling ON (the initFromSettings equivalent of setCallingEnabled(true)) });

Kit 会计算 callingEnabled = !!settings.uiKit.callsSDK,因此真值的 uiKit.callsSDK 等价于 UIKitSettingsBuilder().setCallingEnabled(true)。没有它,通话按钮和来电界面都不会渲染。经典路径 CometChatUIKit.init(new UIKitSettingsBuilder()…setCallingEnabled(true).build()) 仍然可用,但会跳过 ai-agent 遥测归因,因此推荐 initFromSettings。默认路径不需要单独的 CometChatUIKitCalls.init();initFromSettings 会在内部路由 Calls SDK,不要调用原始 CometChat.init()。

使用方式(最少代码路径)

两步即可覆盖端到端振铃:

  1. 在应用根部(路由之上)挂载一次 CometChatIncomingCall。它自行管理可见性——空闲时不渲染,来电时振铃——无需条件包裹,并自行附加 SDK 监听器。

import { CometChatIncomingCall } from "@cometchat/chat-uikit-react"; // at the app shell, inside CometChatProvider, above the router: <CometChatIncomingCall />

  1. 让 CometChatMessageHeader 呈现通话按钮。选中用户或群组后,启用通话时头部会自行组合语音/视频通话按钮,通常无需额外挂载。只有在没有 CometChatMessageHeader 的自定义头部上,才单独放置 CometChatCallButtons user={user}(1:1)或 group={group}。切勿同时挂载两者,否则按钮会重复。

通话记录(可选)

CometChatCallLogs 可放在侧边栏或 /calls 路由(onItemClick、onCallButtonClicked、callLogRequestBuilder)。它不会在新通话时自动刷新,需重新挂载。当通话记录不可用时,它会显示 Kit 的 "OOPS! …" 界面,且该界面来自其内部错误状态、不抛出异常,因此宿主 CometChatErrorBoundary/fallbackView 无法覆盖,onError 也可能不触发。启用通话并不足以让 CometChatCallLogs 可用:通话记录可用性是独立的套餐/能力门槛。可靠做法是仅在真实通话记录可用时(一次性 SDK 探测)才显示 Calls 标签页,默认关闭该标签页。

导入注意:CallLogRequestBuilder 不是 @cometchat/calls-sdk-javascript 的具名导出,而是默认导出类 CometChatCalls 的静态成员:

import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; new CometChatCalls.CallLogRequestBuilder()…

而 import { CallLogRequestBuilder } from "@cometchat/calls-sdk-javascript" 会失败(TS2614)。generateToken 位于 CometChatUIKitCalls(来自 @cometchat/chat-uikit-react)。

1:1 振铃与群组加入

  • 1:1:通话按钮触发 Kit 发起通话,接收方根部的 CometChatIncomingCall 振铃,接听后进入进行中通话界面。Kit 会自动驱动 outgoing → ongoing。
  • 群组:群组上的通话按钮会向聊天发送群组通话会议消息,成员从该消息加入。没有“整组振铃”原语,应呈现加入入口,不要等待振铃。

自定义通话界面

超出默认振铃/加入范围的功能——自定义进行中通话界面(CometChatOngoingCall)、自定义通话管理器(CometChatOutgoingCall)、空闲超时调优、屏幕共享、画中画、设备选择、录制、虚拟背景——需从文档 .md 孪生文件获取确切 props/API(通过 cometchat-react-v7-core/references/docs-map.md)。这些 props 会变化,不要凭记忆或读取 .d.ts 生成。

常见陷阱

  • 空闲超时以毫秒为单位。180 = 180 毫秒,会立即触发并退出“你还在吗?”提示。3 分钟应使用 180_000。
  • 零尺寸通话界面会崩溃或空白。自定义进行中通话容器若宽高为 0 会抛出异常或不渲染(例如在自动高度 flex 父级上使用 h-full)。应给通话界面内容无关的宽高,采用无重排界面标准:固定 flex 链加 min-height:0,或 100dvw/100dvh 覆盖层。
  • 离开时容器尺寸和瓦片数必须为正(非致命)。即使是 Kit 默认进行中通话对话框,在“Leave session”卸载时收缩到 0×0,也会由 Jitsi ResizeObserver 记录此错误。这是 Calls-SDK 拆卸竞态,非致命,应用会恢复到聊天界面,但每次挂断都会产生未捕获的控制台错误,严格的“无控制台错误”门禁需允许/过滤它。
  • 需要 HTTPS。getUserMedia(摄像头/麦克风)仅在 localhost 或 HTTPS 下工作,纯 HTTP 非 localhost 源上通话会静默无效。
  • Next.js SSR。将 CometChat(尤其是 calls SDK)仅客户端渲染:"use client" + dynamic(() => import(...), { ssr: false })。若构建失败并报 Can't resolve 'fs' / 'path',添加 webpack fallback(config.resolve.fallback = { fs: false, path: false }),这是 Calls-SDK-v5 打包怪癖。
  • 自定义界面清理。在手写进行中通话界面上,挂断/卸载时结束会话并停止轨道(stream.getTracks().forEach(t => t.stop())),否则摄像头灯会保持亮起。Kit 驱动的 CometChatIncomingCall/ongoing 流程会代为处理,优先使用。
  • 屏幕共享/画中画/设备选择/录制/虚拟背景默认不开启,各自需在对应 Calls-SDK 页面单独接线。不要声称默认包含它们。

验证方法

通话已启用(SDK 已安装 + initFromSettings 上 uiKit:{callsSDK:{}});从头部按钮发起 1:1 通话会让对方根部的 CometChatIncomingCall 振铃;接听后在非折叠界面连接音频+视频;群组通话发布加入消息(不振铃);挂断释放摄像头/麦克风(灯灭)。若通话按钮始终不出现:SDK 未安装或通话未启用。若通话界面空白:容器零尺寸或源不是 HTTPS。

限制

本技能假设聊天核心已完成。通话记录可用性受独立套餐/能力门槛限制,启用通话并不保证其可用。自定义通话界面的确切 props 需查阅文档,本技能不提供。屏幕共享、画中画、设备选择、录制、虚拟背景等默认不包含。