Zoom Contact Center Android SDK 五分钟预检 Runbook集成前必查清单与调试决策树【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins导读本文围绕partner-built/zoom-plugin/skills/contact-center/android/RUNBOOK.md展开系统梳理 Zoom Contact CenterZoomCCAndroid SDK 集成前必须完成的 7 项预检动作与快速调试决策树。面向在原生 Android 应用中接入 chat / video / ZVA / scheduled callback / campaign 等渠道的开发者读完后你可以快速定位集成面与凭证要求、按正确顺序编排 SDK 生命周期、基于engagementId管理多会话状态、在几分钟内判定 UI 不打开、事件丢失、rejoin 失败等高频问题的根因并在升级前建立清理与版本漂移防护姿势。0. Runbook 定位与使用约定文档职责边界技能入口文件是SKILL.mdcontact-center/android/SKILL.md负责声明技能名、触发器、SDK 表面Surface与硬性护栏Hard Guardrails本 Runbook 是操作约定recommended不是必需的技能文件定位是深入调试之前的 5 分钟预检SDK/API 名称会随版本漂移发布前必须依据官方文档与仓库内 raw-docs 二次核验命名。从源码结构看整个contact-center技能族android / ios / web / general每个平台都配套一个独立 RUNBOOK本 Runbook 只针对 Android 原生集成路径与 contact-center/RUNBOOK.md 的三端总览形成总-分关系。与本技能族其他文档的关系文件作用concepts/sdk-lifecycle.md生命周期各阶段初始化/渠道初始化/启动/结束/清理/战役模式的完整顺序examples/service-patterns.mdChat / Video / Scheduled Callback / Cleanup 四类 Kotlin 代码范式references/android-reference-map.md核心类型、监听器、枚举、常用方法与弃用提示的速查映射troubleshooting/common-issues.md五大高频问题的原因与修复对照1. 确认集成面Integration Surface明确 Android 的渠道目标与集成模式Contact Center app 路径与 Web embed 路径的生命周期规则完全不同Android 原生集成走的是 Contact Center 移动 SDK 二进制与 service 生命周期路线对移动 SDK务必核实原生 service 生命周期与监听器注册顺序——先注册监听器再触发 action这是后续一切事件能否回调的前提。补充佐证顶层总 Runbook contact-center/RUNBOOK.md 明确指出路径选错Wrong path是混淆的第一大来源Android 侧应选择Native mobile app → Android/iOS Contact Center SDK binaries and service lifecycle而不是 Zoom Apps SDK 或 Web 嵌入路径。2. 确认必需凭证Required Credentials凭证适用场景说明entryIdchat / video / ZVA 三类渠道入口用于构建ZoomCCItem的渠道标识apiKeyscheduled callback 与 campaign/tag 用例用于ZoomCCScheduledCallbackService初始化与战役元数据拉取Zoom App 凭证 所需 scopes需要 in-client app 行为时需在 Marketplace 中核验应用凭证与 OAuth scopes 配置源码佐证examples/service-patterns.md中 chat/video 模式用entryId构造ZoomCCItemscheduled callback 模式改用apiKeytroubleshooting/common-issues.md的Video/Chat UI 不打开条目明确把ZoomCCItem中标识符类型填错列为首要原因。3. 确认生命周期顺序Lifecycle OrderAndroid 侧推荐顺序与 concepts/sdk-lifecycle.md 的 Startup → Channel Initialization → Launch 三段式一致尽早初始化 SDK 上下文在Application.onCreate中初始化ZoomCCInterface可附带设置/更新上下文用户名获取渠道 service通过getZoomCCChatService()/getZoomCCVideoService()/getZoomCCZVAService()/getZoomCCScheduledCallbackService()取得对应服务在 action 之前注册监听器/delegate按需认证/登录chat/ZVA 需要显式login()video 流程的登录通常在内部完成启动/获取渠道 UI 并处理 engagement 状态流转fetchUI()呈现渠道视图。各渠道 Launch 差异速查渠道init 凭证登录启动动作ChatentryId显式login()login()后fetchUI()VideoentryId通常内部完成配置 preview/auto-join 后fetchUI()ZVAentryId显式login()login()后fetchUI()Scheduled CallbackapiKey—直接fetchUI()事件不触发的根因常在顺序上common-issues.md明确Listener attached after service launch or removed early会导致事件不触发修复方式是在fetchUI之前添加监听器。4. 确认事件/状态处理Event/State Handling用engagementId跟踪状态不要假设单个 engagement 永远不变——一个 app 实例可能收到多个 engagement context处理 context-switch 事件时不丢失 draft/chat 工作流状态将草稿与工作流状态按engagementId持久化每个活跃 engagement 隔离其 service/channel 状态。佐证顶层总 Runbook 的Context Switching Behavior一节强调 chat/SMS/email 工作流中不可假设只有单一活跃 engagementAndroid 侧ZoomCCChatListener提供onEngagementStart(engagementId)/onEngagementEnd(engagementId)回调见 examples/service-patterns.md正是以engagementId维度驱动状态管理的接口。5. 确认清理与升级姿态Cleanup Upgrade Posture结束会话按需调用endChat()/endVideo()停止回调需要停止接收回调时调用logoff()释放 service 资源在 teardown 路径如onDestroy调用releaseZoomCCService(key)干净释放Android 注意点Runbook 中Forward app lifecycle callbacks for iOS integrations一句针对 iOSAndroid 侧核心是确保onDestroy中按 key 释放对应 servicechatEntryId / videoEntryId / callbackApiKey 各自独立升级前重查 SDK release notes警惕方法被重命名/弃用。清理范式来自 examples/service-patterns.mdoverride fun onDestroy() { ZoomCCInterface.releaseZoomCCService(chatEntryId) ZoomCCInterface.releaseZoomCCService(videoEntryId) ZoomCCInterface.releaseZoomCCService(callbackApiKey) super.onDestroy() }注意结束 engagement ≠ 释放 serviceendChat/endVideo只是结束单次服务会话releaseZoomCCService才是资源释放二者不可混用总 Runbook 的 Cleanup Semantics 一节专门强调。6. 快速探针Quick Probes预检期间用以下探针快速验证集成是否健康engagement context/status API 返回有效值目标渠道的 start/end 流程端到端各跑通一次listener 回调在 switch/end 事件上正常触发且无 stale state旧 engagement 的残留状态未污染新 engagement。实现层面的验证抓手ZoomCCChatListener的unreadMsgCountChanged、onClientEvent、onLoginStatus、onError(error, detail, description)等回调见 service-patterns可借助日志确认每个回调在预期时机触发。7. 快速决策树Fast Decision Tree症状直接原因候选检查方向UI 不打开无效的entryId/apiKey或初始化/监听器顺序缺失核验ZoomCCItem标识符类型与取值确认Application.onCreate初始化与先监听后fetchUI()事件丢失监听器注册太晚或意外被移除检查addListener调用位置是否早于fetchUI/login重连/恢复rejoin失败生命周期回调缺失或 deep-link/scheme 配置不匹配核对 Android manifest intent filter 与生成的 rejoin URL 格式见 common-issues.md 的Rejoin Link Opens Browser But Not App8. 源码检查点Source Checkpoints官方文档Zoom Contact Center Android 开发者文档https://developers.zoom.us/docs/contact-center/android/Android SDK 在线索引https://marketplacefront.zoom.us/sdk/contact/android/index.html仓库内 raw-docs需在仓库同步后核对存在性raw-docs/developers.zoom.us/docs/contact-center/android/raw-docs/marketplacefront.zoom.us/sdk/contact/android/说明以上 raw-docs 目录为 Runbook 约定的官方文档镜像路径经核实当前仓库工作区中暂未同步该目录find_files在partner-built/zoom-plugin下未检索到raw-docs/**实际使用时请以仓库内文档为准或在升级发布前从官方渠道同步后二次核验。仓库内相关技能文件用于快速定位技能入口与硬性护栏contact-center/android/SKILL.md生命周期顺序详解contact-center/android/concepts/sdk-lifecycle.mdKotlin 代码范式contact-center/android/examples/service-patterns.md类型/枚举/方法速查contact-center/android/references/android-reference-map.md高频问题排查contact-center/android/troubleshooting/common-issues.md附Android SDK 核心表面速记来自 SKILL.mdSDK 管理器ZoomCCInterface渠道 service 工厂getZoomCCChatService()/getZoomCCVideoService()/getZoomCCZVAService()/getZoomCCScheduledCallbackService()战役模式Campaign通过 web campaign service 与 campaign metadata 支持硬性护栏Application.onCreate中初始化 SDK用ZoomCCItem定义渠道与标识符chat/video/ZVA 用entryIdscheduled callback/campaign 用apiKeyteardown 时释放 service相邻能力入口in-client app 行为参考 zoom-apps-sdk/SKILL.mdContact Center API 自动化参考 rest-api/SKILL.md【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考