1. トークン認証まわりの「あるある」ミス
トライアルを始めたばかりの段階で最も多いトラブルが、トークン（認証）に関する不整合です。
よくあるパターン
・トークン生成時とjoin時のUIDが一致していない
トークンを生成する際に指定したUIDと、チャンネルにjoinする際に渡すUIDが異なると、認証エラーになります。特にテスト中にUIDを何度か変更していると見落としがちです。
・トークンなしで検証→本番移行時に接続できなくなる
Agoraコンソールでトークンを「必須としない」設定のまま開発を進め、本番環境でトークンを必須化すると、トークンを発行する仕組みがアプリ側に実装されていないため接続できない、というケースがあります。検証段階からトークン必須の設定で開発することをお勧めします。
・RESTful APIをクライアント端末から直接呼んでいる
RESTful APIはサーバーサイドから呼ぶ前提で設計されています。クライアント端末から直接叩こうとすると、認証情報の露出リスクに加え、想定通りに動作しない場合があります。
・環境別のApp ID・App Certificateの紐付けミス
トークンの生成にはUser IDやChannel名だけでなく、環境固有のApp IDとApp Certificateも必要です。検証環境と本番環境でトークン必須の運用をしている場合、それぞれの環境に対応するApp ID・App Certificateを正しく紐付けたトークン発行の仕組みを用意する必要があります。環境を切り替えた際に証明書の差し替えを忘れると、認証エラーの原因になります。
対処法
トークン生成のロジックは、早い段階でサーバーサイドに実装しておくのが安全です。公式ドキュメントのVideo Calling Use tokens | Agora Docsで認証フローの全体像を把握してから着手すると、手戻りを減らせます。
2. Agoraコンソールの設定漏れ
コードは正しいのに機能が動かない場合、Agoraコンソール側の設定が原因であることが少なくありません。
・使いたい機能が有効化されていない
クラウドレコーディングなど一部の機能は、Agoraコンソール上で事前に有効化する必要があります。有効化されていない状態でAPIを呼ぶとエラーになります。「コードは合っているはず」と悩む前に、コンソールの設定画面を確認してみてください。
対処法
利用する機能の公式ドキュメントには「Prerequisites（前提条件）」が記載されています。実装に入る前にこのセクションを確認し、コンソール側の設定を済ませておくと手戻りを防げます。
3. デバイス権限まわりの落とし穴
カメラやマイクのパーミッションが適切に設定されていないと、映像・音声が取得できません。特に注意が必要なのは以下のケースです。
- Android：OSバージョンによってBluetoothパーミッション（MODIFY_AUDIO_SETTINGS等）が細分化されており、古い実装のままだと音声デバイスを検知できないことがある
- バックグラウンド動作：アプリがバックグラウンドに移行した際、OSがカメラ・マイクへのアクセスを停止する挙動がある
- ブラウザ：HTTPSでないとカメラ・マイクの権限が取得できない（localhost以外）
対処法
利用するプラットフォームのリリースノートにあるKnown Issuesに目を通しておくと、環境固有の問題をあらかじめ把握できます。既知の問題で半日悩むのはもったいないので、最初に読んでおくことをお勧めします。
4. サンプルコードから本番実装に進む際の落とし穴
サンプルコードが動いた後、自社サービスに組み込む段階で新たなつまずきが出てきます。
Audio ProfileとAudio Scenarioの選択
Agoraでは音声の品質特性をAudio Profile（コーデックやビットレート）とAudio Scenario（通話、配信、ゲームなど用途別の最適化）の組み合わせで制御します。サンプルコードのデフォルト設定のまま進めると、自社のユースケースに合わない音質になることがあります。配信なのか1対1通話なのかで最適な設定が異なるため、早めに検討しておきましょう。
NAT/Firewallへの対応
社内ネットワークやエンタープライズ環境では、NATやFirewallによって通信がブロックされることがあります。Cloud Proxyの導入が必要かどうか、サービスの通信要件に応じて設計段階で判断しておく必要があります。
チャンネル管理と利用料
意外と見落としがちなのが、チャンネルに接続しているだけでAudio Usageが発生するという点です。実際に、イベント終了後もユーザーがチャンネルに残り続け、利用料が想定以上に膨らんだケースがあります。チャンネルの自動退出ロジックやタイムアウト設定は、早い段階で実装しておきましょう。
詳しい対処法はこちらの記事も参考になります。
もう一つ：困ったときに頼れるリソース
最後に、開発中に困ったときに役立つリソースを紹介します。
- Agora Docs：右下の「Docs Assistant」からAIに質問できます。日本語にも対応しています
- Connection State Management：ユーザーが切断された際のサーバー側の挙動を理解しておくと、トラブルシューティングが格段に楽になります
- Agora MCP/Skills：CursorやCline等のAIコーディングアシスタントにインポートできるスキルセットです。トークン生成のサーバー実装、Audio Profile/Scenarioの設定、クロスプラットフォームの音声ルーティング差分など、本記事で紹介したTIPSの多くがスキル定義としてカバーされています。Vibe Codingで実装を進める方は、最初にインポートしておくとAIからの提案精度が上がります。
ブイキューブのサポートについて
ブイキューブはAgoraの日本総代理店として、トライアル中の技術相談から本番環境の構築支援まで、日本語でサポートしています。実装で困ったことがあれば、お気軽にお問い合わせください。
