このウェブサイトでは、お客様のコンピューターにCookieを保存します。このCookieは、このウェブサイトでのやり取りに関する情報を収集し、お客様を記憶するために使用されます。この情報は、お客様のブラウジング体験を改善し、カスタマイズすること、ならびにこのウェブサイトや他のメディアの訪問者に関する解析と指標を得ることを目的として利用されます。詳細はサイト利用規約をご覧ください。
理解しました

このセクションの記事

Agora Notifications とは

  • 更新
フォローする

質問・問題

Agora Notifications とは

 

回答・解決方法

概要

Agora Notifications とは、Agora サービス利用中に特定のイベントが発生した際に、 HTTPS リクエストを通して、通知として受け取ることができるサービスです。

予め受信したいイベントを登録いただくことで、 これらイベントが発生する度に、 Agora Notifications  は指定先のサーバーに対して通知を POST 送信するようになります。

各通知に含まれる情報を使うことで、更なるユーザーエクスペリエンスを提供いただくことが可能になります。

Agora Notifications が通知を送信してから 10 秒以内に、サーバーからステータス 200 OKを受信した場合において、通知は成功したとみなされます。

この条件を満たさない場合、Agora Notifications は直ちに通知再送をリトライします。再送の間隔は回数が増えるにつれ長くなり、最大 3 回まで再送されます。

 

対象プロダクト

Agora Notifications がサポートするプロダクトは以下となります: 

  • RTC のチャンネルイベント
  • Cloud Recording
  • Media Push
  • Media Pull

利用申請までの手順

2023-03-23 より Console から直接操作いただけるようになりました。
※ 従来の問い合わせベースによる申請も引き続き承ります。詳しくは以下の FAQ をご参考ください: 

 

Console からの設定をご希望の場合、以下の手順をご参考ください: 

  1. Agora Console ログイン後、左メニューから「Project Management」 を選択。

  2. 対象プロジェクトの Action カラム下「Configure」をクリック。

  3. 「Features」セクション内 「Notifications」の「Enable」をクリック。

  4. 設定したいプロダクト名をクリックして編集画面を展開。

    ※ 下図は RTC のチャンネルイベントのものとなります。

  5. 必要な設定項目を編集。

    • Event… 通知として受信したいイベントタイプ。ドロップダウンから複数指定いただけます。「?」アイコンのマウスオーバー時に表示されるバルーンから、イベント各種の詳細をご覧いただけます。
    • Receiving Server Region… 通知を受信するサーバーのロケーション
    • Receiving Server URL Endpoint… 通知を受信するサーバーの HTTPS アドレス。
      ※ 「http://」で始まるアドレスはサポートしません。
      例: https://1111-123-456-789-99.ap.ngrok.io/ncsNotify

      通知配信の遅延軽減の為、ベストプラクティスとして、以下の設定で HTTP keep-alive を有効化することを推奨します:
      • MaxKeepAliveRequests... 100 以上
      • KeepAliveTimeout... 10 秒以上
    • Status… こちらはオン (上図) になっていることをご確認ください。設定完了後、このトグルで Notification の有効・無効を切り替えるためのものになります。
    • Whitelist… 通知を受信するサーバーが Firewall 配下にある場合はチェックを入れ、Agora Notifications サーバーの IP アドレスを Firewall 許可リストに追加してください。サーバーの IP アドレスは IP address query API で取得いただけます。
      ※ アドレス情報は予告なしに変更する場合がありますので、アドレス確認および Firewall 設定の更新の定期的な実施を自動化することを推奨します。

  6. 編集後「Save」を押下し、入力した設定のヘルステスト (Health Test) を実行。

    ヘルステストにパスした場合、表示されるプロンプトの説明を確認し「Save NCS Configuration」をクリックして 閉じてください。この時、設定項目内の Status がオンになっていることを再度確認ください。

 

ヘルステストについて

ヘルステストでは、設定したイベントタイプに対応するテストイベントが生成され、 Receiving Server URL Endpoint で指定したサーバー宛に通知が送信されます。

通知を受信したサーバーは以下の要件を満たす形でレスポンスを返す必要があります。これらを満たさない場合はヘルステストは失敗と判定されます: 

  • 通知を受信した後、10 秒以内にステータスコード 200 でレスポンスを返すこと
  • レスポンスボディは JSON 形式であること

 

ヘルステストに失敗する場合

表示されるプロンプトに従って、エラーのトラブルシューティングを実施してください。一般的なエラーとしては以下の通りです: 

  • Request timeout (590)... 10 秒以内にステータスコード 200 を返さない場合のエラーです。サーバーが  Agora Notifications  からのリクエストに正しく応答しているか確認ください。もし適切に応答する場合、Agora Notifications サーバーと貴社サーバーとのネットワーク経路に問題がないか、サポートにお問合せください。
  • Domain name unreachable (591)... 無効なドメインが指定されているなどして、名前解決が行えない場合のエラーです。サーバーが正しくデプロイされていることをご確認ください。
  • Certificate error (592)... 貴社サーバーが返す SSL 証明書に対して、Agora Notifications  サーバーが検証失敗した場合のエラーです。サーバーの SSL 証明書が有効かご確認ください。Firewall 配下にサーバーがある場合、許可リストに Notifications サーバー全ての IP アドレスが追加されているかご確認ください。
  • その他のレスポンスエラー... 貴社サーバーが 200 以外のステータスコードで応答を返してる可能性があります。プロンプトに表示されるステータスコードとエラーメッセージの詳細をご確認ください。

セキュアな通信を確保するために

Agora Notifications と通知先サーバーが安全に通信できるよう、Agora SD-RTN™ は身元検証のためのシグネチャを提供します。必要に応じて、シグネチャ検証ロジックをサーバー側に実装ください。
※ 検証サンプルコードは以下リンク先からご覧いただけます: 

Agora Notifications は HMAC/SHA1 および HMAC/SHA256 アルゴリズムそれぞれで生成した 2 種類のシグネチャを挿入して通知します。各シグネチャは Agora-Signature および Agora-Signature-V2 として、HTTPS リクエストヘッダに追加されます

  • Agora-Signature で検証するには、秘密鍵 (secret)、Notifications からのリクエストボディ、HMAC/SHA1 アルゴリズムを使用します。
  • Agora-Signature-V2 で検証するには、秘密鍵 (secret)、Notifications からのリクエストボディ、HMAC/SHA256 アルゴリズムを使用します。

シグネチャ検証に使う秘密鍵 (secret) は、Agora Notifications の設定画面から取得できます

シグネチャ生成時は、リクエストボディを改変せずそのままお使いください。空文字の部分を null に置き換えるなどにより異なるシグネチャが生成され、検証失敗する恐れがあります。

 

その他 Agora Notifications に関する詳細

通知受信〜レスポンス送信までのサーバー側サンプルコード (開発テスト用)、特定プロダクトに対する追加情報など、その他情報は各種ドキュメントをご覧ください。

 

この記事のタグ：

関連記事