用途
CometChat Calls SDK v5(产品名 CometChatCallsSDK)用于在 iOS 应用中从零添加语音与视频通话能力。它是无界面(headless)SDK,不包含预置 UI Kit,适合需要自行构建通话界面的开发者。
主要能力
- 生命周期管理:初始化、登录(UID+authKey / UID+apiKey / authToken)、登出、获取当前登录用户。
- 会话管理:生成令牌、加入会话、构建会话设置(SessionSettingsBuilder)。
- 会话内控制(作用于 CallSession.shared,仅用于自定义控件):离开会话、静音/取消静音、暂停/恢复视频、设置布局、设置音频模式、切换摄像头、举手/放下手、开始/停止录制、开始/停止转录、开始/停止推流、固定/取消固定参与者、静音参与者、暂停参与者视频、启用/禁用画中画布局、判断会话是否活跃。
- 事件监听器:SessionStatusListener、MediaEventsListener、ParticipantEventListener、LayoutListener、ButtonClickListener,以及 clearAllListeners。
- 通话记录:CallLogsBuilder → CallLogsRequest → CallLog 及相关类型。
- 枚举:AudioMode、SessionType、LayoutType、CameraFacing。
使用方式
安装
仅支持 Swift Package Manager,不使用 CocoaPods。在 Xcode 中通过 File → Add Package Dependencies 添加:
https://github.com/cometchat/calls-sdk-ios
该包只提供一个产品 CometChatCallsSDK,已内置 WebRTC,无需单独添加。
1:1 响铃模式还需第二个 SPM 包(用于信令):
https://github.com/cometchat/chat-sdk-ios
产品为 CometChatSDK(已验证 4.1.7)。仅会议式房间不需要它。
权限配置
Info.plist 必须包含 NSCameraUsageDescription 与 NSMicrophoneUsageDescription,否则首次权限弹窗时通话会失败。若需后台通话,添加 Background Modes → Audio, AirPlay and Picture in Picture(使用 VoIP 推送时再加 Voice over IP)。
凭据
需要 App ID、Region、Auth Key(仅开发用)。生产环境应在服务端签发 auth token,切勿将 Auth Key 打包进应用。
初始化与登录顺序
初始化(一次,必须成功)→ CometChatCalls.login(...) → 之后才能 generateToken / joinSession / 注册监听器。
默认使用 CometChatCalls.initFromSettings(onSuccess:onError:),它从 Bundle.main 读取 cometchat-settings.json(根级 appId + region;可选 callsSDK → host/adminHost/clientHost/callsHost)。该文件必须加入目标的 Copy Bundle Resources,否则初始化报 SETTINGS_FILE_NOT_FOUND。
备选(公开文档路径):CallAppSettingsBuilder().set(appID:).set(region:).build() → CometChatCalls(callsAppSettings:onSuccess:onError:)。注意使用 set(appID:)/set(region:),文档中的 setAppId/setRegion/setHost 在 5.0.4 已弃用。两者不可同时使用。
加入会话
两条路径任选其一:generateToken(sessionID:) → joinSession(callToken:callSetting:container:),或直接 joinSession(sessionID:callSetting:container:)。container 必须是具有真实尺寸的 UIView,零尺寸视图不可见;SwiftUI 中需用 UIViewRepresentable 包装。
监听器
在加入前于 CallSession.shared 上注册,销毁时移除(或调用 clearAllListeners()),并在界面消失时调用 leaveSession()。所有监听器协议均为 @objc 且成员全部可选,实现类型必须是继承 NSObject 的类。
1:1 响铃与 VoIP 推送
后台或已终止状态下的响铃由独立包 CometChatPushNotifications 1.0.0 负责:
https://github.com/cometchat/push-notifications-sdk-ios @ 1.0.0
产品为 CometChatPushNotificationsSwift。该包虽未声明依赖,但二进制引用了 CometChatSDK 与 CometChatCallsSDK,因此应用必须同时安装上述两个包。导入时使用 import CometChatPushNotificationsSwift。
集成三步:在 CometChat.init 之后调用 CometChatPushNotifications.shared.initialize(config: .init(providerId:)) 并设置 delegate;在 AppDelegate 中转发 registerDeviceToken(:)(及 handleRegistrationFailure(:));实现 CometChatPushNotificationsDelegate(方法均可选,关键是 presentCallScreen(for:sessionId:) 与 onCallCleanupComplete())。不要自行实现 PKPushRegistryDelegate 或 CXProviderDelegate。冷启动时应在登录成功后调用 notifyCallsSDKReady(),而非初始化成功后。presentCallScreen 触发时通话已被接受,只需展示界面并加入。
前置条件:仪表盘中的 APNs VoIP provider、Push Notifications 与 Background Modes(Voice over IP、Remote notifications)能力,以及真机(VoIP 推送不会送达模拟器)。
适用场景
- 需要从零构建自定义通话界面的 iOS 应用。
- 会议式房间通话(所有参与者加入同一 session id)。
- 1:1 响铃通话(需额外引入 Chat SDK 做信令)。
- 需要后台/关闭状态下响铃的场景(需 CometChatPushNotifications)。
限制与注意事项
- 仅支持 Swift Package Manager。
- 加入后的会话已渲染完整通话 UI(静音、摄像头、布局、参与者、举手、离开),不要重复添加内置控件;CallSession.shared 的动作仅用于自定义控件。
- 文档中存在多处不可编译的符号(如 AudioModeType、CometChat.CallStatus、.setType、.BACK 等),应使用 AudioMode、CometChat.callStatus、.setSessionType、.REAR 等正确写法。
- Participant 恰好 12 个字段且全部可选,身份标识为 uid;文档中的 pid、isPinned、isAudioMuted、isVideoPaused、isPresenting、raisedHandTimestamp 均不存在。
- CallSession.shared.setAudioMode / setLayout 接收 String(如 "SPEAKER"、"TILE"),而 builder 形式接收枚举。
- 1:1 响铃的销毁需同时调用 CallSession.shared.leaveSession() 与 CometChat.endCall(sessionID:)。
- 具体签名、字段与事件名应以官方文档为准,本介绍未逐一列出。