zoom-cobrowse-sdk

# Zoom Cobrowse SDK - Web Development Background reference for collaborative browsing on the web with Zoom Cobrowse SDK. Use this after the support workflow is clear and you need implementation detail. **Official Documentation**: https://developers.zoom.us/docs/cobrowse-sdk/ **API Reference**: https://marketplacefront.zoom.us/sdk/cobrowse/ **Quickstart Repository**: https://github.com/zoom/CobrowseSDK-Quickstart **Auth Endpoint Sample**: https://github.com/zoom/cobrowsesdk-auth-endpoint-sample ## Quick Links **New to Cobrowse SDK? Follow this path:** 1. **[Get Started Guide](get-started.md)** - Complete setup from credentials to first session 2. **[Session Lifecycle](concepts/session-lifecycle.md)** - Understanding customer and agent flows 3. **[JWT Authentication](concepts/jwt-authentication.md)** - Token generation and security 4. **[Customer Integration](examples/customer-integration.md)** - Integrate SDK into your website 5. **[Agent Integration](examples/agent-integration.md)** - Set up agent portal (iframe or npm) **Core Concepts:** - **[Two Roles Pattern](concepts/two-roles-pattern.md)** - Customer vs Agent architecture - **[Session Lifecycle](concepts/session-lifecycle.md)** - PIN generation, connection, reconnection - **[JWT Authentication](concepts/jwt-authentication.md)** - SDK Key vs API Key, role_type, claims - **[Distribution Methods](concepts/distribution-methods.md)** - CDN vs npm (BYOP) **Features:** - **[Annotation Tools](examples/annotations.md)** - Drawing, highlighting, pointer tools - **[Privacy Masking](examples/privacy-masking.md)** - Hide sensitive fields from agents - **[Remote Assist](examples/remote-assist.md)** - Agent can scroll customer's page - **[Multi-Tab Persistence](examples/multi-tab-persistence.md)** - Session continues across tabs - **[BYOP Mode](examples/byop-custom-pin.md)** - Bring Your Own PIN with npm integration **Troubleshooting:** - **[Common Issues](troubleshooting/common-issues.md)** - Quick diagnostics and solutions - **[Error Codes](troubleshooting/error-codes.md)** - Complete error reference - **[CORS and CSP](troubleshooting/cors-csp.md)** - Cross-origin and security policy configuration - **[Browser Compatibility](troubleshooting/browser-compatibility.md)** - Supported browsers and limitations - **[5-Minute Runbook](RUNBOOK.md)** - Fast preflight checks before deep debugging **Reference:** - **[API Reference](references/api-reference.md)** - Complete SDK methods and events - **[Settings Reference](references/settings-reference.md)** - All initialization settings - **Integrated Index** - see the section below in this file ## SDK Overview The Zoom Cobrowse SDK is a JavaScript library that provides: - **Real-Time Co-Browsing**: Agent sees customer's browser activity live - **PIN-Based Sessions**: Secure 6-digit PIN for customer-to-agent connection - **Annotation Tools**: Drawing, highlighting, vanishing pen, rectangle, color picker - **Privacy Masking**: CSS selector-based masking of sensitive form fields - **Remote Assist**: Agent can scroll customer's page (with consent) - **Multi-Tab Persistence**: Session continues when customer opens new tabs - **Auto-Reconnection**: Session recovers from page refresh (2-minute window) - **Session Events**: Real-time events for session state changes - **HTTPS Required**: Secure connections (HTTP only works on loopback/local development hosts) - **No Plugins**: Pure JavaScript, no browser extensions needed ## Two Roles Architecture Cobrowse has **two distinct roles**, each with different integration patterns: | Role | role_type | Integration | JWT Required | Purpose | |------|-----------|-------------|--------------|---------| | **Customer** | 1 | Website integration (CDN or npm) | Yes | User who shares their browser session | | **Agent** | 2 | Iframe (CDN) or npm (BYOP only) | Yes | Support staff who views/assists customer | **Key Insight**: Customer and agent use **different integration methods** but the same JWT authentication pattern. ## Read This First (Critical) For customer/agent demos, treat the PIN from customer SDK event `pincode_updated` as the only user-facing PIN. - Show one clearly labeled value in UI (for example, **Support PIN**). - Use that same PIN for agent join. - Do not expose provisional/debug PINs from backend pre-start records to users. If these rules are ignored, agent desk often fails with `Pincode is not found` / code `30308`. ### Typical Production Flow (Most Common) This is the flow most teams implement first, and what users usually expect in demos: 1. **Customer starts session first** (`role_type=1`) - Backend creates/records session - Backend returns customer JWT - Customer SDK starts and receives a PIN 2. **Agent joins second** (`role_type=2`) - Agent enters customer PIN - Backend validates PIN and session state - Backend returns agent JWT - Agent opens Zoom-hosted desk iframe (or custom npm agent UI in BYOP) If a demo only has one generic "session" user, it is incomplete for real cobrowse operations. ## Prerequisites ### Platform Requirements - **Supported Browsers**: - Chrome 80+ ✓ - Firefox 78+ ✓ - Safari 14+ ✓ - Edge 80+ ✓ - Internet Explorer ✗ (not supported) - **Network Requirements**: - HTTPS required (HTTP works on loopback/local development hosts only) - Allow cross-origin requests to `*.zoom.us` - CSP headers must allow Zoom domains (see [CORS and CSP guide](troubleshooting/cors-csp.md)) - **Third-Party Cookies**: - Must enable third-party cookies for refresh reconnection - Privacy mode may limit certain features ### Zoom Account Requirements 1. **Zoom Workplace Account** with SDK Universal Credit 2. **Video SDK App** created in Zoom Marketplace 3. **Cobrowse SDK Credentials** from the app's Cobrowse tab **Note**: Cobrowse SDK is a **feature of Video SDK** (not a separate product). ### Credentials Overview You'll receive **4 credentials** from Zoom Marketplace → Video SDK App → Cobrowse tab: | Credential | Type | Used For | Exposure Safe? | |------------|------|----------|----------------| | **SDK Key** | Public | CDN URL, JWT `app_key` claim | ✓ Yes (client-side) | | **SDK Secret** | Private | Sign JWTs | ✗ No (server-side only) | | **API Key** | Private | REST API calls (optional) | ✗ No (server-side only) | | **API Secret** | Private | REST API calls (optional) | ✗ No (server-side only) | **Critical**: SDK Key is **public** (embedded in CDN URL), but SDK Secret must **never** be exposed client-side. ## Quick Start ### Step 1: Get SDK Credentials 1. Go to [Zoom Marketplace](https://marketplace.zoom.us/) 2. Open your **Video SDK App** (or create one) 3. Navigate to the **Cobrowse** tab 4. Copy your credentials: - SDK Key - SDK Secret - API Key (optional) - API Secret (optional) ### Step 2: Set Up Token Server Deploy a server-side endpoint to generate JWTs. Use the official sample: ```bash git clone https://github.com/zoom/cobrowsesdk-auth-endpoint-sample.git cd cobrowsesdk-auth-endpoint-sample npm install # Create .env file cat > .env << EOF ZOOM_SDK_KEY=your_sdk_key_here ZOOM_SDK_SECRET=your_sdk_secret_here PORT=4000 EOF npm start ``` **Token endpoint:** ```javascript // POST https://YOUR_TOKEN_SERVICE_BASE_URL { "role": 1, // 1 = customer, 2 = agent "userId": "user123", "userName": "John Doe" } // Response { "token": "eyJhbGciOiJIUzI1NiIs..." } ``` ### Step 3: Customer Side Integration (CDN) ```html <!DOCTYPE html> <html> <head> <title>Customer - Cobrowse Demo</title> <script type="module"> const ZOOM_SDK_KEY = 'YOUR_SDK_KEY'; // Load SDK from CDN (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> <h1>Customer Support</h1> <button id="cobrowse-btn" disabled>Loading...</button> <!-- Sensitive fields - will be masked from agent --> <label>SSN: <input type="text" class="pii-mask" placeholder="XXX-XX-XXXX"></label> <label>Credit Card: <input type="text" class="pii-mask" placeholder="XXXX-XXXX-XXXX-XXXX"></label> <script type="module"> let sessionRef = null; const settings = { allowAgentAnnotation: true, allowCustomerAnnotation: true, piiMask: { maskCssSelectors: ".pii-mask", maskType: "custom_input" } }; ZoomCobrowseSDK.init(settings, function({ success, session, error }) { if (success) { sessionRef = session; // Listen for PIN code session.on("pincode_updated", (payload) => { console.log("PIN Code:", payload.pincode); // IMPORTANT: this is the PIN agent should use alert(`Share this PIN with agent: ${payload.pincode}`); }); // Listen for session events session.on("session_started", () => console.log("Session started")); session.on("agent_joined", () => console.log("Agent joined")); session.on("agent_left", () => console.log("Agent left")); session.on("session_ended", () => console.log("Session ended")); document.getElementById("cobrowse-btn").disabled = false; document.getElementById("cobrowse-btn").innerText = "Start Cobrowse Session"; } else { console.error("SDK init failed:", error); } }); document.getElementById("cobrowse-btn").addEventListener("click", async () => { // Fetch JWT from your server const response = await fetch("https://YOUR_TOKEN_SERVICE_BASE_URL", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ role: 1, userId: "customer_" + Date.now(), userName: "Customer" }) }); const { token } = await response.json(); // Start cobrowse session sessionRef.start({ sdkToken: token }); }); </script> </body> </html> ``` ### Step 4: Agent Side Integration (Iframe) ```html <!DOCTYPE html> <html> <head> <title>Agent Portal</title> </head> <body> <h1>Agent Portal</h1> <iframe id="agent-iframe" width="1024" height="768" allow="autoplay *; camera *; microphone *; display-capture *; geolocation *;" ></iframe> <script> async function connectAgent() { // Fetch JWT from your server const response = await fetch("https://YOUR_TOKEN_SERVICE_BASE_URL", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ role: 2, userId: "agent_" + Date.now(), userName: "Support Agent" }) }); const { token } = await response.json(); // Load Zoom agent portal const iframe = document.getElementById("agent-iframe"); iframe.src = `https://us01-zcb.zoom.us/sdkapi/zcb/frame-templates/desk?access_token=${token}`; } connectAgent(); </script> </body>