Zoom Apps SDK

Zoom クライアント内で実行される Web アプリケーションのための背景参照です。まず choose-zoom-approach を優先し、その後 Layers API、Collaborate Mode、in-client OAuth、実行時の制約に関しては、ここにルーティングします。

Zoom Apps SDK

Zoom クライアント内で実行される Web アプリケーションを構築します。ミーティング、ウェビナー、メインクライアント、Zoom Phone に対応しています。

公式ドキュメント: https://developers.zoom.us/docs/zoom-apps/ SDK リファレンス: https://appssdk.zoom.us/ NPM パッケージ: https://www.npmjs.com/package/@zoom/appssdk

クイックリンク

Zoom Apps は初めてですか？このパスに従ってください:

1. アーキテクチャ - フロントエンド/バックエンドパターン、埋め込みブラウザ、ディープリンク
2. クイックスタート - 完全に機能する Express + SDK アプリ
3. 実行コンテキスト - アプリがどこで実行されるか (inMeeting、inMainClient など)
4. Zoom Apps vs Meeting SDK - アプリの種類を混在させるのをやめましょう
5. In-Client OAuth - PKCE を使用したシームレスな認可
6. API リファレンス - 100 以上の SDK メソッド
7. 統合インデックス - このファイル内の以下のセクションを参照
8. 5分間のランブック - 深いデバッグの前のプリフライトチェック

リファレンス:

• API リファレンス - カテゴリ別のすべての SDK メソッド
• イベントリファレンス - すべての SDK イベントリスナー
• Layers API - イマーシブおよびカメラモードのレンダリング
• OAuth リファレンス - Zoom Apps の OAuth フロー
• Zoom Mail - メールプラグイン統合

問題が発生していますか？

• App won't load in Zoom → 下記の Domain Allowlist をチェック
• SDK エラー → 一般的な問題
• ローカル開発セットアップ → デバッグガイド
• バージョンアップグレード → 移行ガイド
• フォーラム由来の FAQ → フォーム上位質問

イマーシブなエクスペリエンスを構築していますか？

• Layers Immersive Mode - カスタムビデオレイアウト
• Camera Mode - 仮想カメラオーバーレイ

OAuth について質問がありますか？ 認証フロー については zoom-oauth スキルを参照してください。

SDK 概要

Zoom Apps SDK (@zoom/appssdk) は、Zoom の埋め込みブラウザで実行される Web アプリケーション向けの JavaScript API を提供しています:

• Context APIs - ミーティング、ユーザー、参加者情報の取得
• Meeting Actions - アプリの共有、参加者の招待、URL のオープン
• Authorization - PKCE を使用した In-Client OAuth (ブラウザリダイレクトなし)
• Layers API - イマーシブビデオレイアウトおよびカメラモードオーバーレイ
• Collaborate Mode - 参加者全体での共有アプリ状態
• App Communication - アプリインスタンス間のメッセージパッシング (メインクライアント <-> ミーティング)
• Media Controls - 仮想背景、カメラリスト、レコーディング制御
• UI Controls - アプリの拡大、通知、ポップアウト
• Events - ミーティング状態、参加者、共有などへの応答

前提条件

• Marketplace で "Zoom App" タイプとして構成された Zoom アプリ
• Zoom Apps スコープを持つ OAuth 認証情報 (Client ID + Secret)
• Web アプリケーション (Node.js + Express 推奨)
• Marketplace ドメイン許可リストにホワイトリストされたドメイン
• ローカル開発用の ngrok または HTTPS トンネル
• Node.js 18 以上 (バックエンドサーバー用)

クイックスタート

オプション A: NPM (フレームワークの場合は推奨)

npm install @zoom/appssdk

import zoomSdk from '@zoom/appssdk';

async function init() {
  try {
    const configResponse = await zoomSdk.config({
      capabilities: [
        'shareApp',
        'getMeetingContext',
        'getUserContext',
        'openUrl'
      ],
      version: '0.16'
    });

    console.log('Running context:', configResponse.runningContext);
    // 'inMeeting' | 'inMainClient' | 'inWebinar' | 'inImmersive' | ...

    const context = await zoomSdk.getMeetingContext();
    console.log('Meeting ID:', context.meetingID);
  } catch (error) {
    console.error('Not running inside Zoom:', error.message);
    showDemoMode();
  }
}

オプション B: CDN (バニラ JS)

<script src="https://appssdk.zoom.us/sdk.js"></script>

<script>
// 重要: "let zoomSdk" を宣言しないでください - SDK は window.zoomSdk をグローバルに定義します
// "let zoomSdk = ..." を使用すると: SyntaxError: redeclaration of non-configurable global property が発生します
let sdk = window.zoomSdk;  // 異なる変数名を使用してください

async function init() {
  try {
    const configResponse = await sdk.config({
      capabilities: ['shareApp', 'getMeetingContext', 'getUserContext'],
      version: '0.16'
    });

    console.log('Running context:', configResponse.runningContext);
  } catch (error) {
    console.error('Not running inside Zoom:', error.message);
    showDemoMode();
  }
}

function showDemoMode() {
  document.body.innerHTML = '<h1>Preview Mode</h1><p>Open this app inside Zoom to use.</p>';
}

document.addEventListener('DOMContentLoaded', () => {
  init();
  setTimeout(() => { if (!sdk) showDemoMode(); }, 3000);
});
</script>

重要: グローバル変数の競合

CDN スクリプトは window.zoomSdk をグローバルに定義します。これを再宣言しないでください:

// 誤り - Zoom の埋め込みブラウザで SyntaxError が発生します
let zoomSdk = null;
zoomSdk = window.zoomSdk;

// 正し - 異なる変数名を使用
let sdk = window.zoomSdk;

// 同様に正し - NPM インポート (競合なし)
import zoomSdk from '@zoom/appssdk';

これは CDN アプローチにのみ適用されます。NPM インポートはモジュール スコープの変数を作成し、競合はありません。

ブラウザプレビュー / デモモード

SDK は Zoom クライアント内でのみ機能します。通常のブラウザでアクセスされた場合:

• window.zoomSdk は存在しますが、sdk.config() はエラーをスロー します
• 常にフォールバック UI で try/catch を実装する
• SDK がハングする可能性がある場合はタイムアウト (3 秒) を追加

URL ホワイトリスト (必須)

ドメインがホワイトリストされていない限り、アプリは Zoom に読み込まれません。

1. Zoom Marketplace に移動
2. アプリを開く -> 機能 タブ
3. Zoom App の下で Add Allow List を探す
4. ドメインを追加します (例: 本番環境では yourdomain.com、開発環境では xxxxx.ngrok.io)

これなしでは、Zoom クライアントはエラーメッセージなしで空白のパネルを表示します。

OAuth スコープ (必須)

機能には、Marketplace で有効になっている一致する OAuth スコープが必要です:

Capability	必須スコープ
getMeetingContext	zoomapp:inmeeting
getUserContext	zoomapp:inmeeting
shareApp	zoomapp:inmeeting
openUrl	zoomapp:inmeeting
sendAppInvitation	zoomapp:inmeeting
runRenderingContext	zoomapp:inmeeting
authorize	zoomapp:inmeeting
getMeetingParticipants	zoomapp:inmeeting

スコープを追加するには: Marketplace -> アプリ -> Scopes タブ -> 必要なスコープを追加します。

スコープがないと、機能は自動的に失敗するか、エラーをスロー します。新しいスコープを追加する場合、ユーザーは再認可する必要があります。

実行コンテキスト

アプリは Zoom 内のさまざまなサーフェスで実行されます。configResponse.runningContext はどこにあるかを示します:

Context	Surface	説明
inMeeting	ミーティングサイドバー	最も一般的。完全なミーティング API が利用可能
inMainClient	メインクライアントパネル	ホームタブ。ミーティングコンテキスト API なし
inWebinar	ウェビナーサイドバー	ホスト/パネリスト。ミーティング + ウェビナー API
inImmersive	Layers API	フルスクリーンカスタムレンダリング
inCamera	カメラモード	仮想カメラオーバーレイ
inCollaborate	Collaborate モード	共有状態コンテキスト
inPhone	Zoom Phone	電話呼び出しアプリ
inChat	Team Chat	チャットサイドバー

詳細については、実行コンテキスト を参照してください。

SDK 初期化パターン

すべての Zoom App は config() で始まります:

import zoomSdk from '@zoom/appssdk';

const configResponse = await zoomSdk.config({
  capabilities: [
    // 使用するすべての API をリストします
    'getMeetingContext',
    'getUserContext',
    'shareApp',
    'openUrl',
    'authorize',
    'onAuthorized'
  ],
  version: '0.16'
});

// configResponse contains:
// {
//   runningContext: 'inMeeting',
//   clientVersion: '5.x.x',
//   unsupportedApis: []  // このクライアント バージョンでサポートされていない API
// }

ルール:

1. config() は他の SDK メソッドより前に呼び出す必要があります
2. config() にリストされている機能のみが利用可能
3. 機能は Marketplace の OAuth スコープと一致する必要があります
4. グレースフルデグラデーションのため unsupportedApis をチェック

In-Client OAuth (概要)

認可に最適なUX - ブラウザリダイレクトなし:

// 1. バックエンドからコードチャレンジを取得
const { codeChallenge, state } = await fetch('/api/auth/challenge').then(r => r.json());

// 2. In-Client 認可をトリガー
await zoomSdk.authorize({ codeChallenge, state });

// 3. 認可結果をリッスン
zoomSdk.addEventListener('onAuthorized', async (event) => {
  const { code, state } = event;
  // 4. トークン交換のためにコードをバックエンドに送信
  await fetch('/api/auth/token', {
    method: 'POST',
    body: JSON.stringify({ code, state })
  });
});

完全な実装については、In-Client OAuth ガイド を参照してください。

Layers API (概要)

イマーシブなビデオレイアウトとカメラオーバーレイを構築:

// イマーシブモードを開始 - ギャラリービューを置き換え
await zoomSdk.runRenderingContext({ view: 'immersive' });

// 参加者ビデオフィードを配置
await zoomSdk.drawParticipant({
  participantUUID: 'user-uuid',
  x: 0, y: 0, width: 640, height: 480, zIndex: 1
});

// オーバーレイ画像を追加
await zoomSdk.drawImage({
  imageData: canvas.toDataURL(),
  x: 0, y: 0, width: 1280, height: 720, zIndex: 0
});

// イマーシブモードを終了
await zoomSdk.closeRenderingContext();

Layers Immersive および Camera Mode を参照してください。

環境変数

変数	説明	参照先
ZOOM_APP_CLIENT_ID	アプリクライアント ID	Marketplace -> アプリ -> アプリ認証情報
ZOOM_APP_CLIENT_SECRET	アプリクライアントシークレット	Marketplace -> アプリ -> アプリ認証情報
ZOOM_APP_REDIRECT_URI	OAuth リダイレクト URL	サーバー URL + /auth
SESSION_SECRET	クッキー署名シークレット	ランダム文字列を生成
ZOOM_HOST	Zoom ホスト URL	https://zoom.us (または https://zoomgov.com)

一般的な API

API	説明
config()	SDK を初期化し、機能をリクエスト
getMeetingContext()	ミーティング ID、トピック、ステータスを取得
getUserContext()	ユーザー名、ロール、参加者 ID を取得
getRunningContext()	現在の実行コンテキストを取得
getMeetingParticipants()	参加者をリスト表示
shareApp()	参加者とアプリ画面を共有
openUrl({ url })	外部ブラウザで URL をオープン
sendAppInvitation()	ユーザーをアプリを開くように招待
authorize()	In-Client OAuth をトリガー
connect()	他のアプリインスタンスに接続
postMessage()	接続されているインスタンスにメッセージを送信
runRenderingContext()	Layers API を開始 (イマーシブ/カメラ)
expandApp({ action })	アプリパネルを展開/折りたたみ
showNotification()	Zoom に通知を表示

完全なドキュメントライブラリ

コアコンセプト

• アーキテクチャ - フロントエンド/バックエンドパターン、埋め込みブラウザ、ディープリンク、X-Zoom-App-Context
• 実行コンテキスト - すべてのコンテキスト、コンテキスト固有の API、マルチインスタンス通信
• セキュリティ - OWASP ヘッダー、CSP、クッキーセキュリティ、PKCE、トークンストレージ

完全な例

• クイックスタート - Hello World Express + SDK アプリ
• In-Client OAuth - PKCE 認可フロー
• Layers Immersive - カスタムビデオレイアウト
• Camera Mode - 仮想カメラオーバーレイ
• Collaborate Mode - 参加者全体での共有状態
• Guest Mode - 未認可/認可/許可状態
• Breakout Rooms - ルーム検出とクロスルーム状態
• App Communication - インスタンス間の connect + postMessage

トラブルシューティング

• 一般的な問題 - クイック診断とエラーコード
• デバッグ - ローカル開発、ngrok、ブラウザプレビュー
• 移行 - SDK バージョンアップグレード注釈

リファレンス

• API リファレンス - すべての 100 以上の SDK メソッド
• イベントリファレンス - すべての SDK イベントリスナー
• Layers API リファレンス - 描画およびレンダリングメソッド
• OAuth リファレンス - Zoom Apps の OAuth フロー
• Zoom Mail - メールプラグイン統合

サンプルリポジトリ

公式 (Zoom 製)

リポジトリ	タイプ	最終更新	ステータス	SDK バージョン
zoomapps-sample-js	Hello World (Vanilla JS)	Dec 2025	Active	^0.16.26
zoomapps-advancedsample-react	Advanced (React + Redis)	Oct 2025	Active	0.16.0
zoomapps-customlayout-js	Layers API	Nov 2023	Stale	^0.16.8
zoomapps-texteditor-vuejs	Collaborate (Vue + Y.js)	Oct 2023	Stale	^0.16.7
zoomapps-serverless-vuejs	Serverless (Firebase)	Aug 2024	Stale	^0.16.21
zoomapps-cameramode-vuejs	Camera Mode	-	-	-
zoomapps-workshop-sample	Workshop	-	-	-

新規プロジェクト推奨: @zoom/appssdk バージョン ^0.16.26 を使用してください。

コミュニティ

タイプ	リポジトリ	説明
Library	harvard-edtech/zaccl	Zoom App Complete Connection Library

完全なリスト: general/references/community-repos.md を参照

学習パス

1. 開始: zoomapps-sample-js - 最もシンプルで最も最新
2. 高度: zoomapps-advancedsample-react - 包括的 (In-Client OAuth、Guest Mode、Collaborate)
3. 特別: 機能に基づいて選択 (Layers、Serverless、Camera Mode)

重大な落とし穴 (実際の開発から)

1. グローバル変数の競合

CDN スクリプトは window.zoomSdk を定義します。コード内で let zoomSdk を宣言すると、SyntaxError: redeclaration of non-configurable global property が発生します。let sdk = window.zoomSdk を使用するか、NPM インポートを使用してください。

2. ドメイン許可リスト

アプリ URL は Marketplace ドメイン許可リストに含まれている必要があります。ない場合、Zoom はエラーなしで空白のパネルを表示します。appssdk.zoom.us および使用する任意の CDN ドメインも追加してください。

3. 機能はリストされている必要があります

config({ capabilities: [...] }) にリストされている API のみが利用可能です。リストされていない API を呼び出すと、エラーがスロー されます。これはイベントリスナーにも当てはまります。

4. SDK は Zoom の内側でのみ機能します

zoomSdk.config() は Zoom クライアントの外でエラーをスロー します。常にブラウザフォールバックで try/catch にラップしてください:

try { await zoomSdk.config({...}); } catch { showBrowserPreview(); }

5. ngrok URL の変更

無料の ngrok URL は再起動時に変更されます。Marketplace で 4 か所を更新する必要があります: Home URL、Redirect URL、OAuth Allow List、Domain Allow List。安定したサブドメイン用に ngrok 有料プランを検討してください。

6. In-Client OAuth vs Web OAuth

UX が最適な場合は zoomSdk.authorize() (In-Client) を使用してください - ブラウザリダイレクトなし。Web リダイレクトには、Marketplace からの初期インストールにのみフォールバックしてください。

7. カメラモード CEF レース条件

カメラモードは CEF を使用し、初期化に時間がかかります。drawImage/drawWebView は呼び出しが早い場合、失敗する可能性があります。指数バックオフで再試行を実装してください。

8. クッキー構成

Zoom の埋め込みブラウザでは、SameSite=None および Secure=true を持つクッキーが必要です。これなしでは、セッションは自動的に破損します。

9. 状態検証

CSRF 攻撃を防ぐために、常に OAuth state パラメーターを検証してください。暗号化的にランダムな状態を生成し、保存し、コールバックで検証してください。

リソース

• 公式ドキュメント: https://developers.zoom.us/docs/zoom-apps/
• SDK リファレンス: https://appssdk.zoom.us/
• NPM パッケージ: https://www.npmjs.com/package/@zoom/appssdk
• 開発者フォーラム: https://devforum.zoom.us/
• GitHub SDK ソース: https://github.com/zoom/appssdk

---

ヘルプが必要ですか？ 完全なナビゲーションについて、以下の統合インデックスセクションを開始してください。

---

統合インデックス

このセクションは SKILL.md から移行されました。

クイックスタートパス

Zoom Apps が初めての場合は、この順序に従ってください:

1. まずプリフライトチェックを実行 -> RUNBOOK.md

2. アーキテクチャを読む -> concepts/architecture.md

   • フロントエンド/バックエンドパターン、埋め込みブラウザ、ディープリンク
   • Zoom がアプリをロードし、通信する方法を理解する

3. 最初のアプリを構築 -> examples/quick-start.md

   • 完全な Express + SDK Hello World
   • ローカル開発用の ngrok セットアップ

4. 実行コンテキストを理解 -> concepts/running-contexts.md

   • アプリがどこで実行されるか (inMeeting、inMainClient、inWebinar など)
   • コンテキスト固有の API と制限

5. OAuth を実装 -> examples/in-client-oauth.md

   • PKCE を使用した In-Client OAuth (最適なUX)
   • トークン交換とストレージ

6. 機能を追加 -> references/apis.md

   • カテゴリ別に整理された 100 以上の SDK メソッド
   • 各メソッドのコード例

7. トラブルシューティング -> troubleshooting/common-issues.md

   • 一般的な問題のクイック診断

---

ドキュメント構造

zoom-apps-sdk/
├── SKILL.md                           # メインスキル概要
├── SKILL.md                           # このファイル - ナビゲーションガイド
│
├── concepts/                          # コアアーキテクチャパターン
│   ├── architecture.md               # フロントエンド/バックエンド、埋め込みブラウザ、OAuth フロー
│   ├── running-contexts.md           # アプリがどこで実行されるか + コンテキスト固有の API
│   └── security.md                   # OWASP ヘッダー、CSP、データアクセスレイヤー
│
├── examples/                          # 完全な動作コード
│   ├── quick-start.md                # Hello World - 最小限の Express + SDK アプリ
│   ├── in-client-oauth.md            # PKCE を使用した In-Client OAuth
│   ├── layers-immersive.md           # Layers API - イマーシブモード (カスタムレイアウト)
│   ├── layers-camera.md              # Layers API - カメラモード (仮想カメラ)
│   ├── collaborate-mode.md           # Collaborate モード (共有状態)
│   ├── guest-mode.md                 # Guest モード (未認可 -> 許可)
│   ├── breakout-rooms.md             # Breakout ルーム統合
│   └── app-communication.md          # インスタンス間の connect + postMessage
│
├── troubleshooting/                   # 問題解決ガイド
│   ├── common-issues.md              # クイック診断、エラーコード
│   ├── debugging.md                  # ローカル開発セットアップ、ngrok、ブラウザプレビュー
│   └── migration.md                  # SDK バージョン移行注釈
│
└── references/                        # リファレンスドキュメント
    ├── apis.md                        # 完全な API リファレンス (100 以上のメソッド)
    ├── events.md                      # すべての SDK イベント
    ├── layers-api.md                  # Layers API 詳細リファレンス
    ├── oauth.md                       # Zoom Apps の OAuth フロー
    └── zmail-sdk.md                   # Zoom Mail 統合

---

ユースケース別

基本的な Zoom App を構築したい

1. アーキテクチャ - パターンを理解
2. クイックスタート - Hello World を構築
3. In-Client OAuth - 認可を追加
4. セキュリティ - 必須ヘッダー

イマーシブなビデオレイアウト (Layers API) が必要

1. Layers Immersive - カスタムビデオ位置
2. Layers API リファレンス - すべての描画メソッド
3. App Communication - 参加者間でレイアウトを同期

仮想カメラオーバーレイが必要

1. カメラモード - カメラモードレンダリング
2. Layers API リファレンス - 描画メソッド

リアルタイムコラボレーションが必要

1. Collaborate Mode - 共有状態 API
2. App Communication - インスタンスメッセージング

ゲスト/匿名アクセスが必要

1. Guest Mode - 3 つの認可状態
2. In-Client OAuth - promptAuthorize フロー

Breakout ルームサポートが必要

1. Breakout Rooms - ルーム検出と状態同期

メインクライアントとミーティング間で同期したい

1. App Communication - connect + postMessage
2. 実行コンテキスト - マルチインスタンス動作

サーバーレスデプロイメントが必要

1. クイックスタート - 基本パターンを理解
2. サンプル: zoomapps-serverless-vuejs - Firebase パターン

Zoom Mail 統合を追加したい

1. Zoom Mail リファレンス - REST API + メールプラグイン

エラーが発生している

1. 一般的な問題 - クイック診断テーブル
2. デバッグ - ローカル開発セットアップ、DevTools
3. 移行 - バージョン互換性

---

最も重要なドキュメント

1. アーキテクチャ (基礎)

concepts/architecture.md

Zoom Apps がどのように機能するかを理解してください: 埋め込みブラウザ内のフロントエンド、OAuth/API 用のバックエンド、SDK はブリッジ。これなしでは、他に何も意味がありません。

2. クイックスタート (最初のアプリ)

examples/quick-start.md

完全に機能するコード。高度な機能に飛び込む前に何か実行を取得します。

3. 一般的な問題 (最も一般的な問題)

troubleshooting/common-issues.md

Zoom Apps の問題の 90%: ドメイン許可リスト、グローバル変数の競合、または欠落している機能。

---

重要な学習

重大な発見:

1. グローバル変数の競合は #1 の落とし穴

   • CDN スクリプトは window.zoomSdk をグローバルに定義
   • let zoomSdk = ... は Zoom のブラウザで SyntaxError を発生させます
   • let sdk = window.zoomSdk を使用するか、NPM インポートを使用

2. ドメイン許可リストは妥協できません

   • ドメインがホワイトリストされていない場合、アプリは空白のパネルを表示し、エラーはゼロ
   • ドメイン AND appssdk.zoom.us AND 任意の CDN ドメインを含める必要があります
   • ngrok URL は再起動時に変更されます - 毎回 Marketplace を更新する必要があります

3. config() はすべてをゲート

   • 最初に呼び出す必要があり、すべての機能をリストする必要があります
   • リストされていない機能はエラーをスロー します
   • クライアント バージョン互換性のために unsupportedApis をチェック

4. In-Client OAuth > Web OAuth for UX

   • authorize() はユーザーを Zoom に保ちます (ブラウザリダイレクトなし)
   • Web リダイレクトは Marketplace からの初期インストールにのみ必要
   • 常に PKCE を実装 (code_verifier + code_challenge)

5. 2 つのアプリインスタンスが同時に実行される可能性があります

   • メインクライアントインスタンス + ミーティングインスタンス
   • connect() + postMessage() を使用して、それらの間で同期
   • ミーティング前のセットアップをメインクライアントで、ミーティングで使用

6. カメラモードには CEF の特性があります

   • CEF 初期化には時間がかかります
   • 描画呼び出しが早い場合は失敗する可能性があります
   • 指数バックオフを使用して再試行を実装

7. クッキー設定は重要

   • SameSite=None + Secure=true が必要
   • これなしでは、セッションは埋め込みブラウザで自動的に失敗します

---

クイックリファレンス

"App shows blank panel"

-> Domain Allowlist - ドメインを Marketplace に追加

"SyntaxError: redeclaration"

-> Global Variable - let sdk = window.zoomSdk を使用

"config() throws error"

-> Browser Preview - SDK は Zoom 内でのみ機能

"API call fails silently"

-> OAuth Scopes - Marketplace で必須スコープを追加

"How do I implement [feature]?"

-> API リファレンス - メソッドを見つけ、必要な機能をチェック

"How do I test locally?"

-> デバッグガイド - ngrok + Marketplace 設定

---

ドキュメントバージョン

ベース: @zoom/appssdk v0.16.x (最新: 0.16.26+)

---

コーディング楽しんでください!

アーキテクチャ で パターンを理解してから、クイックスタート で最初のアプリを構築します。