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