本技能面向 Flutter 应用,使用无头(headless)的 CometChat Calls SDK v5(包名 cometchat_calls_sdk,pub.dev 版本 5.0.7)从零添加语音与视频通话,不使用 UI Kit。若需要预置的即插即用通话界面,应改用 cometchat-flutter-v6-calls。
【用途与适用场景】 适用于“从零添加通话 / 不使用 UI Kit”“Flutter 上独立的语音视频”“自建通话界面”“无头通话 SDK”“通过 session id 加入会议房间”“一对一响铃”等需求。前提是调用方已选择从零/独立路径。
【安装与前置条件】 在 pubspec.yaml 中添加依赖:cometchat_calls_sdk: ^5.0.7(已针对 5.0.7 验证),然后执行 flutter pub get。1:1 响铃还需要 Chat SDK(cometchat_sdk v5)用于信令。 权限为必需项:Android 的 AndroidManifest.xml 需声明 INTERNET、CAMERA、RECORD_AUDIO、MODIFY_AUDIO_SETTINGS、ACCESS_NETWORK_STATE;API 23+ 还必须在运行时请求摄像头与麦克风权限,仅声明清单不够。iOS 的 Info.plist 需添加 NSCameraUsageDescription 与 NSMicrophoneUsageDescription。Android minSdkVersion 为 26,iOS 为 platform :ios, '15.1'(文档写 24 与 iOS 12,但会在构建时失败)。 凭据包括 App ID、Region、Auth Key(仅开发用),可通过 CLI 获取:npx @cometchat/skills-cli@3 auth login → provision use --app-id <id> --json。生产环境应在服务端生成 auth token,切勿下发 Auth Key。
【初始化与登录顺序(固定不变)】 初始化(一次,必须成功)→ CometChatCalls.login(...) → 之后才能 generateCallToken / joinSession / 注册监听器。在 init 与 login 完成前不能加入通话,可用 CometChatCalls.isInitialized 作为守卫。默认使用 CometChatCalls.initFromSettings(onSuccess:, onError:),它不带 settings 参数,通过 rootBundle 读取项目根目录的 cometchat-settings.json,因此该文件必须位于项目根目录并注册为 Flutter asset(flutter: assets: - cometchat-settings.json)。根键为 appId 与 region,可选 callsSDK → adminHost/clientHost/callsHost,不含 Auth Key。若遗漏 assets 注册,init 会以 settings-file-not-found 静默失败。备选路径为使用 CallAppSettingBuilder 构建 CallAppSettings 后调用 CometChatCalls.init(s, ...),注意使用 Dart 级联(..appId =)而非 setX() 方法,且 CallAppSettingBuilder 为单数形式。切勿同时使用两种方式,否则会重新归属为 manual 并丢失 ai-agent 遥测。 登录:开发用 CometChatCalls.login(uid:, authKey:, onSuccess:, onError:),生产用 CometChatCalls.loginWithAuthToken(authToken:, onSuccess:, onError:)。可先检查 await CometChatCalls.getLoggedInUser()(返回 Future<User?>),SDK 会保留会话,重复登录是多余操作。两个 onSuccess 回调给出的 User? 可为空,文档中未做空值保护,不要照抄。
【两种构建模式】 会议式(session 房间):仅用 Calls SDK,无需 Chat SDK,加入同一 session id 的人进入同一通话。 1:1 响铃:由 Chat SDK 负责信令,Calls SDK 承载媒体,需要 cometchat_sdk v5。
【Flutter 特有:joinSession 返回 Widget】 其他平台把通话挂载到调用方提供的容器中,而 Flutter 将通话以 Widget? 返回且不自行挂载。需将 onSuccess 回调中的 Widget? 存入 State,并在 build() 中返回,否则通话已加入但界面不显示(有声音、无画面、无控件),这是 Flutter 最常见的失败。示例:Widget? _callWidget; CometChatCalls.joinSession(sessionId: sessionId, sessionSettings: settings, onSuccess: (Widget? w) => setState(() => _callWidget = w), onError: (CometChatCallsException e) { /* 处理错误 */ }); 然后在 build 中返回 _callWidget ?? const CircularProgressIndicator()。
【SDK 方法概览(封闭符号列表,签名需从文档获取)】 生命周期:initFromSettings、init、CallAppSettingBuilder → CallAppSettings、isInitialized、login、loginWithAuthToken、logout、getLoggedInUser → User?。 会话:generateCallToken(sessionId, …) → CallToken、joinSession(…) → Widget?、SessionSettingsBuilder → SessionSettings、SessionType。存在两条 join 路径:generateCallToken(sessionId) → joinSession(callToken:sessionSettings:),或直接 joinSession(sessionId:sessionSettings:)。 通话内操作(在 CallSession.getInstance() 上,仅用于自定义控件):leaveSession、muteAudio/unMuteAudio、pauseVideo/resumeVideo、setLayout、setAudioModeType、switchCamera、raiseHand/lowerHand、startRecording/stopRecording、startScreenShare/stopScreenShare/toggleScreenShare、pinParticipant/unPinParticipant、muteParticipant、pauseParticipantVideo、enablePictureInPictureLayout/disablePictureInPictureLayout、enterPipMode/isPipSupported、setChatButtonUnreadCount、isCallSessionActive。Flutter 专有开关:toggleMuteAudio、togglePauseVideo、toggleCameraSource、toggleRaiseHand。别名:endCallSession、startCallRecording/stopCallRecording、setCallLayoutType。设置面板:hideSettingsPanel、openCallSettingsPanel、openVirtualBackgroundSettingsPanel。状态读取:isAudioMuted、isVideoPaused、isHandRaised、isRecording、isScreenSharing、isTranscribing。监听器:SessionStatusListeners、ParticipantEventListeners、MediaEventListeners、ButtonClickListeners、LayoutListeners。通话日志:CallLogRequestBuilder → CallLogRequest → fetchNext/fetchPrevious → CallLog。后台:CometChatOngoingCallService.launch() / .abort()(Android 前台服务,iOS 为空操作)。枚举:AudioMode、SessionType、LayoutType、CameraFacing。
【监听器生命周期】 五种监听器均为抽象类,需实现而非实例化。建议使用 extends 并只覆写需要的方法(其余方法已有空实现)。监听器实例应提升为字段,在加入前注册,移除时传入同一实例;新建实例去移除是无效操作并会静默泄漏。注册方法名与类型名并不一致,例如 MediaEventListeners 通过 addMediaEventsListener 注册,LayoutListeners 没有 add/remove,而是单槽的 layoutListener 属性,用 = null 清除。CallSession.getInstance() 实际不会为 null,但类型仍为 CallSession?,需保留 ?.,可用 isCallSessionActive() 判断是否有活动会话。ButtonClickListeners 的回调与 SDK 自身动作并行触发且不会抑制它,例如 onLeaveSessionButtonClicked 中不应再调用 leaveSession(),否则会重复离开。 Participant 有十二个字段且均可为空:uid、name、avatar、mid、state、isJoined、deviceId、joinedAt、leftAt、totalAudioMinutes、totalVideoMinutes、totalDurationInMinutes。文档中列出的 pid/role/audioMuted/videoPaused/isPinned/isPresenting/raisedHandTimestamp 并不存在,无法编译,需通过 ParticipantEventListeners 累积这些实时状态,建议使用 onParticipantListChanged 获取完整列表。
【最小代码顺序(会议式)】
- initFromSettings;2. login 或 loginWithAuthToken;3. 用 SessionSettingsBuilder 构建 SessionSettings;4. 加入前注册 SessionStatusListeners;5. joinSession 并在 onSuccess 中保存 Widget;6. 在 build() 中返回该 Widget;7. 无需自建控件按钮,返回的 Widget 已渲染静音/视频/离开等控件;8. 退出时移除各监听器(同一实例)并调用 leaveSession()。
【后台与来电通知】 Android 应用进入后台后通话会被终止,除非用 CometChatOngoingCallService.launch() 维持前台服务(退出时 .abort()),该调用在 iOS 上为空操作。Flutter 没有官方推送包,关闭应用后的响铃需由应用自行接入 FCM(Android)与 APNs/PushKit/CallKit(iOS),并需要仪表盘推送提供商与真机。
【文档更正与常见陷阱】 官方 /calls/flutter/** 页面存在约 23 类符号在 5.0.7 下无法通过 flutter analyze,例如文档中的 generateToken(sessionId: …) 应改用 generateCallToken(sessionId, onSuccess:, onError:);Participant 的多个字段不存在。复制文档代码前应先查阅更正表。其他陷阱包括:忘记挂载返回的 Widget;重复添加内置通话控件(返回的 Widget 已是完整通话界面,仅在用户明确要求替换默认控件时才使用 CallSession 操作,并先用 SessionSettingsBuilder 的 hide*Button 隐藏内置控件);移除未保存的监听器;User 被两个 barrel 同时导出导致 ambiguous_import(需 hide User);响铃退出需同时调用 leaveSession() 与 CometChat.endCall(sessionId);没有 cancelCall,取消自己的去电应使用 rejectCall(sessionId, CometChatCallStatus.cancelled);仅声明清单权限而未运行时请求;minSdkVersion 未改为 26;Apple Silicon 上 iOS 模拟器因 CometChatWebRTC 排除 arm64 而只能构建 x86_64,仅适用于 iOS 18 模拟器。