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:

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

1. 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)

• 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:

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
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:

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:

// 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)

<!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;