Firebase Cloud Messaging の HTTP プロトコル

このドキュメントでは、Firebase Cloud Messaging 経由でアプリサーバーからクライアント アプリにメッセージを渡すために使用される HTTP 構文のリファレンスを示します。アプリサーバーはすべての HTTP リクエストを次のエンドポイントに送信する必要があります。

https://fcm.googleapis.com/fcm/send

使用できるパラメータとオプションは、次の大きなカテゴリに分類されます。

ダウンストリーム メッセージの構文

このセクションでは、Firebase Cloud Messaging からダウンストリーム メッセージを送信し、HTTP レスポンスを解釈するための構文を示します。

ダウンストリーム HTTP メッセージ(JSON)

次の表は、HTTP JSON メッセージのターゲット、オプション、およびペイロードを示しています。

表 1. ダウンストリーム HTTP メッセージ(JSON)のターゲット、オプション、ペイロード

パラメータ 指定方法 説明
ターゲット
to 省略可、文字列

このパラメータでは、メッセージの受信者を指定します。

値は、登録トークン、通知キー、トピックのいずれかにする必要があります。複数のトピックに送信するときは、このフィールドは設定しないでください。condition を参照してください。

registration_ids
文字列配列

このパラメータでは、マルチキャスト メッセージを受信する端末のリスト(登録トークンまたは ID)を指定します。1~1,000 個の登録トークンを含める必要があります。

このパラメータはマルチキャスト メッセージング専用であり、単一の受信者への送信には使用できません。マルチキャスト メッセージ(複数の登録トークンに送信)には HTTP JSON 形式のみを使用できます。

condition 省略可、文字列

このパラメータでは、メッセージのターゲットを決定する条件の論理式を指定します。

サポートされる条件: 「'yourTopic' in topics」の形式で表したトピック。この値は大文字と小文字が区別されません。

サポートされる演算子: &&||。トピック メッセージ 1 つあたり演算子は 2 つまで使用できます。

notification_key
サポート終了
省略可、文字列

このパラメータは廃止されました。代わりに、to を使用してメッセージの受信者を指定してください。複数の端末にメッセージを送信する方法の詳細については、お使いのプラットフォームのドキュメントをご覧ください。

オプション
collapse_key 省略可、文字列

このパラメータは、配信が再開されるときに最後のメッセージだけが送信されるように、折りたたみ可能なメッセージのグループを(collapse_key: "Updates Available" により)識別します。これは、端末がオンラインに戻るか、アクティブになったときに、同じメッセージが過剰に送信されないようにするためのものです。

メッセージが送信される順序は保証されません。

注: 任意の時点で最大 4 つの異なる折りたたみキーを使用できます。したがって、FCM 接続サーバーは、クライアント アプリごとに 4 つの送信後同期メッセージを同時に保存できます。この数を超えた場合、FCM 接続サーバーが保存する 4 つの折りたたみキーがどれになるかは保証されません。

priority 省略可、文字列

メッセージの優先度を設定します。有効な値は「normal」と「high」です。 iOS では、これらは APNs 優先度の 5 と 10 に相当します。

デフォルトでは、通知メッセージは high(高)の優先度で送信され、データ メッセージは normal(標準)の優先度で送信されます。優先度が normal の場合、クライアント アプリのバッテリー消費量が最適化されるため、すぐに配信する必要がない限り、これを使用してください。この優先度を指定されたメッセージをアプリで受信するまでに、不特定の遅延が発生する可能性があります。

high(高)の優先度が付いたメッセージの場合はすぐに送信されます。スリープ状態にある端末はアプリによってアクティブにされ、サーバーへのネットワーク接続が開かれます。

詳細については、メッセージの優先順位の設定をご覧ください。

content_available 省略可、JSON ブール値 iOS では、このフィールドを使用して APNs ペイロードで content-available を表します。通知やメッセージの送信時にこのフィールドが true に設定されている場合、アクティブでないクライアント アプリのスリープ状態が解除されます。Android では、既定でデータ メッセージによってアプリのスリープ状態が解除されます。Chrome では現在サポートされていません。
delay_while_idle
2016 年 11 月 15 日にサポート終了
省略可、JSON ブール値

このパラメータは廃止されました。2016 年 11 月 15 日を過ぎると、FCM によって受け入れられますが、無視されるようになります。

このパラメータが true に設定されている場合、端末がアクティブになるまでメッセージを送信すべきでないことを示します。

既定値は false です。

time_to_live 省略可、JSON 数値

このパラメータでは、端末がオフラインの場合にメッセージを FCM のストレージに保持する期間(秒単位)を指定します。サポートされている最大有効期間は 4 週間で、既定値は 4 週間です。詳細については、メッセージの有効期間の設定をご覧ください。

restricted_package_
name
省略可、文字列 このパラメータでは、アプリケーションのパッケージ名を指定します。メッセージを受信するには登録トークンがこの値と一致している必要があります。
dry_run 省略可、JSON ブール値

このパラメータが true に設定されている場合、デベロッパーは実際にメッセージを送信せずにリクエストをテストすることができます。

既定値は false です。

ペイロード
data 省略可、JSON オブジェクト

このパラメータでは、メッセージのペイロードのカスタム Key-Value ペアを指定します。

たとえば、data:{"score":"3x1"}: とした場合、次のようになります。

iOS では、メッセージが APNs 経由で送信された場合、カスタム データ フィールドを表します。FCM 接続サーバー経由で送信された場合は、AppDelegate application:didReceiveRemoteNotification: でキーと値の辞書として表されます。

Android では、score というインテントの extra に文字列値 3x1 が設定されます。

キーを予約語(「from」、または「google」や「gcm」で始まる語)にすることはできません。この表に定義されたどの単語も使用しないでください(collapse_key など)。

値は文字列型にすることをおすすめします。オブジェクトに含まれる値や文字列型以外のデータ型(整数またはブール値)は、文字列型に変換する必要があります。

notification 省略可、JSON オブジェクト このパラメータでは、通知ペイロードの事前定義済みでユーザーに表示される Key-Value ペアを指定します。詳細については、通知ペイロードのサポートを参照してください。通知メッセージとデータ メッセージ オプションの詳細については、ペイロードをご覧ください。

通知ペイロードのサポート

次の表は、iOS および Android 用の通知メッセージの構築に使用できる事前定義されたキーの一覧を示します。

表 2a. iOS — 通知メッセージのキー

パラメータ 指定方法 説明
title 省略可、文字列 通知のタイトルを示します。 このフィールドは iOS のスマートフォンやタブレットには表示されません。
body 省略可、文字列 通知の本文テキストを示します。
sound 省略可、文字列

端末が通知を受信したときに再生する通知音を示します。 通知音ファイルはクライアント アプリのメインバンドルにあるか、アプリのデータコンテナの Library/Sounds フォルダにあります。詳細については、iOS デベロッパー ライブラリをご覧ください。

badge 省略可、文字列 クライアント アプリのホームアイコン上のバッジを示します。
click_action 省略可、文字列

ユーザーが通知をクリックする操作に関連付けられたアクションを示します。 APNs ペイロードの category に該当します。

body_loc_key 省略可、文字列

ローカライズ用の本文の文字列に対するキーを示します。APNs ペイロードの「loc-key」に該当します。

body_loc_args 省略可、文字列による JSON 配列

ローカライズ目的で、本文の文字列内の書式指定子を置き換える文字列値を示します。APNs ペイロードの「loc-args」に該当します。

title_loc_key 省略可、文字列

ローカライズ用のタイトル文字列に対するキーを示します。 APNs ペイロードの「title-loc-key」に該当します。

title_loc_args 省略可、文字列による JSON 配列

ローカライズ目的で、タイトル文字列内の書式指定子を置き換える文字列値を示します。APNs ペイロードの「title-loc-args」に該当します。

表 2b. Android — 通知メッセージのキー

パラメータ 指定方法 説明
title 省略可、文字列 通知のタイトルを示します。
body 省略可、文字列 通知の本文テキストを示します。
icon 省略可、文字列 通知アイコンを示します。 ドローアブル リソース myicon の場合は値を myicon に設定します。リクエストでこのキーを送信しない場合、FCM はアプリのマニフェストで指定されたランチャー アイコンを表示します。
sound 省略可、文字列

端末が通知を受信したときに再生する通知音を示します。 default、またはアプリにバンドルされた通知音リソースのファイル名を指定できます。通知音ファイルは /res/raw/ に置く必要があります。

tag 省略可、文字列 各通知によって Android 上の通知ドロワーに新しいエントリが作成されるかどうかを示します。
設定されていない場合は、各リクエストにより新しい通知が作成されます。
設定されていて、同じタグを持つ通知が既に表示されている場合、通知ドロワー内の既存の通知が新しい通知に置き換わります。
color 省略可、文字列 アイコンの色を #rrggbb 形式で表します。
click_action 省略可、文字列

ユーザーが通知をクリックする操作に関連付けられたアクションを示します。 これが設定されている場合、ユーザーが通知をクリックしたときにインテント フィルタに一致するアクティビティが起動されます。

body_loc_key 省略可、文字列

ローカライズ用の本文文字列に対するキーを示します。アプリの文字列リソースにあるキーを使ってこのパラメータの値を指定します。

body_loc_args 省略可、文字列による JSON 配列

ローカライズ目的で、本文文字列内の書式指定子を置き換える文字列値を示します。詳細については、書式設定とスタイルを参照してください。

title_loc_key 省略可、文字列

ローカライズ用のタイトル文字列に対するキーを示します。アプリの文字列リソースにあるキーを使ってこのパラメータの値を指定します。

title_loc_args 省略可、文字列による JSON 配列

ローカライズ目的で、タイトル文字列内の書式指定子を置き換える文字列値を示します。詳細については、文字列のフォーマットをご覧ください。

表 2c. ウェブ(JavaScript) - 通知メッセージのキー

パラメータ 指定方法 説明
title 省略可、文字列 通知のタイトルを示します。
body 省略可、文字列 通知の本文テキストを示します。
icon 省略可、文字列 通知アイコンの URL。
click_action 省略可、文字列

ユーザーが通知をクリックする操作に関連付けられたアクションを示します。 セキュアな HTTPS はすべての URL に対して必要です。

ダウンストリーム HTTP メッセージ(書式なしテキスト)

次の表は、書式なしテキストのダウンストリーム HTTP メッセージに含まれるターゲット、オプション、およびペイロードの構文を示しています。

表 3. 書式なしテキストのダウンストリーム HTTP メッセージのターゲット、オプション、ペイロード

パラメータ 指定方法 説明
ターゲット
registration_id 必須、文字列

このパラメータでは、メッセージを受信するクライアント アプリ(登録 ID)を指定します。

マルチキャスト メッセージング(複数の登録 ID に送信)には HTTP JSON 形式のみを使用できます。

オプション
collapse_key 省略可、文字列 詳細については表 1 を参照してください。
time_to_live 省略可、数値 詳細については表 1 を参照してください。
restricted_package_name 省略可、文字列 詳細については表 1 を参照してください。
dry_run 省略可、ブール値 詳細については表 1 を参照してください。
ペイロード
data.<key> 省略可、文字列

このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。Key-Value パラメータの数に制限はありませんが、合計メッセージ サイズは 4 KB までに制限されています。

たとえば Android で "data.score"."3x1" とすると score というインテントの extra に文字列値 3x1 が設定されます。

キーを予約語(「from」、または「google」や「gcm」で始まる語)にすることはできません。この表に定義されたどの単語も使用しないでください(collapse_key など)。

ダウンストリーム メッセージ レスポンスの解釈

FCM から送信されたメッセージ レスポンスを解釈するには、アプリサーバーでメッセージ レスポンスのヘッダーと本文の両方を評価する必要があります。次の表に想定されるレスポンスを示します。

表 4. ダウンストリーム HTTP メッセージ レスポンス ヘッダー

レスポンス 説明
200 メッセージは正常に処理されました。レスポンスの本文にはメッセージのステータスに関する詳細が含まれますが、その形式はリクエストが JSON と書式なしテキストのどちらであったかによって異なります。詳細については表 5 を参照してください。
400 JSON リクエストに対してのみ適用されます。 リクエストが JSON として解析できなかったか、リクエストに無効なフィールド(数値が期待されている場合に文字列が渡されているなど)が含まれていたことを示します。レスポンスには障害の理由が明記されており、リクエストを再試行する前に、問題に対処する必要があります。
401 送信者アカウントの認証エラーが発生しました。
5xx 500~599 の範囲に含まれるエラー(500 や 503 など)は、リクエストの処理中に FCM 接続サーバーで内部エラーが発生したか、サーバーが(タイムアウトなどの理由で)一時的に利用できないことを示します。送信者はレスポンスに含まれている Retry-After ヘッダーを適用し、後で再試行する必要があります。アプリサーバーでは指数バックオフを実装する必要があります。

次の表は、ダウンストリーム メッセージ レスポンスの本文(JSON)に含まれるフィールドを示しています。

表 5. ダウンストリーム HTTP メッセージ レスポンス本文(JSON)

パラメータ 指定方法 説明
multicast_id 必須、数値 マルチキャスト メッセージを識別する一意の ID(番号)。
success 必須、数値 エラーなしで処理されたメッセージの数。
failure 必須、数値 処理できなかったメッセージの数。
canonical_ids 必須、数値 正規の登録トークンが含まれている結果の数。正規登録 ID は、クライアント アプリによって最後に登録をリクエストされた登録トークンです。これは、端末にメッセージを送信するときにサーバーが使用する必要がある ID です。
results 省略可、配列オブジェクト 処理されたメッセージのステータスを表すオブジェクトの配列。オブジェクトはリクエストと同じ順序でリストされます(リクエストに含まれる各登録 ID の結果は、リスポンス内にリクエストと同じインデックスで記載されます)。
  • message_id: 正常に処理されたメッセージごとに一意の ID を指定する文字列。
  • registration_id: メッセージが処理され送信されたクライアントアプリの正規登録トークンを指定する、省略可能な文字列。送信者は、今後のリクエストでこの値を登録トークンとして使用する必要があります。使用しない場合、メッセージは拒否される可能性があります。
  • error: 受信者のためにメッセージを処理する際に発生したエラーを指定する文字列。想定される値は表 9 に記載されています。

表 6. トピック メッセージの HTTP レスポンス本文(JSON)

パラメータ 指定方法 説明
message_id 省略可、数値 FCM が正常にリクエストを受信し、特定のトピックを登録した全端末に配信を試みる際のトピック メッセージ ID。
error 省略可、文字列 メッセージを処理する際に発生したエラー。 想定される値は表 9 に記載されています。

表 7. ダウンストリーム HTTP メッセージ レスポンス本文(書式なしテキスト)の正常なレスポンス

パラメータ 指定方法 説明
id 必須、文字列 このパラメータでは、FCM 接続サーバーによって正常に処理された一意のメッセージ ID を指定します。
registration_id 省略可、文字列 このパラメータでは、メッセージが処理され送信されたクライアント アプリの正規登録トークンを指定します。送信者は、今後のリクエストで登録トークンをこの値に置き換える必要があります。置き換えない場合、メッセージは拒否される可能性があります。

表 8. ダウンストリーム HTTP メッセージ レスポンス本文(書式なしテキスト)のエラー レスポンス

パラメータ 指定方法 説明
Error 必須、文字列 このパラメータでは、受信者のためにメッセージを処理する際のエラー値を指定します。詳細については、表 9 を参照してください。

ダウンストリーム メッセージのエラー レスポンス コード

次の表は、ダウンストリーム メッセージのエラー レスポンス コードを示しています。

表 9. ダウンストリーム メッセージのエラー レスポンス コード

エラー HTTP コード 推奨される対処方法
登録トークンが見つからない 200 + error:MissingRegistration 登録トークンがリクエストに含まれているか調べます。書式なしテキスト メッセージでは registration_id 内、JSON では to または registration_ids フィールド内を確認してください。
無効な登録トークン 200 + error:InvalidRegistration サーバーに渡す登録トークンの形式を確認します。Firebase Notifications に登録した際にクライアント アプリが受信する登録トークンと一致している必要があります。文字の追加や削除は行わないでください。
端末が登録されていない 200 + error:NotRegistered 次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。
  • クライアント アプリが FCM から登録解除した場合。
  • クライアント アプリが自動的に登録解除された場合。これはユーザーがアプリケーションをアンインストールしたときに発生する可能性があります。たとえば iOS では、APNs フィードバック サービスによって APNs トークンが無効であると報告された場合です。
  • 登録トークンが期限切れになった場合(たとえば、Google が登録トークンを更新したり、iOS 端末の APNs トークンが期限切れになった場合)。
  • クライアント アプリが更新されたが、新しいバージョンはメッセージを受信するように設定されていない場合。
上記のすべての状況で、アプリサーバーから既存の登録トークンを削除し、これを使用したメッセージの送信を停止してください。
無効なパッケージ名 200 + error:InvalidPackageName メッセージの宛先は、リクエストで渡された値に一致するパッケージ名を持つ登録トークンにしてください。
認証エラー 401 メッセージの送信に使用された送信者のアカウントを認証できませんでした。考えられる原因は次のとおりです。
  • 認証ヘッダーが見つからないか、HTTP リクエストに含まれた構文が無効です。
  • 無効なプロジェクト番号がキーとして送信されました。
  • キーは有効ですが、FCM サービスが無効になっています。
  • リクエストは、サーバーキーの IP のホワイトリストに登録されていないサーバーから発信されています。
認証ヘッダー内で送信しているトークンが、プロジェクトに関連付けられている正しいサーバーキーであることを確認してください。詳細については、サーバーキーの有効性の確認をご覧ください。
送信者が一致しない 200 + error:MismatchSenderId 登録トークンは、特定の送信者グループに結び付けられています。クライアント アプリを FCM に登録するときに、メッセージの送信が許可される送信者を指定する必要があります。メッセージをクライアント アプリに送信する場合は、これらの送信者 ID のどれかを使用してください。別の送信者に切り替えると、既存の登録トークンは機能しなくなります。
無効な JSON 400 JSON メッセージの形式が適切であり、有効なフィールドが含まれていることを確認します(たとえば、正しいデータ型が渡されているか確認します)。
メッセージが大きすぎる 200 + error:MessageTooBig メッセージに含まれているペイロード データの合計サイズが、FCM の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 4096 バイト、iOS でのトピック メッセージや通知メッセージでは 2048 バイトで、これにはキーと値の両方が含まれます。
無効なデータキー 200 + error:
InvalidDataKey
ペイロード データに、FCM 内部で使用されるキー(fromgcm、先頭に google が付けられたすべての値など)が含まれていないことを確認します。一部の語(collapse_key など)は FCM でも使用されますが、ペイロードでも使用できます。この場合、ペイロードの値は FCM の値によってオーバーライドされます。
無効な有効期間 200 + error:InvalidTtl time_to_live で使用される値が、0~2,419,200(4 週間)の期間(秒単位)を示す整数であることを確認します。
タイムアウト 5xx または 200 + error:Unavailable

サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行してください。ただし、次の条件を満たす必要があります。

  • FCM 接続サーバーからのレスポンスに Retry-After ヘッダーが含まれていれば、それを適用します。
  • 再試行のメカニズムに指数バックオフを適用します(例: 最初に再試行する前に 1 秒間待機した場合は、次の再試行までに少なくとも 2 秒間待機し、さらに次は 4 秒間待機する)。 複数のメッセージを再送信する場合は、すべてのメッセージに対して新規リクエストが同時に発行されないように、各メッセージにランダムな秒数を加えて送信を個別に遅らせます。

問題を引き起こす送信者はブラックリストに登録されるおそれがあります。

内部サーバーエラー 500 または 200 + error:InternalServerError リクエストを処理しようとしてサーバーでエラーが発生しました。「タイムアウト」(上の行を参照)に記載されている要件に従って同じリクエストを再試行することができます。エラーが解決しない場合は、問題を android-gcm group で報告してください。
デバイス メッセージ レートの超過 200 + error:
DeviceMessageRate
Exceeded
特定の端末へのメッセージ レートが高すぎます。この端末に送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。
トピック メッセージ レートの超過 200 + error:
TopicsMessageRate
Exceeded
特定のトピックの登録者へのメッセージ レートが高すぎます。このトピックについて送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。

端末グループ管理

次の表は、端末グループを作成し、メンバーを追加および削除するためのキーを示しています。詳細については、お使いのプラットフォーム(iOS または Android)のガイドを参照してください。

表 10. 端末グループ管理キー

パラメータ 指定方法 説明
operation 必須、文字列 送信するオペレーション。有効な値は、createaddremove です。
notification_key_name 必須、文字列 作成または変更する端末グループのユーザー定義の名前。
notification_key 必須(create オペレーション、文字列を除く 端末グループの一意の識別子。この値は、正常な create オペレーションに対する応答で返され、端末グループのすべての後続のオペレーションで必要です。
registration_ids 必須の JSON 配列 追加または削除する端末トークン。端末グループから既存のすべての登録トークンを削除すると、FCM によって端末グループが削除されます。

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