基于 Zoom Cobrowse SDK 构建客服协同浏览Co-Browsing支持系统实战指南【免费下载链接】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客服协同浏览Co-Browsing是解决客户说不清问题、填不完复杂表单这一长期痛点的关键技术支持人员可以在客户授权下实时查看其浏览器页面并通过批注、指针引导客户完成操作同时借助 PII 掩码保护敏感数据。本文以 Zoom Cobrowse SDK 为核心完整覆盖从认证服务器搭建、客户页面与坐席门户集成的三步实施方案并深入讲解隐私掩码、批注工具、会话管理与安全合规细节帮助你从零搭建一套可运行、可扩展的协同浏览支持能力。本文的配套实现细节可参考仓库中的 Zoom Cobrowse SDK 技能文档 与 客户支持协同浏览用例文中的架构、代码与参数均以这两份文档及仓库内配套参考为依据。用例概览问题与解决方案问题背景客户在电话或在线沟通中难以准确描述界面问题或在多步骤、多字段的复杂表单如保险申请、开户流程中频繁出错导致支持通话时间被拉长、客户挫败感上升、工单转化率下降。解决方案通过 Zoom Cobrowse SDK 实现客户与坐席之间的实时协同浏览。坐席可以实时查看客户浏览器中的页面状态用批注和指针引导客户操作同时 SDK 内置隐私控制能力通过 CSS 选择器对敏感字段进行掩码坐席看到的是被遮挡后的值客户数据不会泄露。这一能力既可以独立部署也可以与 客服中心集成 方案组合使用后者负责在 Zoom Contact Center 的 App、Web、移动端建立 engagement 上下文而本文介绍的 Cobrowse 则负责在具体会话中的实时屏幕协同。整体架构┌──────────────────────┐ ┌──────────────────────┐ │ Customer Browser │ │ Support Agent │ │ • View form/page │◄───────►│ • View customer │ │ • Share PIN │ Sync │ • Provide guidance │ │ • Get assistance │ │ • Draw annotations │ └──────────────────────┘ └──────────────────────┘ │ │ └────────────┬───────────────────┘ ▼ ┌──────────────────────┐ │ Your Auth Server │ │ • Generate JWTs │ │ • Log sessions │ │ • Track agents │ └──────────────────────┘从架构图可以看出整个系统由三个部分组成客户浏览器端通过 CDN 加载 ZoomCobrowseSDK负责展示页面/表单、生成并展示 PIN、发起会话坐席端门户通过 iframe 加载 Zoom 托管的 desk 模板负责查看客户页面、提供引导、绘制批注你自己的认证服务器Auth Server位于架构中枢负责签发客户与坐席各自的 JWT、记录会话日志、追踪坐席信息。两个角色的架构本质协同浏览存在两个职责完全不同的角色理解这一点是正确集成的关键参见 双角色模式角色role_type集成方式是否需 JWT用途客户Customer1网站集成CDN 或 npm是分享自己浏览器会话的用户坐席Agent2iframeCDN或 npm仅 BYOP是查看并协助客户的客服人员从仓库的 get-started 文档 可以看到客户与坐席使用不同的集成方式但走相同的 JWT 认证模式。两种角色必须使用独立的 JWT且令牌生成必须保留在服务端。PIN 码的权威来源关键规则仓库文档中特别强调了一条关键规则真正可供坐席加入使用的 PIN来自客户 SDK 的pincode_updated事件而不是后端预创建记录中的占位/临时 PIN。在 UI 中只展示一个明确标识的值例如Support PIN并让坐席端复用同一个值。如果违背这一规则坐席 desk 常会报Pincode is not found错误码 30308。典型生产流程是客户先发起会话role_type1后端创建/记录会话 → 返回客户 JWT → 客户 SDK 启动并收到 PIN坐席后加入role_type2坐席输入客户 PIN → 后端校验 PIN 与会话状态 → 返回坐席 JWT → 坐席打开 Zoom 托管的 desk iframe或 BYOP 模式下的自定义 npm 坐席 UI。实施步骤第一步搭建认证服务器JWT 签名的前提是获取四类凭据见 get-started 的凭据说明凭据类型用途是否可以暴露SDK Key公开CDN URL、JWT 的app_key声明可以客户端安全SDK Secret私有签名 JWT不可以仅服务端API Key私有REST API 调用可选不可以仅服务端API Secret私有REST API 调用可选不可以仅服务端关键点SDK Key 是公开的内嵌在 CDN URL 中但 SDK Secret 绝不能出现在任何客户端代码里。常见误区是把 API Key 误当作 JWTapp_key声明使用——JWT 中必须使用 SDK Key。认证服务器的核心代码server.js// server.js - JWT token generation const express require(express); const { KJUR } require(jsrsasign); app.post(/cobrowse-token, (req, res) { const { role, userId, userName, caseId } req.body; const iat Math.floor(Date.now() / 1000); const exp iat 60 * 60 * 2; // 2 hours const payload { app_key: process.env.ZOOM_SDK_KEY, role_type: role, // 1 customer, 2 agent user_id: userId, user_name: userName, iat, exp }; const token KJUR.jws.JWS.sign(HS256, JSON.stringify({ alg: HS256, typ: JWT }), JSON.stringify(payload), process.env.ZOOM_SDK_SECRET ); // Log session for tracking logCobrowseSession(caseId, userId, role); res.json({ token }); });JWT 的 payload 字段定义来自仓库 JWT 认证概念 与 get-started 文档字段是否必填说明app_key是你的 Zoom SDK Key不是 API Keyrole_type是用户角色1 客户2 坐席iat是令牌签发时间戳epochexp是令牌过期时间戳epoch最小 30 分钟最大 48 小时user_id是唯一可识别的用户 IDuser_name是用户名最长 80 字符enable_byop可选启用 Bring Your Own PIN1 是0或省略 否认证服务器还可以按 双角色模式文档 的建议做端点拆分让会话生命周期更清晰POST /api/customer/start→ 创建会话 签发客户 token 生成 PINPOST /api/agent/connect→ 校验 PIN 签发坐席 tokenPOST /api/session/revoke→ 结束会话GET /api/session/list→ 运维可视化第二步集成客户支持页面客户页面通过 CDN 加载 SDKsupport.html!-- support.html -- !DOCTYPE html html head script typemodule const ZOOM_SDK_KEY YOUR_SDK_KEY; // Load Cobrowse SDK (function(r, a, b, f, c, d) { r[f] r[f] || { init: function() { r.ZoomCobrowseSDKInitArgs arguments }}; var fragment a.createDocumentFragment(); function loadJs(url) { c a.createElement(b); d a.getElementsByTagName(b)[0]; c[async] false; c.src url; fragment.appendChild(c); } loadJs(https://us01-zcb.zoom.us/static/resource/sdk/${ZOOM_SDK_KEY}/js/2.13.2); d.parentNode.insertBefore(fragment, d); })(window, document, script, ZoomCobrowseSDK); /script /head body div idsupport-widget button idstart-cobrowseGet Support Help/button div idpin-display styledisplay:none; pShare this PIN with your support agent:/p div idpin-code/div /div /div !-- Customer form with sensitive fields -- form idcustomer-form input namename placeholderFull Name input nameemail placeholderEmail input namessn classpii-mask placeholderSSN input nameaccount classpii-mask placeholderAccount Number /form script let sessionRef null; const settings { allowAgentAnnotation: true, // Agent can highlight fields allowCustomerAnnotation: false, // Customer cant annotate piiMask: { maskType: custom_input, maskCssSelectors: .pii-mask // Hide sensitive fields from agent } }; ZoomCobrowseSDK.init(settings, function({ success, session, error }) { if (success) { sessionRef session; session.on(pincode_updated, (payload) { document.getElementById(pin-code).innerText payload.pincode; document.getElementById(pin-display).style.display block; }); session.on(agent_joined, () { console.log(Support agent connected); showNotification(Agent is now viewing your screen); }); } }); document.getElementById(start-cobrowse).addEventListener(click, async () { const caseId getCurrentCaseId(); const response await fetch(/cobrowse-token, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ role: 1, userId: customer_ Date.now(), userName: Customer, caseId: caseId }) }); const { token } await response.json(); sessionRef.start({ sdkToken: token }); }); /script /body /html代码中的几个要点值得展开说明CDN 版本管理加载地址js/2.13.2是固定版本也可以使用js/2.13.x获取2.13.0 且 2.14.0的最新补丁版本。仓库 get-started 文档 记录当前版本为 2.13.2。初始化设置allowAgentAnnotation控制坐席能否批注allowCustomerAnnotation控制客户能否批注piiMask用于隐私掩码见下文核心功能。会话事件pincode_updated是展示 PIN 的唯一权威来源agent_joined触发时可以弹出坐席正在查看你的屏幕提示这既是功能也是合规要求。完整事件列表参见 会话事件参考。启动会话调用sessionRef.start({ sdkToken: token })将服务端签发的客户 JWT 传入。第三步坐席门户集成坐席门户通过 iframe 嵌入 Zoom 托管的 desk 模板agent-portal.html!-- agent-portal.html -- !DOCTYPE html html head titleSupport Agent - Co-Browse/title /head body div classagent-dashboard div classcase-info h2Case #span idcase-id/span/h2 pCustomer: span idcustomer-name/span/p /div iframe idcobrowse-frame width1024 height768 allowautoplay *; camera *; microphone *; display-capture *; geolocation *; /iframe /div script async function loadCobrowseSession(caseId) { const response await fetch(/cobrowse-token, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ role: 2, userId: agent_ Date.now(), userName: getAgentName(), caseId: caseId }) }); const { token } await response.json(); const iframe document.getElementById(cobrowse-frame); iframe.src https://us01-zcb.zoom.us/sdkapi/zcb/frame-templates/desk?access_token${token}; } // Load cobrowse when case requires it const caseId getCurrentCaseId(); loadCobrowseSession(caseId); /script /body /htmliframe 的allow属性必须包含以下权限声明参见 get-started 的 iframe 权限说明autoplay *媒体自动播放、camera *摄像头、microphone *麦克风、display-capture *屏幕捕获、geolocation *定位服务。iframe 方式无法自定义坐席 UI如需完全自定义的坐席界面应改用 npm 集成并配合 BYOPBring Your Own PIN模式。核心功能详解隐私掩码Privacy Masking隐私掩码是协同浏览方案中的第一安全屏障。它通过 CSS 选择器自动隐藏客户敏感数据坐席看到的将是掩码后的内容const settings { piiMask: { maskType: custom_input, maskCssSelectors: .pii-mask, .sensitive, [data-private], maskHTMLAttributes: data-privatetrue } };会被掩码的数据社会保险号SSN信用卡号银行账号密码任何带有.pii-mask类的字段仓库 get-started 文档 补充了掩码的适用范围支持掩码文本节点、表单输入input、下拉选择select不支持掩码img图片元素和链接元素。这意味着对图片中渲染的敏感信息如证件扫描件需要另行处理。此外从 SKILL.md 的已知限制 可以确认掩码依据的maskType支持custom_input按选择器精确掩码与all_input掩码全部输入框两种模式后者适合整页表单都需要保护的场景。批注工具Annotation Tools坐席可以用可视化方式引导客户操作画笔Pen高亮表单字段批注内容持续保留矩形Rectangle圈出重要区域指针Pointer将客户注意力引导到特定元素从 SKILL.md 的批注说明 可以看到SDK 还提供渐隐笔Vanishing Pen4 秒后自动消失、取色器Color Picker、橡皮擦Eraser与撤销/重做Undo/Redo等完整绘图工具集且客户与坐席的批注权限可分别通过allowCustomerAnnotation/allowAgentAnnotation独立控制。具体配置示例见 批注工具示例。会话管理Session Management所有协同浏览会话都应被记录与追踪便于审计与质量分析function logCobrowseSession(caseId, userId, role) { const log { caseId, userId, role: role 1 ? customer : agent, timestamp: new Date(), sessionType: cobrowse }; database.sessions.insert(log); }会话的生命周期由 SDK 事件驱动完整事件见 会话事件参考session_started会话开始、pincode_updatedPIN 更新、agent_joined/agent_left坐席加入/离开、session_ended会话结束、session_reconnecting重连中、session_error错误。客户与坐席两端的事件流可以对照 会话生命周期文档 理解客户流程加载 SDK →init→ 获取 JWTrole_type1→session.start({ sdkToken })→pincode_updated事件生成 PIN → 分享 PIN →agent_joined→ 实时同步 →session.end()或坐席离开坐席流程获取 JWTrole_type2→ 加载 desk iframe → 输入客户 PIN → 连接 → 查看页面 → 使用批注/远程协助工具 → 点击离开。典型业务场景场景一复杂表单填写协助背景客户在填写多步骤保险申请表时卡住。流程客户在表单页面点击获取帮助系统生成并展示 PIN客户致电支持热线告知坐席 PIN坐席输入 PIN看到客户的表单坐席使用批注高亮下一个需要填写的字段客户在实时引导下完成表单敏感字段SSN、医疗信息对坐席保持掩码状态效果表单在约 5 分钟内完成而传统的纯电话引导通常需要 20 分钟。场景二技术问题排查背景客户找不到账号设置入口。流程客户从帮助聊天发起协同浏览坐席加入会话坐席用指针演示导航路径客户跟随可视化引导操作问题实时解决效果无需额外安装任何屏幕共享软件问题即时解决。场景三新用户引导Onboarding背景首次使用的用户需要引导式参观。流程引导专员发起协同浏览客户通过 PIN 加入专员引导用户走完核心功能批注高亮关键功能入口客户在自己的浏览器中跟随操作效果交互式引导显著提升新用户的完成率与上手体验。安全与合规考量1. 隐私合规GDPR/CCPA// GDPR/CCPA compliant data handling const privacySettings { piiMask: { maskType: custom_input, maskCssSelectors: .pii-mask }, sessionRecording: false, // Dont record sessions dataRetention: 24h // Auto-delete session logs };合规设计的三个要点默认掩码所有敏感字段、默认不录制会话、日志设置自动过期策略。从仓库的 会话生命周期文档 可知会话记录session record应包含session_id、生成的 PIN、状态active/revoked与过期时间戳为审计和撤销提供依据。2. 坐席认证// Verify agent credentials before token generation async function validateAgent(agentId) { const agent await database.agents.findOne({ id: agentId }); if (!agent || !agent.cobrowseEnabled) { throw new Error(Agent not authorized for cobrowse); } return agent; }在签发坐席 JWT 之前必须校验坐席身份及其协同浏览权限未授权或权限被关闭的坐席直接拒绝签发。这是防止内部权限滥用的关键防线。3. 会话限制与超时仓库 SKILL.md 的会话限制表格 给出了官方约束可直接作为系统设计依据限制项值触发行为每会话客户数1错误码 1012SESSION_CUSTOMER_COUNT_LIMIT每会话坐席数5错误码 1013SESSION_AGENT_COUNT_LIMIT每浏览器活跃会话数1错误码 1004SESSION_COUNT_LIMITPIN 长度上限10 字符错误码 1008SESSION_PIN_INVALID_FORMAT坐席等待客户3 分钟会话自动结束页面刷新重连窗口2 分钟超时未重连则结束重连尝试次数最多 2 次失败后会话结束JWT 有效期2 小时过期需重新签发同时要求所有连接必须使用 HTTPS本地开发可退而求其次使用 loopback 主机或本地 HTTPS 端点。完整错误码说明可参考 错误码参考。指标与数据分析追踪协同浏览的有效性// Track session metrics const metrics { sessionDuration: calculateDuration(startTime, endTime), issueResolved: true, customerSatisfaction: 5, formFieldsCompleted: 12, annotationsUsed: 8 }; analytics.track(cobrowse_session_completed, metrics);关键指标平均会话时长Average session duration问题解决率Issue resolution rate客户满意度 CSATCustomer satisfaction相对电话支持节省的时间Time saved vs phone support表单完成转化率Conversion rate / form completion这些指标应结合上文会话管理中的会话日志一起沉淀形成从日志到指标的完整数据闭环。与现有系统的集成Salesforce 集成// Log cobrowse session to Salesforce case async function logToSalesforce(caseId, sessionData) { await salesforce.cases.update(caseId, { Cobrowse_Session_Date__c: new Date(), Cobrowse_PIN__c: sessionData.pin, Agent_Id__c: sessionData.agentId, Session_Duration__c: sessionData.duration }); }将协同浏览会话的日期、PIN、坐席 ID、时长回写到 Salesforce case 的自定义字段可以让工单记录完整覆盖支持过程。更进一步的方案可以结合 客服中心集成 中的 Smart Embed 事件实现 CRM 与协同会话的深度联动。Zendesk 集成// Add cobrowse note to Zendesk ticket await zendesk.tickets.addComment(ticketId, { body: Cobrowse session completed. PIN: ${pin}. Duration: ${duration}, public: false });以内部备注public: false方式把协同会话信息写入 Zendesk 工单客户不可见但坐席与质检团队可以追溯。最佳实践明确的隐私披露Clear Privacy Disclosure告知客户坐席能看到什么、不能看到什么客户页面常驻显示坐席正在查看你的屏幕Agent is viewing your screen横幅可在agent_joined事件回调中触发选择性掩码Selective Masking默认全部掩码仅在确有必要时解除广泛使用.pii-mask类标注敏感字段宁可多标不可漏标会话日志Session Logging记录所有会话以满足合规审计要求记录坐席操作行为用于质量保障QA坐席培训Agent Training对坐席进行隐私控制专项培训建立批注使用规范何时用画笔、何时用矩形、何时用指针客户授权Customer Consent在会话开始前取得客户明确同意允许客户随时主动结束会话客户可调用session.end()或点击界面按钮成本考量Zoom Cobrowse SDK 的成本结构基于原文档的说明按协同浏览分钟数计费Pay per cobrowse minute需要 SDK Universal Credits 支持示例估算按每日 100 个会话、每个会话平均 10 分钟计算约 1,000 分钟/天根据所选套餐每日费用大致在数十美元量级注意具体单价与套餐以 Zoom Marketplace 后台实际数据为准上文的估算仅用于容量规划参考。当前仓库不提供价格保证实施前请以官方计费说明为准。常见问题排查问题客户看不到 PIN方案检查pincode_updated事件处理器是否正确挂载并确认没有使用后端预创建记录中的占位 PIN这是导致坐席端Pincode is not found/ 30308 的最常见原因。问题坐席看到了敏感数据方案核对敏感字段是否已正确添加.pii-mask类并确认piiMask.maskCssSelectors选择器与页面 DOM 匹配注意图片和链接元素不支持掩码。问题页面刷新后会话断开方案实现自动重连模式Auto-Reconnection。客户刷新页面后SDK 会在 2 分钟窗口内尝试恢复会话初始化回调中检查session.getSessionInfo()若sessionStatus session_recoverable则调用session.join()自动重连否则新建会话参见 自动重连示例。需要说明的是重连依赖浏览器第三方 Cookie隐私模式或启用了阻止跨站跟踪的浏览器可能受限。更多诊断线索可参考 常见问题排查 与 CORS/CSP 配置指南注意 CSP 头必须放行*.zoom.us域。相关资源与下一步行动仓库内相关文档Zoom Cobrowse SDK 主文档SDK 总览、快速开始与完整文档索引Get Started 指南从凭据到首个会话的完整搭建步骤会话事件参考全部事件类型定义隐私掩码示例掩码模式配置客户集成示例 与 坐席集成示例两端完整实现JWT 认证概念令牌结构与签名规范客服中心集成与 Zoom Contact Center 的组合方案推荐的落地路线通读 Get Started 指南完成凭据申请与首个会话联调按 JWT 认证概念 搭建服务端令牌签发端点按 客户集成示例 接入客户支持页面配置 PIN 展示与隐私掩码按 坐席集成示例 部署坐席门户按 隐私掩码示例 全面测试敏感字段掩码并通过双浏览器含无痕模式完成端到端验证通过上述步骤你将获得一套具备实时协同、隐私保护、会话审计与工单联动能力的完整客服协同浏览系统。【免费下载链接】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），仅供参考