Probe Sdk

Zoom Probe SDK

Background reference for preflight diagnostics on user devices and networks before meeting or session workflows.

Official docs:

• https://developers.zoom.us/docs/probe-sdk/
• https://marketplacefront.zoom.us/sdk/probe/index.html

Reference sample:

• https://github.com/zoom/probesdk-web

Routing Guardrail

• Use Probe SDK when the user needs client-side diagnostics and readiness scoring (device/network/browser capability), not meeting/session join.
• If user needs embedded meeting flows, route to ../meeting-sdk/SKILL.md.
• If user needs custom real-time session UX, route to ../video-sdk/SKILL.md.
• If user needs backend orchestration of events/APIs, chain with ../rivet-sdk/SKILL.md, ../oauth/SKILL.md, and ../rest-api/SKILL.md.

Quick Links

Start here: 1. probe-sdk.md 2. concepts/architecture-and-lifecycle.md 3. scenarios/high-level-scenarios.md 4. examples/diagnostic-page-pattern.md 5. examples/comprehensive-network-pattern.md 6. references/probe-reference-map.md 7. references/environment-variables.md 8. references/versioning-and-compatibility.md 9. references/samples-validation.md 10. references/source-map.md 11. troubleshooting/common-issues.md 12. RUNBOOK.md

Common Lifecycle Pattern

1. Initialize Prober / Reporter. 2. Request media permissions and enumerate devices. 3. Run targeted diagnostics (diagnoseAudio, diagnoseVideo). 4. Run comprehensive network diagnostic (startToDiagnose) and stream stats to UI. 5. Produce final report and apply readiness gates. 6. Stop/cleanup (stopToDiagnose, stopToDiagnoseVideo, releaseMediaStream, cleanup).

High-Level Scenarios

• Pre-join diagnostics page before Meeting SDK join action.
• Support workflow that captures structured report for customer troubleshooting.
• Device certification flow for kiosk or controlled endpoint environments.
• Browser capability gating for advanced media features.

See scenarios/high-level-scenarios.md for details.

Chaining

• Meeting pre-join gate: ../meeting-sdk/web/SKILL.md
• Video session readiness gate: ../video-sdk/web/SKILL.md
• Telemetry/report ingestion backend: ../rivet-sdk/SKILL.md + ../rest-api/SKILL.md

Environment Variables

• See references/environment-variables.md for optional .env keys and how to source values.

Operations

• RUNBOOK.md - 5-minute preflight and debugging checklist.

Probe SDK Architecture and Lifecycle

Purpose

Probe SDK answers one question before real-time media starts:

• Can this user/device/network support an acceptable experience?

Architecture Model

User Browser
  -> Probe SDK (Prober, Reporter)
     -> Media APIs (permissions/devices)
     -> Renderer path (video tag / WebGL / WebGL2 / WebGPU)
     -> Network probing runtime (JS/WASM + domain endpoint)
  -> Diagnostic stats stream + final report
  -> UI gating decision (allow join / warn / block)

Lifecycle Workflow

1. Initialize

• const prober = new Prober()
• const reporter = new Reporter() (optional for standalone feature/basic reports)

2. Permissions and devices

• requestMediaDevicePermission({ audio: true, video: true })
• requestMediaDevices()

3. Targeted diagnostics

• diagnoseAudio(inputConstraints, outputConstraints, duration)
• diagnoseVideo(constraints, { rendererType, target })

4. Comprehensive diagnostics

• startToDiagnose(jsUrl, wasmUrl, config, statsListener)
• stream live stats and wait for final report payload

5. Tear-down and cleanup

• stopToDiagnose() / stopToDiagnoseVideo(stream?)
• releaseMediaStream(stream)
• cleanup()

Readiness Policy Calibration

• Keep readiness policy product-specific and versioned (for example, policy_version=2026-02).
• Define explicit thresholds per output signal (allow, warn, block) for network/audio/video outcomes.
• Recalibrate policy thresholds whenever upgrading Probe SDK or changing browser support baseline.
• Log policy version with each final report so support can reproduce decisions.

Data Model Notes

Typical final report includes:

• network diagnostic result
• basic info entries
• supported feature entries

Field naming may vary by version (basicInfo vs basicInfoEntries, supportedFeatures vs featureEntries), so version-aware adapters are recommended.

Comprehensive Network Diagnostic Pattern

import { Prober } from "@zoom/probesdk";

const prober = new Prober();

export async function runComprehensiveDiagnostic() {
  const jsUrl = "";   // optional custom hosted prober.js
  const wasmUrl = ""; // optional custom hosted prober.wasm loader

  const config = {
    probeDuration: 120 * 1000,
    connectTimeout: 20 * 1000,
    domain: "zoom.us",
  };

  const statsHistory = [];

  const report = await prober.startToDiagnose(jsUrl, wasmUrl, config, (stats) => {
    statsHistory.push(stats);
  });

  return {
    report,
    statsHistory,
  };
}

export async function stopEarlyAndCollect() {
  const partial = await prober.stopToDiagnose();
  prober.cleanup();
  return partial;
}

Notes

• Use stats callback for realtime charting; keep callback lightweight.
• Wrap final report fields behind adapter layer for version drift.

Diagnostic Page Pattern

import { Prober } from "@zoom/probesdk";

const prober = new Prober();

export async function runDeviceChecks(videoCanvas) {
  const permission = await prober.requestMediaDevicePermission({ audio: true, video: true });
  if (permission.error) return { ok: false, stage: "permission", error: permission.error };

  const devices = await prober.requestMediaDevices();
  if (devices.error) return { ok: false, stage: "devices", error: devices.error };

  const cameraId = devices.devices?.find((d) => d.kind === "videoinput")?.deviceId || "default";
  const micId = devices.devices?.find((d) => d.kind === "audioinput")?.deviceId || "default";
  const speakerId = devices.devices?.find((d) => d.kind === "audiooutput")?.deviceId;

  const audioResult = await prober.diagnoseAudio(
    { audio: { deviceId: micId }, video: false },
    { audio: { deviceId: speakerId }, video: false },
    5000
  );

  const videoResult = await prober.diagnoseVideo(
    { video: { deviceId: cameraId } },
    { rendererType: 2, target: videoCanvas }
  );

  return { ok: true, devices: devices.devices, audioResult, videoResult };
}

export function cleanupStream(stream) {
  prober.releaseMediaStream(stream);
  prober.cleanup();
}

Notes

• rendererType target requirements must match chosen renderer.
• Always release media streams when diagnostics are complete.

Zoom Probe SDK (Overview)

Probe SDK is a web diagnostics SDK used to validate media devices, network quality, and browser capability before meeting/session workflows.

For full documentation and navigation, start at SKILL.md.

Quick Links

• Architecture and Lifecycle
• High-Level Scenarios
• Diagnostic Page Pattern
• Comprehensive Network Pattern
• Probe Reference Map
• Sample Validation
• Common Issues

Probe SDK Environment Variables

Probe SDK does not require Zoom Marketplace credentials for core diagnostics.

Required .env keys

• None required by the SDK itself.

Optional .env keys (app-level conventions)

Notes

• Because no OAuth credentials are required, Probe SDK is suitable as a lightweight preflight page before auth-sensitive flows.
• Do not require ZOOM_CLIENT_ID, ZOOM_CLIENT_SECRET, or account-level OAuth tokens for core Probe diagnostics.
• Keep optional URLs/versioning aligned with package version to avoid JS/WASM mismatch.

Probe SDK Reference Map

Canonical Documentation

• Product docs: https://developers.zoom.us/docs/probe-sdk/
• Get started: https://developers.zoom.us/docs/probe-sdk/get-started/
• API reference: https://marketplacefront.zoom.us/sdk/probe/index.html

Core Classes

• Prober
• Reporter

Core Methods

From global/class reference surfaces:

• requestMediaDevicePermission
• requestMediaDevices
• diagnoseAudio
• diagnoseVideo
• startToDiagnose
• stopToDiagnose
• stopToDiagnoseVideo
• releaseMediaStream
• reportBasicInfo
• reportFeatures
• cleanup

Key Enums/Constants

• RENDERER_TYPE
• NETWORK_QUALITY_LEVEL
• BANDWIDTH_QUALITY_LEVEL
• PROTOCOL_TYPE
• ERR_CODE
• SUPPORTED_FEATURE_INDEX
• BASIC_INFO_ATTR_INDEX

Changelog and Package

• Changelog: https://developers.zoom.us/changelog/probe-sdk/
• npm package: https://www.npmjs.com/package/@zoom/probesdk
• sample source: https://github.com/zoom/probesdk-web

Probe SDK Sample Validation and Drift Notes

Validated sample:

• zoom/probesdk-web

Lifecycle and Architecture Patterns Confirmed

• Prober initialization followed by staged diagnostics.
• Explicit separation between targeted checks (diagnoseAudio, diagnoseVideo) and comprehensive network probe (startToDiagnose).
• Cleanup and stream lifecycle methods are critical for stable page behavior.

Contradictions and Drift Indicators

• Doc snippet drift:
• Some docs use video options key type while reference/sample prefer rendererType.
• Report shape drift:
• Docs show basicInfo/supportedFeatures whereas sample README also references basicInfoEntries/featureEntries.
• Timeout example variance:
• Docs and sample show different connectTimeout defaults in code snippets.

Recommendations

• Use adapter layer for diagnostic report fields.
• Normalize renderer options through a shared utility in your app.
• Keep browser matrix in your own QA docs and update quarterly.

Probe SDK Source Map

Crawled Docs (local raw-docs)

• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/probe-sdk/get-started.md
• tools/zoom-crawler/raw-docs/marketplacefront.zoom.us/sdk/probe/index.md
• tools/zoom-crawler/raw-docs/marketplacefront.zoom.us/sdk/probe/Prober.md
• tools/zoom-crawler/raw-docs/marketplacefront.zoom.us/sdk/probe/Reporter.md
• tools/zoom-crawler/raw-docs/marketplacefront.zoom.us/sdk/probe/global.md

External Validation Source

• zoom/probesdk-web

Probe SDK Versioning and Compatibility

Upgrade Strategy

Use the standard upgrade workflow:

• ../../general/references/sdk-upgrade-workflow.md

Compatibility Risks

• Renderer option naming drift (type vs rendererType) across docs/examples.
• Report object field naming drift (basicInfo vs basicInfoEntries, supportedFeatures vs featureEntries).
• Browser support table age vs current browser versions.
• Runtime JS/WASM URL override mismatches.

Safe Upgrade Checklist

• Pin and record current/target @zoom/probesdk version.
• Compare get-started docs, API reference, and sample repo behavior.
• Validate all renderer targets in your browser matrix.
• Validate both full diagnostic completion and early stop path.
• Validate report schema adapter and downstream consumers.
• Pin JS/WASM assets to the same Probe SDK release and prevent mixed-version loading.
• Add cache-busting strategy for JS/WASM updates (asset fingerprinting or versioned URLs).
• Confirm CDN/browser cache invalidation behavior before production rollout.

Probe SDK 5-Minute Preflight Runbook

Use this before deep debugging.

Skill Doc Standard Note

• Skill entrypoint is SKILL.md.
• This runbook is an operational convention (recommended), not a required skill file.
• API/option naming can drift by version; validate against current Probe SDK reference.

1) Confirm Integration Surface

• Confirm this is a web diagnostics use case, not meeting/session join runtime.
• Confirm whether you need only device checks, only network checks, or full diagnostics.
• Confirm renderer target strategy (video-tag or canvas-based renderer).

2) Confirm Required Inputs

• No Zoom Marketplace credentials are required for core Probe SDK diagnostics.
• Device IDs are required for explicit audio input/output and camera diagnostics.
• For comprehensive network diagnostics, verify optional JS/WASM URL override strategy.

3) Confirm Lifecycle Order

1. requestMediaDevicePermission(). 2. requestMediaDevices(). 3. diagnoseAudio(...) / diagnoseVideo(...). 4. startToDiagnose(jsUrl, wasmUrl, config, statsListener). 5. stopToDiagnose* and cleanup() on exit.

4) Confirm Event/State Handling

• Keep stream lifecycle explicit (releaseMediaStream).
• Keep stats callback lightweight and avoid blocking UI thread.
• Persist final report snapshot before cleanup.

5) Confirm Cleanup + Upgrade Posture

• Always stop active diagnostics before page unload/navigation.
• Re-check renderer option naming and report field names on upgrades.
• Re-check browser compatibility assumptions against current docs.

6) Quick Probes

• Permissions prompt appears and resolves expectedly.
• Devices list includes expected microphone/speaker/camera.
• Video diagnostic renders to selected target.
• Network diagnostic emits stats and final report.

7) Fast Decision Tree

• No media diagnostics -> permissions denied or insecure context.
• Video diagnostics fail -> renderer/target mismatch or unsupported renderer type.
• Network diagnostic incomplete -> timeout/domain/config mismatch.
• Report schema mismatch -> version drift between docs and installed package.

8) Source Checkpoints

Official docs

• https://developers.zoom.us/docs/probe-sdk/
• https://marketplacefront.zoom.us/sdk/probe/index.html

Raw docs in repo

• tools/zoom-crawler/raw-docs/developers.zoom.us/docs/probe-sdk/
• tools/zoom-crawler/raw-docs/marketplacefront.zoom.us/sdk/probe/

Probe SDK High-Level Scenarios

1) Meeting Pre-Join Readiness Gate

• Run Probe diagnostics before showing Meeting SDK join button.
• Block join for severe failures (no media permissions, fatal network score).
• Show guidance and retry path for recoverable failures.

2) Video Session Quality Predictor

• Pair Probe results with Video SDK session UX.
• Choose default video quality and renderer path based on capability checks.
• Fall back to audio-first profile when network quality is poor.

3) Support/Triage Diagnostic Capture

• Collect final diagnostic report for helpdesk workflows.
• Attach report to support ticket to reduce reproduction time.
• Compare report against known-good baseline by browser/OS cohort.

4) Managed Device Certification

• Run automated checks across approved browser/device matrix.
• Persist pass/fail score and feature support profile.
• Use certification output to guide endpoint policy and rollout.

5) Incident Response Validation

• During outage/performance alerts, run Probe tests from affected geos.
• Distinguish local device failures from Zoom/service-zone path issues.
• Route incident response based on network and protocol-specific findings.

Probe SDK Common Issues

Permissions denied or missing streams

Symptoms:

• Permission request returns error.
• No stream returned for diagnostics.

Checks:

• HTTPS/secure context is used.
• Not in insecure context (http://, mixed content, blocked iframe permissions policy).
• Browser-level camera/mic permissions are granted.
• Device is not locked by another app.

No media devices detected

Symptoms:

• requestMediaDevices returns empty sets for mic/camera/speaker.

Checks:

• OS-level privacy settings allow browser device access.
• External USB/Bluetooth devices are connected before page load.
• Virtual device drivers are installed and recognized by the browser.
• Browser enterprise policies are not blocking media device enumeration.

Video diagnostic fails to render

Symptoms:

• diagnoseVideo error or blank target.

Checks:

• Renderer option key and target match selected renderer.
• video-tag renderer uses HTMLVideoElement target.
• WebGL/WebGL2/WebGPU renderers use canvas/offscreen canvas target.

Network diagnostic never completes

Symptoms:

• startToDiagnose does not return final report in expected duration.

Checks:

• probeDuration and connectTimeout values are reasonable.
• Domain and optional JS/WASM URLs are reachable.
• Browser/network policies do not block probing paths.

Report field mismatch in app code

Symptoms:

• Undefined fields when parsing final report.

Checks:

• Add compatibility adapter for basicInfo vs basicInfoEntries.
• Add compatibility adapter for supportedFeatures vs featureEntries.
• Pin SDK version and align parser tests to that version.

Residual resource usage after diagnostics

Symptoms:

• Camera indicator remains active.
• Memory/network usage persists after leaving page.

Checks:

• Call stopToDiagnoseVideo and/or releaseMediaStream.
• Call stopToDiagnose on early exit.
• Call cleanup() on route/page teardown.