FCM メッセージについて

Firebase Cloud Messaging(FCM)には広範なメッセージング オプションと機能が用意されています。このページの情報は、通知メッセージとデータ メッセージについて理解し、FCM のオプションを使用してこれらのメッセージを何に利用できるかを把握するために提供されています。

これらのオプションの一部は Firebase Cloud Messaging サーバーを実装した場合にのみ利用できます。メッセージ オプションの完全なリストについては、選択した接続サーバー プロトコル(HTTP または XMPP)の参照情報をご覧ください。

メッセージのタイプ

FCM では、2 つのタイプのメッセージをクライアントに送信できます。

  • 通知メッセージ。「表示メッセージ」とみなされる場合もあります。
  • データ メッセージ。クライアント アプリによって処理されます。

通知メッセージはより軽量な方法で、2 KB の制限があり、ユーザーに表示されるいくつかのキーが事前定義されています。データ メッセージを使用すると、デベロッパーは最大 4 KB のカスタム Key-Value ペアを送信できます。通知メッセージにデータ ペイロードを組み込み、ユーザーが通知をタップしたときに配信されるようにすることもできます。

使用シナリオ 送信方法
通知メッセージ クライアント アプリの代わりに FCM によってエンドユーザーの端末にメッセージが自動表示されます。通知メッセージには、ユーザーに表示されるいくつかのキーが事前定義されています。
  1. アプリサーバーと FCM サーバー API を使用する方法: notification キーを設定します。データ ペイロードを任意で指定できます。常に折りたたみ可能になります。
  2. Notifications コンソールを使用する方法: メッセージのテキスト、タイトルなどを入力して送信します。 Notifications コンソールでカスタムデータを指定することで、データ ペイロードを任意で追加します。 常に折りたたみ可能になります。
データ メッセージ クライアント アプリがデータ メッセージの処理を行います。データ メッセージにはカスタムの Key-Value ペアだけが含まれます。 アプリサーバーと FCM サーバー API を使用する方法: data キーのみを設定します。折りたたみ可能または折りたたみ不可のどちらにすることもできます。

クライアント アプリに代わって FCM で通知の表示を処理する場合は、通知メッセージを使用します。クライアント アプリでメッセージを処理する場合は、データ メッセージを使用します。

アプリサーバーは、通知とデータ ペイロードの両方を含むメッセージを送信できます。このような場合には、FCM によって通知ペイロードの表示が処理され、クライアント アプリによってデータ ペイロードが処理されます。

通知メッセージを利用すると、デベロッパーは事前定義されたキーと任意指定のカスタム Key-Value ペアを使って、ユーザーに表示されるメッセージを簡単に送信することができます。データ ペイロードにはデベロッパーが指定したカスタム Key-Value ペアのみが含まれており、メッセージはクライアント アプリで処理される必要があります。送信するメッセージには、通知とデータ ペイロードの両方を含めることができます。

通知メッセージ

通知メッセージを送信するには、notification キーを使って、通知メッセージのユーザー表示部分に必要とされる事前定義のキーオプションを設定します。例として IM アプリ内の JSON 形式の通知メッセージを以下に示します。 ユーザーの端末に表示されるメッセージのタイトルは「Portugal vs. Denmark」、テキストは「great match!」になります。

  {
    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification" : {
      "body" : "great match!",
      "title" : "Portugal vs. Denmark",
      "icon" : "myicon"
    }
  }

アプリがバックグラウンドで動作中の場合、通知メッセージは通知トレイに配信されます。フォアグラウンドで動作時は、以下のコールバックによってメッセージが処理されます。

  • didReceiveRemoteNotification:(iOS の場合)
  • onMessageReceived()(Android の場合)データバンドルの notification キーには通知が含まれます。

データ メッセージ

データ ペイロードをクライアント アプリに送信するには、data キーにカスタム Key-Value ペアを設定します。データ メッセージには最大 4 KB のペイロードを含めることができます。

たとえば以下は上記と同じ IM アプリ内の JSON 形式のメッセージですが、情報は data キー内にカプセル化され、クライアント アプリがコンテンツを解釈する必要があります。

{
   "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "data" : {
     "Nick" : "Mario",
     "body" : "great match!",
     "Room" : "PortugalVSDenmark"
   },
 }

iOS では、メッセージは FCM によって格納され、アプリがフォアグラウンド状態で FCM 接続が確立している場合にのみ FCM から配信されます。Android では、クライアント アプリが onMessageReceived() でデータ メッセージを受信し、それに応じて Key-Value ペアを処理することができます。

プラットフォームに応じて、以下の補足情報も確認してください。

  • Android では、アクティビティを起動するために使用されるインテントでデータ ペイロードを取得できます。

  • iOS では、データ ペイロードは didReceiveRemoteNotification: で確認できます。

通知とデータ ペイロードの両方を含むメッセージ

通知とデータ ペイロードの両方を含むメッセージを受信するアプリの動作は、そのアプリがバックグラウンド状態なのかフォアグラウンド状態なのか、つまり受信時に本質的にアクティブであったか否かによって異なります。

  • バックグラウンドにある場合、アプリでは通知トレイに通知ペイロードを受信し、ユーザーが通知をタップしたときにのみデータ ペイロードが処理されます。
  • フォアグラウンドにある場合、両方のペイロードを取得できる状態でアプリがメッセージ オブジェクトを受信します。

以下に notification キーと data キーの両方を含む JSON 形式のメッセージを示します。

  {
    "to" : "APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx...",
    "notification" : {
      "body" : "great match!",
      "title" : "Portugal vs. Denmark",
      "icon" : "myicon"
    },
    "data" : {
      "Nick" : "Mario",
      "Room" : "PortugalVSDenmark"
    }
  }

折りたたみできないメッセージと折りたたみできるメッセージ

折りたたみできないメッセージとは、個々のメッセージが端末に配信されることを意味します。折りたたみできないメッセージは有用なコンテンツを配信するので、モバイルアプリへ指示してサーバーに接続してからデータをフェッチさせる「ping」とは対照的です。常に折りたたみ可能である通知メッセージを除き、メッセージは既定では折りたたみできません。FCM では配信するメッセージの順序が保証されません。

折りたたみできないメッセージの一般的な使用例は、チャット メッセージや重大メッセージです。たとえば、各メッセージが異なるコンテンツを含むため、IM アプリですべてのメッセージを配信したい場合などが考えられます。

折りたたみできるメッセージとは、まだ端末に配信されていない場合に、同じ折りたたみキーを含む新しいメッセージで置き換えることができるメッセージです。

折りたたみできるメッセージの一般的な使用例としては、送信後同期メッセージと通知メッセージの 2 種類があります。送信後同期メッセージは「ping」であり、データをサーバーと同期するようにモバイルアプリに指示します。たとえば、ユーザーに最新スコアを知らせるスポーツ アプリなどで使われます。このようなアプリで関連性のあるメッセージは最新のものだけです。

FCM では、任意の時点で端末ごとに折りたたみキーを最大 4 つまでアプリサーバーで使用できます。つまり、FCM 接続サーバーは端末ごとに 4 つの折りたたみ可能な送信後同期メッセージを、それぞれ別の折りたたみキーで同時に格納することができます。この上限を超えると、FCM ではどれを維持するかは保証せずに任意の 4 つの折りたたみキーのみ格納します。

どちらを使うべきか

パフォーマンス面から見ると、アプリで折りたたみできないメッセージを使用する必要がなければ、折りたたみできるメッセージを選択するのが適切です。ただし、折りたたみできるメッセージを使用する場合は、FCM 接続サーバーで使用できる異なる折りたたみキーは、任意の時点で登録トークンごとに最大 4 つまでという制限があるので注意してください。この上限を超えると予測不可能な事態を招く可能性があるので、上限内に収まるようにしてください。

使用シナリオ 送信方法
折りたたみ不可 すべてのメッセージがクライアント アプリにとって重要で、配信される必要がある。 通知メッセージを除き、すべてのメッセージは既定では折りたたみできません。
折りたたみ可能 古い関連メッセージをクライアント アプリにとって無意味にするような新しいメッセージがある場合、FCM によって古いメッセージが置き換えられる。例: 送信後同期通知メッセージまたは期限切れ通知メッセージ。 collapse_key パラメータを設定します。

メッセージの優先順位の設定

ダウンストリーム メッセージに配信の優先順位を割り当てるオプションには、標準(normal)と高(high)の 2 つの優先度があります。標準の優先度と高い優先度のメッセージの配信は以下のようになります。

  • 優先度: 標準。 データ メッセージの場合は、これがデフォルトの優先度です。優先度が標準のメッセージの場合、スリープ状態の端末ではネットワーク接続が開かれず、バッテリー節約のために配信が遅延されることがあります。新着メールやその他の同期データに関する通知など、緊急度の低いメッセージ配信では優先度を標準に設定します。
  • 優先度: 高。 通知メッセージの場合は、これがデフォルトの優先度です。FCM は、可能な場合はスリープ状態の端末をアクティブにし、アプリサーバーへのネットワーク接続を開いて優先度の高いメッセージを即時配信するよう試みます。たとえばインスタント メッセージ、チャット、音声通話アラートなどの機能があるアプリでは、一般的にネットワーク接続を開いて、FCM によって遅滞なく端末へメッセージが配信されるようにする必要があります。メッセージが緊急でありユーザーにすぐに気付いてもらう必要がある場合は、高い優先度を設定します。ただし、優先度の高いメッセージは、優先度が標準のメッセージに比べてバッテリーの消耗が早いことに注意してください。

有効な値は、標準が normal、高が high です。詳細については、HTTP または XMPP のサーバー リファレンスをご覧ください。

iOS のクライアント アプリでは、標準の優先度と高い優先度は、APNs 優先度の 5 と 10 にそれぞれ相当します。iOS 固有の動作の詳細については、APNs のマニュアルを参照してください。Android 固有の動作については、Doze とアプリ スタンバイの最適化を参照してください。

以下の優先度が標準のメッセージ例では、マガジンの購読者に新しいコンテンツがダウンロード可能になったことを通知します。

{
  "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
  "priority" : "normal",
  "notification" : {
    "body" : "This week's edition is now available.",
    "title" : "NewsMagazine.com",
    "icon" : "new"
  },
  "data" : {
    "volume" : "3.21.15",
    "contents" : "http://www.news-magazine.com/world-week/21659772"
  }
}

メッセージの有効期間の設定

FCM では通常、メッセージが送信されるとすぐに配信します。しかし、それが常に可能であるとは限りません。たとえば、プラットフォームが Android の場合、端末が電源オフの状態であるか、オフラインであるか、あるいは利用できない可能性もあります。FCM が意図的にメッセージを遅らせて、アプリが過剰なリソースを消費してバッテリーの寿命に悪影響を与えないようにすることもあります。

このようなとき、FCM ではメッセージが保存され、配信可能になるとすぐにそれが配信されます。この動作はほとんどの場合は問題ありませんが、配信が遅れると配信されなかったも同然となるアプリもあります。たとえば、メッセージが通話着信またはビデオチャットの通知である場合、それが意味を持つのは通話が終了する前の短時間だけです。または、メッセージがイベントへの招待状である場合、イベントが終了した後に受信しても意味がありません。

HTTPXMPP の両方のリクエストでサポートされている time_to_live パラメータを使用して、メッセージの有効期間を指定できます。このパラメータの値は 0~2,419,200 秒の期間で設定する必要があり、FCM でメッセージを保存し配信を試みる最大期間に対応します。このフィールドの指定がないリクエストには、既定で最大 4 週間の期間が設定されます。

この機能には以下のような用途が考えられます。

  • ビデオチャットの通話着信
  • 期限が近づいている招待イベント
  • カレンダー イベント

また、FCM では time_to_live(TTL)の値が 0 秒になっているメッセージにはスロットリングを発生させないこともメッセージの有効期間を指定する利点です。つまり、FCM ではメッセージを「すぐに送信するかまったく送信しない」ように最大限の努力が保証されます。time_to_live の値を 0 にすると、直ちに配信できないメッセージは破棄されることに注意してください。ただし、このようなメッセージが保存されることはないため、通知メッセージを送信するためのレイテンシが最善になります。

以下に、TTL を含む JSON 形式リクエストの例を示します。

 {
   "collapse_key" : "demo",
   "to" : "xyz",
   "data" : {
     "key1" : "value1",
     "key2" : "value2"
   },
   "time_to_live" : 3
 }
 

複数送信者からのメッセージの受信

FCM では、複数の当事者が同じクライアント アプリにメッセージを送信することができます。たとえば、クライアント アプリが複数の寄稿者から記事を集めるアグリゲータで、各寄稿者は新しい記事の公開時にメッセージを送信可能である要件があるとします。このメッセージには、クライアント アプリで記事をダウンロードできるように URL が含まれている場合があります。送信アクティビティをすべて 1 か所に集中させる代わりに、FCM では寄稿者が個別にメッセージを送信するように設定できます。

これを実現するには、各送信者が自身の送信者 ID を生成できるようにします。FCM の送信者 ID を取得する方法については、お使いのプラットフォームのクライアント マニュアルをご覧ください。登録をリクエストする際にクライアント アプリは、毎回対象端末フィールドにある別の送信者 ID でトークンを複数回フェッチします。

最後に、登録トークンを対応するアプリサーバーと(FCM 登録クライアントとサーバーのハンドシェイクを完了するために)共有すると、アプリサーバーは自身の認証キーを使用して、クライアント アプリにメッセージを送信できるようになります。

送信者の数は 100 名までの上限があります。

メッセージの有効期間

アプリサーバーから FCM にメッセージが送信され、メッセージ ID を受け取っても、メッセージが既に端末に配信されたことを意味するわけではありません。これは単に配信が受け付けられたことを意味し、その後でメッセージがどのように処理されるかは、多くの要因によって異なります。

最良のシナリオでは、端末が FCM に接続されており、画面がオンになっていて、スロットリングの制限がない場合、メッセージはすぐに配信されます。

端末が FCM に接続されていても Doze モードになっている場合、優先度の低いメッセージは端末が Doze モードを抜けるまで FCM で保管されます。このようなときに collapse_key が役立ちます。既に同じ折りたたみキー(と登録トークン)を持つメッセージが保存されていて、配信を待機している場合、古いメッセージは破棄され、新しいメッセージに置き換えられます(つまり古いメッセージが新しいメッセージによって折りたたまれます)。しかし、折りたたみキーが設定されていない場合は、新しいメッセージも古いメッセージも今後の配信のために保存されます。

端末が FCM に接続されていない場合、(ここでも折りたたみキーのルールに従って)接続が確立されるまでメッセージが保存されます。接続が確立されると、保留中のすべてのメッセージが FCM から端末に配信されます。端末が再接続されなくなった場合(工場出荷時の状態にリセットされた場合など)、メッセージは最終的にタイムアウトし、FCM ストレージから破棄されます。time_to_live フラグが設定されていない限り、既定では 4 週間でタイムアウトします。

最後に、FCM が端末へのメッセージ配信を試みたときにアプリがアンインストールされていると、FCM はすぐにそのメッセージを破棄し、登録トークンを無効にします。それ以降、同じ端末にメッセージを送信しようとすると NotRegistered エラーが発生します。

認証情報

実装する FCM 機能によっては、Firebase プロジェクトから次の認証情報を取得することが必要な場合があります。

送信者 ID Firebase プロジェクトの作成時に作成される一意の数値。この ID は、Firebase console の [設定] ペインにある [Cloud Messaging] タブで確認できます。送信者 ID を使用して、クライアント アプリにメッセージを送信できる各アプリサーバーが識別されます。
サーバーキー

サーバーキーで、Firebase Cloud Messaging 経由のメッセージの送信などの、アプリサーバーから Google サービスへのアクセスを承認します。サーバーキーは Firebase プロジェクトの作成時に取得します。サーバーキーは、Firebase console の [設定] ペインにある [クラウド メッセージング] タブで確認できます。

重要: クライアント コードにはサーバーキーを含めないでください。また、アプリサーバーの承認には、必ずサーバーキーのみを使用してください。Android、iOS、およびブラウザのキーは、FCM で拒否されます。

登録トークン クライアント アプリのインスタンスごとに FCM SDK によって生成される ID。単一の端末と端末グループへのメッセージングに必要になります。登録トークンは非公開にしなければならないことに注意してください。

フィードバックを送信...