findscripter 何时使用
适用：
- 把 Zoom Virtual Agent（虚拟客服坐席）的对话机器人嵌入网站，用 Campaign 或 Entry ID 启动聊天，并传入客户上下文。
- 在 Android WebView / iOS WKWebView 中包一层原生壳，需要原生关闭、转人工（support_handoff）、外链跳转等桥接。
- 用自定义 API 把外部系统的知识库同步进 ZVA（KB sync）。
- 处理对话生命周期（就绪、engagement 开始/结束）与 UI 状态。
不该用：
- 要在 Zoom 客户端内做 Contact Center 应用面板 —— 转 contact-center 相关技能。
- 纯后端知识库 CRUD / 自动化脚本，不涉及前端嵌入 —— 用 OAuth + REST API 技能。
- 非 Zoom 的客服/机器人平台 —— 本条命令、事件名、桥接约定均不通用。
步骤 / 指令
标准生命周期（Web 与移动端通用）：
- 在 Virtual Agent 管理后台配置并发布 Campaign 或 Entry，拿到 ID。
- 在页面/WebView 注入 SDK 脚本，提供运行时配置（
apikey、env、用户上下文）。 - 就绪门控：等
zoomCampaignSdk:ready事件或waitForReady()完成后，再注册事件、调任何 API。切勿在初始化前调show/hide/open/close。 - 注册事件监听：
open、close、show、hide、engagement_started、engagement_ended。 - 移动端在就绪时注入
window.zoomCampaignSdk.native，挂exitHandler、commonHandler、support_handoff回调。 - 结束会话调
endChat()，并在页面/视图销毁时移除监听。
嵌入选型：优先 Campaign 嵌入（用户摩擦最小）；仅当需要 Campaign 配置无法覆盖的预聊天数据采集时，才用 Entry ID。
外链策略（统一约定）：用 DOM 锚点 target="_blank" 或 window.open()；移动端在 WebView 代理里拦截决定「应用内 vs 系统浏览器」。已废弃 openURL 命令路径，跨版本行为不稳定，勿用。
知识库同步：用 Server-to-Server OAuth 拿短时 token，调 KB REST API，针对 ZVA_KB_ID 做自定义 API 写入。
示例
Web · Campaign 优先（推荐）：
<script data-apikey="YOUR_API_KEY" src="https://us01ccistatic.zoom.us/us01cci/web-sdk/zcc-sdk.js"></script>
<script>
window.addEventListener('zoomCampaignSdk:ready', () => {
window.zoomCampaignSdk.show();
window.zoomCampaignSdk.on('engagement_started', () => console.log('engagement started'));
});
</script>
Web · 运行时刷新用户上下文：
window.zoomCampaignSdkConfig = { env: 'us01', apikey: 'YOUR_API_KEY', firstName: 'Ada', email: 'ada@example.com' };
window.addEventListener('zoomCampaignSdk:ready', async () => {
if (window.zoomCampaignSdk.waitForReady) await window.zoomCampaignSdk.waitForReady();
window.zoomCampaignSdk.updateUserContext();
});
方法面：close()、endChat()、hide()、show()、ChangeCampaign(id, channel?)、updateUserContext()、waitForInit()、waitForReady()。
Android · 注入原生桥接（Kotlin）：
val js = """
javascript: window.addEventListener('zoomCampaignSdk:ready', () => {
if (window.zoomCampaignSdk) {
window.zoomCampaignSdk.native = {
exitHandler: { handle: function() { AndroidExit.handleExit(); } },
commonHandler: { handle: function(e) { AndroidCommon.handleCommon(JSON.stringify(e)); } }
};
}
});
""".trimIndent()
webView.loadUrl(js)
// 转人工：监听 support_handoff -> AndroidHandoff.handleHandoff(JSON.stringify(e.detail))
// 外链：shouldOverrideUrlLoading 决定应用内/系统浏览器；多窗口回调处理 target="_blank"
iOS · 注入桥接（Swift）：
let script = """
window.addEventListener('zoomCampaignSdk:ready', () => {
if (window.zoomCampaignSdk) {
window.zoomCampaignSdk.native = {
exitHandler: { handle: function() { window.webkit.messageHandlers.zoomLiveSDKMessageHandler.postMessage('close_web_vc'); } },
commonHandler: { handle: function(e) { window.webkit.messageHandlers.commonMessageHandler.postMessage(JSON.stringify(e)); } }
};
}
});
"""
// 转人工：support_handoff -> messageHandlers.support_handoff.postMessage(JSON.stringify(e.detail))
// 外链：WKNavigationActionPolicyAllow 走应用内；UIApplication.openURL 走系统浏览器；可选 SFSafariViewController
环境变量（要点）：ZVA_API_KEY、ZVA_ENV（us01/eu01）、ZVA_CAMPAIGN_ID、ZVA_ENTRY_ID；KB 自动化：ZOOM_ACCOUNT_ID、ZOOM_CLIENT_ID、ZOOM_CLIENT_SECRET、ZOOM_ACCESS_TOKEN、ZVA_KB_ID。
注意事项
- 就绪门控是头号坑：
window.zoomCampaignSdk未定义多半是没等ready；逻辑只在zoomCampaignSdk:ready后注册，能用waitForReady()就用。 - 命名漂移：官方文档现用 "Virtual Agent"，但示例仓库仍残留旧称
virtual-assistant、liveSDK、ZMLiveSDKWebviewController，搜索/映射代码时按当前文档语义走、把旧符号当别名映射。 - CSP / 脚本宿主：先确认 CSP 放行 Zoom SDK 脚本、websocket、media、wasm，且无代理拦掉
zcc-sdk.js；WebView 需开启 JavaScript。先排查这些再调业务逻辑。 - 脚本标签
defer可能打乱执行顺序（某些三方链路），按页面生命周期改用async或去掉defer。 - Campaign 配了却不显示：确认 Campaign 投放范围在移动 WebView 下包含移动端；校验 style/config API 网络响应。
- 登录/子域失败：核对 Virtual Agent 偏好设置里的子域名白名单与环境。
- 把桥接的命令/事件常量集中定义，隔离重命名风险；仅在确需向后兼容处保留旧 key 回退。
ZOOM_ACCESS_TOKEN为短时令牌，勿硬编码；凭据来源：Zoom Marketplace（OAuth 应用）、AI Management（Campaign/Entry、KB ID）。
互见
- related：
twilio-communications、whatsapp-cloud-api、slack-bolt-bot-builder—— 同属对话/客服渠道集成 - combines_with：OAuth 应用搭建与 REST 自动化技能 —— 用于知识库 CRUD / 后端编排；Contact Center 相关技能 —— 用于 Zoom 客户端内面板
采编自 anthropics/knowledge-work-plugins（Apache-2.0）。