SuperAPI AI 工具集

cometchat-ios-calls

编程与开发

查看项目

更新于 10-21 20:28

技能介绍

用途

本技能用于在 iOS 版 CometChat 应用中添加语音和视频通话功能,包括通话按钮、来电/通话中界面、通话记录以及 CallKit 响铃。触发场景如“添加视频通话”“显示来电界面”“添加通话历史”。

它是 cometchat-ios-core 的配套技能:core 负责初始化和聊天界面,本技能在其基础上增加通话能力。

前置依赖

core 技能已经以 5.0.3 版本链接了 CometChatCallsSDK。在 5.1.22(自 5.1.19 起)中,套件的接口会导入它,因此即使是纯聊天构建也需要它。不要重复添加,也不要使用不同版本。

Calls 有独立的登录

UI Kit 的登录不足以认证 Calls SDK。仅使用 CometChatUIKit.login(uid:) 时,CometChatCallLogs 会显示“Oops! Looks like something went wrong”,其请求携带空的 authToken(在 5.1.19/5.0.3 上实测),且没有错误指向原因。在 UI Kit 登录成功后,需要执行 Calls 的初始化与登录。

默认方式使用 CometChatCalls.initFromSettings,它不接收 settings 参数,而是读取 core 技能已打包的同一个 cometchat-settings.json(Copy Bundle Resources),不要构建第二个 settings 对象。初始化成功后,用 CometChat.getUserAuthToken() 获取 token 并调用 CometChatCalls.login(authToken:onSuccess:onError:)。

注意:应通过 CometChatCalls.initFromSettings 初始化,而不是经典的 CometChatCalls(callsAppSettings: CallAppSettingsBuilder()…) 构建器,后者会将应用归属为“manual”并丢失 ai-agent 遥测。构建器初始化仅作为回退,用于未打包 cometchat-settings.json 的应用。不要同时使用两者——在 initFromSettings 之后再做构建器初始化会重新归属为“manual”。若文件不在 Copy Bundle Resources 中,initFromSettings 会以 SETTINGS_FILE_NOT_FOUND 失败;core 技能已为聊天添加该文件,因此先发布聊天的 UI-Kit 应用已满足此条件。

文档的通话集成页面称链接 SDK 即可,但实际并非如此。纯聊天应用可跳过这些(它们链接 Calls SDK 仅为了满足 5.1.19 的导入)。

五个组件

  • CometChatCallButtons:语音/视频触发按钮。没有无参初始化,需用 CometChatCallButtons(width:height:) 构造,配合 set(user:) 或 set(group:),以及 set(controller:)。应放在消息头部的槽位中。
  • CometChatIncomingCall:响铃界面。使用 set(call:)、set(onAcceptClick:)、set(onCancelClick:),拒绝使用 onCancelClick,没有 onDeclineClick。
  • CometChatOngoingCall:通话中界面。使用 set(sessionId:)(小写 d),set(sessionID:) 无法编译。还有 set(callSettingsBuilder:)、set(callWorkFlow:)。
  • CometChatOutgoingCall:主叫方在对方未接听时的响铃界面。使用 set(call:)、set(onCancelClick:)。
  • CometChatCallLogs:通话历史。

CometChatCallLogs 的回调是 Any 类型,使用前需转换。与其他列表组件不同,它的五个 setter 返回未类型化的值:set(onItemClick:) → (_ callLog: Any)、set(onCallButtonClicked:) → (Any)、set(options:) → (_ callLog: Any)、set(onLoad:) → ([Any])、set(onError:) → (_ error: Any),而非其他地方的 CometChatException。

在 onItemClick 中应转换为 CallLog(而非 Call,后者在运行时转换失败并导致点击静默无效)。CallLog 暴露 status、type、mode、initiator、receiver,而非 Call 的拼写(callStatus/callType/callInitiator/callReceiver)。CallLog 是 Calls-SDK 类型。onError 中的值是 Calls SDK 的异常类型,转换为聊天 SDK 的 CometChatException 会失败,应转换为 CometChatCallException。

sessionID 与 sessionId 是同一概念的不同拼写:SDK 的 Call 暴露 sessionID(大写),而套件的 CometChatOngoingCall 接收 set(sessionId:)(小写)。在同一函数中读取日志并开始通话需要同时使用两种拼写。

CometChatCallButtons 的语音/视频点击处理器是属性:callButtons.onVoiceCallClick = { user, group in … },onVideoCallClick 同理。并且是 set(callSettingsBuilder:)(复数 Settings)。

如果在工厂中构造这些组件,需要 @MainActor。在 UIViewController 内无需额外处理(已是主 actor)。但若包装在独立的工厂/枚举/静态方法中,需标记该上下文为 @MainActor,因为组件的 setter 是主 actor 隔离的。CometChatOutgoingCall 最严格:与 CometChatIncomingCall/CometChatCallButtons 不同,它没有 @preconcurrency,因此在 Swift 5 下从非隔离上下文调用其 set(call:)/set(onCancelClick:) 是硬错误,而非警告。

最小接线示例

在 @MainActor 上下文(如 UIViewController)中:

let callButtons = CometChatCallButtons(width: 180, height: 40) callButtons.set(user: user) // 或 .set(group:) 用于群组通话 callButtons.set(controller: self) callButtons.onVoiceCallClick = { user, group in /* 发起语音通话 / } callButtons.onVideoCallClick = { user, group in / 发起视频通话 */ }

// 通过全局应用级监听器在任何界面上呈现来电 let incoming = CometChatIncomingCall() incoming.set(call: incomingCall) // accept/cancel 闭包是两个参数:(call: Call?, controller: UIViewController?)。单参数闭包无法编译。 incoming.set(onAcceptClick: { call, _ in /* 推入 CometChatOngoingCall */ }) incoming.set(onCancelClick: { call, _ in self.dismiss(animated: true) })

let outgoing = CometChatOutgoingCall() outgoing.set(call: pendingCall) outgoing.set(onCancelClick: { call, _ in self.dismiss(animated: true) })

let ongoing = CometChatOngoingCall() // Call.sessionID(大写 D,SDK)是可选的 String?;set(sessionId:)(小写 d,套件)需要非可选 String,因此需 guard。 if let sid = pendingCall.sessionID { ongoing.set(sessionId: sid) }

let logs = CometChatCallLogs() // 注意:CometChatCallLogs 没有 set(controller:),像普通 UIViewController 一样呈现/推入。 logs.set(onItemClick: { callLog in guard let log = callLog as? CallLog else { return } /* … */ })

来电是应用级的

通话可能在任何界面到达,因此应在应用级监听(CometChatCallEventListener / CometChatCallEvents),并在当前显示的界面上呈现 CometChatIncomingCall。若只在某个聊天界面内接线,其他界面会漏接来电。

权限与后台

Info.plist 中需要相机和麦克风的使用说明,否则首次通话会崩溃而非优雅失败。后台响铃由 CometChatPushNotifications SDK 处理,它为你管理 CallKit + PushKit。不要手写 PKPushRegistryDelegate / CXProviderDelegate,也不要调用 UIKitSettings.set(voipToken:)(该 setter 是当前文档不再使用的旧路径)。完整的 VoIP 接线见 cometchat-ios-v5-sdk 的“VoIP call notifications”和 cometchat-ios-push;需要在 Dashboard 中配置 APNs VoIP 提供商并使用真机。

注意事项

  • 模拟器限制:无摄像头;WebRTC 表面行为可能与真机不同。请在真机上验证通话。
  • 每个通话界面都需要退出路径:接听、拒绝和挂断都必须有去处。
  • 版本锁定:套件 5.1.22 / SDK 4.1.7 / Calls 5.0.3 是精确版本;混用版本会导致构建失败或运行时崩溃。

验证

在真机上:通话按钮出现在头部,点击后对方响铃,来电界面显示在当前界面之上,接听后有音视频连接,挂断释放摄像头和麦克风,通话出现在通话记录中。