FAQ

RealtimeKit API を使うには、Cloudflare アカウント ↗ が必要です。

API トークンを作成する の手順に従い、Cloudflare ダッシュボード ↗ でトークンを作成します。権限を設定するときは、Realtime > Realtime Admin を選びます。用途に応じて、追加の アクセスポリシーと制限 も設定します。

Cloudflare API トークンは、Cloudflare API へのリクエストを認証します。これらのトークンはバックエンドでのみ使ってください。API トークンをフロントエンドへ露出したり、エンドユーザーと共有したりしないでください。

バックエンドは、Add Participant API エンドポイントでユーザーをミーティングの参加者として追加し、認証トークンを発行します。API レスポンスには、その参加者の token フィールドが含まれます。

このトークンを、対象の参加者向けにフロントエンドへ送れます。トークンはその参加者とミーティングに結び付いています。ほかのミーティングへのアクセスは付与しません。

以前のトークンが期限切れになったあとに新しいトークンが必要な場合は、Refresh Participant Token エンドポイントを使います。詳細は 参加者トークン を参照してください。

認証トークンは JSON Web Token（JWT）で、有効期間は 100 日です。meetingId と participantId フィールドを含み、特定のミーティングの特定の参加者にトークンを結び付けます。トークンはほかのミーティングへのアクセスを付与しません。以前のトークンが期限切れになったあとに新しいトークンが必要な場合は、Refresh Participant Token エンドポイントを使います。詳細は 参加者トークン を参照してください。

できます。Refresh Participant Token エンドポイントは、現在のトークンが期限切れになる前に呼び出せます。認証トークンを更新すると、既存トークンを無効化せずに新しいトークンが発行されます。各トークンは有効なまま残り、それぞれの有効期限で独立して期限切れになります。

できません。認証トークン API は、カスタムの開始日や有効期限をサポートしていません。Add Participant または Refresh Participant Token の流れで作成したトークンは、発行時点から有効になり、100 日後に期限切れになります。

予定されたアクセスが必要な場合は、自前のシステムで時間ベースのアクセス制御を実装してください。RealtimeKit SDK は、スケジュールや期間のロジックを管理しません。

なりません。更新フローを含む新しいトークンの発行では、既存トークンは無効になりません。各トークンは有効なまま残り、それぞれの有効期限で独立して期限切れになります。

取り消されます。Delete Participant エンドポイントは、そのミーティングでその参加者に発行したすべてのトークンをただちに取り消します。

参加者を削除する前に、Kick Participants エンドポイントで、アクティブなセッションから参加者を安全に退出させてください。そのあと参加者を削除して、トークンを取り消します。

その参加者はミーティングに参加できません。RealtimeKit の UI と Core SDK は、トークンが無効であると報告します。

RealtimeKit は、参加者がミーティングステージに入る前に拒否するため、課金対象にはなりません。

できません。ミーティングのステータスが INACTIVE の場合、認証トークンが有効で期限切れ前でも、参加者は参加できません。

しません。RealtimeKit SDK は、参加者の認証トークンをキャッシュしたり、ブラウザーやデバイスのストレージに保存したりしません。

RealtimeKit 自体に組み込みの予約システムはありませんが、アプリケーション側で予約体験を実装できます。 RealtimeKit のミーティングには開始時刻も終了時刻もないため、スケジュールの保存と、参加を許可するタイミングの強制はバックエンドが行います。 一般的な手順は次のとおりです。

• ユーザーがミーティングを予約したら、バックエンドは RealtimeKit でミーティングを作成し、ミーティングの id と開始・終了時刻を保存します。
• ユーザーがアプリケーションでミーティングに参加しようとしたら、バックエンドは現在時刻が許可された時間枠内かを確認します。
• 確認が通ったら、バックエンドは 参加者を追加し、 参加者の認証トークンをフロントエンドへ返します。フロントエンドはそのトークンを RealtimeKit SDK へ渡し、ユーザーが参加できるようにします。

指定した時刻に、ミーティングにアクティブなセッションがある場合は、まず Kick All Participants エンドポイントを呼び出します。これにより全参加者を退出し、セッションを適切に終了します。

次に Update Meeting エンドポイントを呼び出し、ミーティングのステータスを INACTIVE に設定します。これにより参加者がミーティングに入れなくなり、新しいセッションも開始できなくなります。

curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/realtime/kit/{APP_ID}/meetings/{MEETING_ID} \
--request PATCH \
--header "Authorization: Bearer <CLOUDFLARE_API_TOKEN>" \
--header "Content-Type: application/json" \
--data '{ "status": "INACTIVE" }'

できます。同じミーティングに別のデバイスやタブから参加すると、1 人の参加者が複数のピアとして表されます。各接続は別々のピアになりますが、いずれも同じ参加者に対応します。

Delete Participant API エンドポイントで、そのミーティングの該当ユーザーの参加者を削除します。参加者を削除し、新しいトークンの発行を止めると、そのミーティングには参加できなくなります。

できます。そのミーティングに参加者が存在し、有効な認証トークンを持っていれば、時間を置いて同じミーティングの複数のライブセッションに参加できます。

ほとんどの場合、必要ありません。通常は、特定のユーザーとミーティングに対して参加者を一度作成し、そのミーティングのセッション間で再利用します。時間の経過とともに参加者の認証トークンを更新する必要はありますが、参加者を作り直す必要はありません。

自前のシステムの安定した内部識別子（数値のユーザー ID や UUID など）を使います。メールアドレス、電話番号、その他の個人を特定できる情報などの個人データは使わないでください。

Preset は、App レベルで定義する再利用可能なルールと設定の集まりです。同じ Preset を複数の参加者に使えます。

Preset の詳細は こちら を参照してください。

RealtimeKit は、Web とモバイルの主要なフレームワークをサポートしています。

ほとんどの用途では、UI Kit の利用をおすすめします。

注意: UI Kit を使うと Core SDK も一緒に利用でき、必要に応じて追加機能を構築できます。

詳細は SDK を選ぶ を参照してください。

RealtimeKit の初期化時に、カメラ画質のメディア設定を指定できます。

詳細はメディア設定の こちら を参照してください。

カメラ画質を上げると帯域使用量が増え、エンドユーザーの端末が複数ピアからの 1080p を扱えない場合、低スペック端末ではミーティング性能に影響することがあります。

RealtimeKit の初期化時に、カメラのメディア設定を指定できます。

詳細はメディア設定の こちら を参照してください。

映像のフレームレートを上げると帯域使用量が増え、エンドユーザー端末の帯域に問題がある場合、ミーティング内の他ピアの映像品質に影響することがあります。グループ通話では、映像のフレームレートを低い値（例: <= 30）にしてください。現在のデフォルトは、simulcast レイヤーに応じて 24/30 FPS です。

RealtimeKit SDK は、マイクを自動選択してできるだけよい体験を提供しようとします。有線デバイスより Bluetooth デバイスを優先します。ただし、RealtimeKit のミーティング参加前にすでに接続されており、ラベルに bluetooth、headset、earphone が含まれないデバイスは、見逃されることがあります。

ラベルが bluetooth、headset、earphone、microphone のマイクと、usb や wired などのラベルを持つ USB デバイスの自動選択をサポートしています。AirPods や Airdopes など、よく使われる一部のデバイスもサポートしています。仮想デバイスは自動選択しません。

自動選択に失敗した場合、エンドユーザーはミーティングの Settings ボタンからマイクを手動で選べます。SDK はその選択を以降のセッションでも覚えます。よく使われるデバイスで自動選択の対象になっていないと思われる場合は、サポートへ連絡して、優先的な自動選択対応を依頼してください。

RealtimeKit の初期化時に、画面共有のメディア設定を指定できます。

詳細はメディア設定の こちら を参照してください。

画面共有のフレームレートを上げると帯域使用量が増え、エンドユーザー端末の帯域に問題がある場合、ミーティング内の他ピアの映像品質に影響することがあります。グループ通話では、画面共有のフレームレートを低い値（例: <= 30）にしてください。ほとんどの用途では、画面共有にはデフォルトの 5 FPS で十分です。

原因は複数考えられます。

まず デモアプリ ↗ でサンプルミーティングを試してください。デモアプリでもメッセージを送れない場合は、サポートへ連絡してください。デモアプリで送れる場合は、連携側の問題です。

連携の切り分けでは、まずユーザーがミーティングへ正常に参加できたかを確認します。ユーザーがミーティングへ 参加 できている場合は、ユーザーの Preset にメッセージ送信の権限があるかを確認します。カスタム UI を使っている場合は、Core SDK を疑う前に、コアの チャット API が動作するかを確認します。

それでも解決しない場合は、フレームワークが UI をブロックしていないかを確認します。Material UI などのフレームワークは、Drawer コンポーネントのフォーカストラップで入力フォーカスを妨げることがあります。フォーカストラップを無効にするプロパティがあることが多く、Material UI ではこの目的で disableEnforceFocus プロパティがあります。

それでもメッセージを送れない場合は、サポートへ連絡してください。

Start Recording API で透かし画像の URL を渡すと、レコーダーは Cloudflare コンテナ内で動くブラウザーでその画像を読み込みます。画像が壊れて見える場合は、次を確認してください。

• CORS ヘッダー: 画像 URL は、HTTP レスポンスで適切な CORS ヘッダー（例: Access-Control-Allow-Origin: *）を返す必要があります。これらのヘッダーがないと、ブラウザーは画像の読み込みをブロックします。
• 画像への直接 URL: URL は画像ファイル自体を指す必要があります（例: https://example.com/logo.png）。画像を埋め込んだ HTML ページを指してはいけません。
• リダイレクトなし: URL は別の場所へリダイレクトしてはいけません。レコーダーは URL をそのまま取得するため、リダイレクトがあると画像の読み込みに失敗することがあります。

ネットワークが送信トラフィックを制限している場合は、RealtimeKit 連携に必要なドメインとポートについて ネットワーク許可リスト を参照してください。

test.realtime.cloudflare.com ↗ を開き、通話前テストを実行します。テストはカメラ、マイク、ネットワークを確認し、Cloudflare Realtime エンドポイントへの接続も検証します。ミーティング参加前に、必要なサービスがネットワークやファイアウォールでブロックされていないことを確認できます。必要なドメインとポートは ネットワーク許可リスト を参照してください。

認証トークンを URL パラメーターで渡す場合でも、Cloudflare がホストするデモアプリやサンプルを自分のサイトに iframe として埋め込むことは、強くおすすめしません。

代わりに、UI Kit のセットアップガイド に従って自分のサイトでデフォルトのミーティング UI を構築するか、RealtimeKit web examples ↗ を自分のドメインでデプロイしてください。どちらの作業量も小さく、次の大きな利点があります。

• 制御: ユーザー体験、構成、インターフェイスを自分で完全に管理できます。
• 安定性: 実装が急に変わらず、突然の障害からプロダクトを守れます。
• 信頼性: いつ、どのようにアップグレードするかを自分で決められ、ユーザーへ安定した体験を提供できます。

デモアプリとサンプルアプリケーションは、予告なくいつでも更新されることがあります。

RealtimeKit は、アクティブな参加者の利用時間を課金します。課金は参加者がミーティングセッションに参加したときに始まり、退出したときに止まります。

主な課金ルール:

• 不参加者は課金されません: Add Participant API で追加しただけでは課金されません。その参加者がミーティングに一度も参加しなければ、RealtimeKit は課金しません。
• 利用時間で課金されます: RealtimeKit は、参加者がアクティブなセッションにいた正確な時間（秒を含む）を課金します。音声や映像を送受信していなくても、参加者は課金対象です。
• 複数タブは別々に課金されます: 同じ認証トークンで複数のブラウザーのタブから参加した場合、RealtimeKit はタブごとに課金します。RealtimeKit ダッシュボードには、その参加者の合算時間が表示されます。

ミーティングとセッションの違いの詳細は RealtimeKit の概念 を参照してください。

例:

• 2 人の参加者が午後 7:00 に参加し、午後 7:30 に退出した場合、各参加者は 30 分使います。RealtimeKit は 60 参加者分を課金します。
• 1 人が午後 4:00 に参加し、もう 1 人が午後 4:03 に参加し、両者が午後 5:00 に退出した場合、利用時間は 60 分と 57 分です。RealtimeKit は 117 参加者分を課金します。
• 1 人が午後 3:00 に参加して午後 3:27 に退出し、もう 1 人が午後 3:05 に参加して午後 3:30 に退出した場合、利用時間は 27 分と 25 分です。RealtimeKit は 52 参加者分を課金します。
• 5 人の参加を見込んでいても実際に参加したのが 2 人なら、RealtimeKit は参加した 2 人分の参加者分だけを課金します。
• 事前作成したミーティングに午後 2:00 の参加を見込んでいても、どちらも参加しなければ、RealtimeKit は参加者分を課金しません。

ミーティングと参加者トークンの作成だけでは課金されません。

合成録画では、レコーダーが非表示の仮想参加者としてミーティングに参加し、そのビューを録画します。詳細は 録画ガイド を参照してください。

最後の参加者が退出したあと、レコーダーはミーティングの session_keep_alive_time_in_secs のあいだ動き続けます。デフォルトは 60 秒、最大は 600 秒です。

RealtimeKit はレコーダーの参加者分を課金しません。代わりに、録画時間に対するエクスポート分を課金します。現行料金は RealtimeKit の料金 を参照してください。

record_on_start が true の場合:

• 2 人の参加者が午後 7:00 に参加し、午後 7:30 に退出すると、録画は午後 7:00 に始まります。両者が退出したあと、レコーダーはデフォルトの 60 秒のセッション keep-alive 期間のあいだ動き続けます。録画は午後 7:31 に止まるため、RealtimeKit は 31 エクスポート分を課金します。
• 5 人の参加を見込んでいても、実際に午後 8:00 に参加して午後 8:20 に退出したのが 2 人なら、デフォルトのセッション keep-alive 期間を含め録画は午後 8:21 まで続きます。RealtimeKit は 21 エクスポート分を課金します。5 人全員が同じ時刻に参加・退出しても、参加者数は録画のエクスポート分に影響しないため、課金は 21 エクスポート分のままです。
• 事前作成したミーティングに誰も参加しなければ、録画は始まりません。record_on_start を true にしてミーティングを作成しただけでは課金されません。

アクティブなセッション中に誰かが録画を開始した場合:

• 録画が午後 4:20 に始まり、最後の参加者が午後 5:00 に退出すると、デフォルトでは午後 5:01 に止まります。RealtimeKit は 41 エクスポート分を課金します。
• 録画が午後 4:20 に始まり、午後 5:00 に誰かが kickAll() を呼ぶと、録画はただちに止まります。RealtimeKit は 40 エクスポート分を課金します。
• ミーティングと録画が午後 4:20 に始まり、ミーティングの keep-alive 期間が 2 分で、全参加者が午後 5:00 にタブを閉じると、録画は午後 5:02 に止まります。RealtimeKit は 42 エクスポート分を課金します。

この keep-alive 期間は、短い切断のあいだ同じ録画を維持する必要があるワークフローに役立ちます。たとえば教育技術（EdTech）アプリケーションが、1 人参加のミーティングで時間制限のある自宅課題を録画する場合です。参加者がネットワーク接続を失い、keep-alive 期間が切れる前に再参加すれば、レコーダーは同じ録画を続けます。切断中は空の隙間が残りますが、アプリケーションは 2 本の録画を結合する必要がありません。

エクスポート課金には keep-alive 期間が含まれます。この余分な時間を避けるには、kickAll() または Kick all participants API を呼び出して、セッションを明示的に終了してください。