FCM メッセージについて

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

メッセージのタイプ

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

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

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

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

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

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

通知メッセージ

テストやマーケティング、ユーザーの再エンゲージメントのために、Notifications Composer を使用して通知メッセージを送信できます。

Admin SDK または FCM プロトコルを使用して通知メッセージをプログラムで送信するには、notification キーを使って、通知メッセージのユーザー表示部分に対応する事前定義された Key-Value オプションの中から必要なものを設定します。例として、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: で確認できます。

オプションのデータ ペイロードを含む通知メッセージ

プログラムと Firebase コンソールのどちらからでも、カスタム Key-Value ペアのオプション ペイロードを含む通知メッセージを送信できます。Notifications Composer では、[詳細オプション] の [カスタムデータ] フィールドを使用します。

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

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

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

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

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

折りたたみできないメッセージとは、個々のメッセージが端末に配信されることを意味します。 折りたたみできないメッセージは、モバイルアプリにサーバーからデータをフェッチさせるための単なる合図ではなく、実際に意味のあるコンテンツを配信します。常に折りたたみ可能である通知メッセージを除き、メッセージはデフォルトでは折りたたみできません。

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

折りたたみせずに保存できるメッセージの数には 100 件の上限があります。上限に達した場合は、保存されているすべてのメッセージが破棄されます。端末がオンラインに戻ったとき、メッセージ数の上限に達したことを示す特別なメッセージが届きます。 この場合、通常はアプリサーバーとの完全な同期を要求することで、状況に適切に対処できます。

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

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

メッセージを折りたたみ可能としてマークするには、メッセージ ペイロードに collapse_key パラメータを含めます。FCM では、常に端末あたり最大 4 つの折りたたみキーをアプリサーバーで使用できます。つまり、FCM 接続サーバーは端末あたり 4 つの折りたたみ可能な送信後同期メッセージを、それぞれ異なる折りたたみキーで同時に保存できます。この上限を超えた場合は、引き続き 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 秒(28 日間)の間で設定する必要があります。これは 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 週間です。

端末が 1 か月以上 FCM に接続されていない場合、FCM は引き続きメッセージを受け取りますが、すぐに破棄します。その端末に最後にデータ メッセージが送信されてから 4 週間以内に端末が接続した場合、クライアントは onDeletedMessages() コールバックを受け取ります。 この場合、通常はアプリサーバーとの完全な同期を要求することで、状況に適切に対処できます。

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

認証情報

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

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

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

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

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

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

ご不明な点がありましたら、Google のサポートページをご覧ください。