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 省略可、文字列

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

指定できる値は、端末の登録トークン、端末グループの通知キー、または(/topics/ の接頭辞が付いた)単一のトピックです。複数のトピックに送信するには、condition パラメータを使用します。

registration_ids
省略可、文字列の配列

このパラメータは、複数の登録トークンに送信されるマルチキャスト メッセージの受信者を指定します。

マルチキャスト メッセージの送信先となる登録トークンの配列を値とします。配列には少なくとも 1 つの登録トークンが含まれている必要があります。指定可能な最大のトークン数は 1,000 個です。単一の端末にメッセージを送信するには、to パラメータを使用します。

マルチキャスト メッセージには 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 省略可、ブール値

iOS では、このフィールドを使用して APNs ペイロードで content-available を表します。通知やメッセージの送信時にこのフィールドが true に設定されている場合、非アクティブなクライアント アプリのスリープ状態が解除されます。また、メッセージは FCM 接続サーバーではなく APNs を介して、サイレント通知として送信されます。APNs のサイレント通知の配信は保証されておらず、ユーザーが [低電力モード] をオンにする、アプリを強制終了するなどの要因によって結果が異なる場合があることに注意してください。Android では、デフォルトでデータ メッセージによってアプリが復帰します。Chrome では現在サポートされていません。

mutable_content 省略可、JSON ブール値

現時点では iOS 10 以降の端末のみでサポートされます。iOS では、このフィールドを使用して APNs ペイロード内の mutable-content を表します。通知の送信時にこのフィールドが true に設定されている場合、その通知が表示される前に通知サービスアプリ拡張機能を使って通知の内容を変更できます。このパラメータは Android とウェブでは無視されます。

delay_while_idle
2016 年 11 月 15 日にサポート終了
省略可、ブール値

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

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

デフォルト値は false です。

time_to_live 省略可、数値

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

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

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

デフォルト値は false です。

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

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

たとえば data:{"score":"3x1"}: を使用すると、次のようになります。

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

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

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

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

notification 省略可、オブジェクト このパラメータは、通知ペイロードの事前定義されたユーザー表示用の Key-Value ペアを指定します。詳細については、通知ペイロードのサポートを参照してください。通知メッセージとデータ メッセージのオプションの詳細については、メッセージ タイプをご覧ください。通知ペイロードが提供されている場合、または iOS 端末へのメッセージについて content_available オプションが true に設定されている場合は、メッセージは APNs を介して送信されます。それ以外の場合は、FCM 接続サーバーを介して送信されます。

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

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

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

パラメータ 指定方法 説明
title 省略可、文字列

通知のタイトル。

このフィールドは iOS のスマートフォンやタブレットには表示されません。

body 省略可、文字列

通知の本文。

sound 省略可、文字列

端末が通知を受信したときに再生される通知音。

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

badge 省略可、文字列

ホーム画面アプリのアイコンのバッジの値。

これを指定しなかった場合、バッジは変更されません。

0 に設定するとバッジは削除されます。

click_action 省略可、文字列

ユーザーが通知をクリックしたときに実行されるアクション。

APNs ペイロード内の category に対応します。

subtitle 省略可、文字列

通知のサブタイトル。

body_loc_key 省略可、文字列

ユーザーの現在のローカリゼーションに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。

APNs ペイロード内の loc-key に対応します。

詳細については、ペイロードキー リファレンスリモート通知の内容のローカライズをご覧ください。

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

ユーザーの現在のローカリゼーションに合わせて本文テキストをローカライズするために使用する、body_loc_key で指定された書式指定子と置き換える可変文字列値。

APNs ペイロード内の loc-args に対応します。

詳細については、ペイロードキー リファレンスリモート通知の内容のローカライズをご覧ください。

title_loc_key 省略可、文字列

ユーザーの現在のローカリゼーションに合わせてタイトル テキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。

APNs ペイロード内の title-loc-key に対応します。

詳細については、ペイロードキー リファレンスリモート通知の内容のローカライズをご覧ください。

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

ユーザーの現在のローカリゼーションに合わせてタイトル テキストをローカライズするために使用する、title_loc_key で指定された書式指定子と置き換える可変文字列値。

APNs ペイロード内の title-loc-args に対応します。

詳細については、ペイロードキー リファレンスリモート通知の内容のローカライズをご覧ください。

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

パラメータ 指定方法 説明
title 省略可、文字列

通知のタイトル。

body 省略可、文字列

通知の本文。

android_channel_id 省略可、文字列

通知のチャネル ID(Android O の新機能)。

このキーを含む通知を受け取るには、アプリが事前にこの ID を持つチャネルを作成する必要があります。

リクエストでこのキーを送信しなかった場合、または提供されたチャネル ID がアプリによってまだ作成されていない場合は、アプリのマニフェストで指定されたチャネル ID が使用されます。

icon 省略可、文字列

通知アイコン

通知アイコンをドローアブル リソース myiconmyicon に設定します。リクエストでこのキーを送信しなかった場合は、アプリのマニフェストで指定されたランチャー アイコンが表示されます。

sound 省略可、文字列

端末が通知を受信したときに再生される通知音。

"default"、またはアプリにバンドルされた通知音リソースのファイル名を指定できます。通知音ファイルは /res/raw/ に置く必要があります。

tag 省略可、文字列

通知ドロワーにある既存の通知を置き換えるために使用される識別子。

指定されていない場合、各リクエストによって新しい通知が作成されます。

このタグが指定されていて、同じタグを持つ通知がすでに表示されている場合は、新しい通知によって通知ドロワー内の既存の通知が置き換えられます。

color 省略可、文字列

通知のアイコンの色。#rrggbb 形式で表されます。

click_action 省略可、文字列

ユーザーが通知をクリックしたときに実行されるアクション。

これが指定されている場合、ユーザーが通知をクリックすると、一致するインテント フィルタを持つアクティビティが起動します。

body_loc_key 省略可、文字列

ユーザーの現在のローカリゼーションに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。

詳細については、文字列リソースをご覧ください。

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

ユーザーの現在のローカリゼーションに合わせて本文テキストをローカライズするために使用する、body_loc_key で指定された書式指定子と置き換える可変文字列値。

詳細については、書式設定とスタイル設定をご覧ください。

title_loc_key 省略可、文字列

ユーザーの現在のローカリゼーションに合わせてタイトル テキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。

詳細については、文字列リソースをご覧ください。

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

ユーザーの現在のローカリゼーションに合わせてタイトル テキストをローカライズするために使用する、title_loc_key で指定された書式指定子と置き換える可変文字列値。

詳細については、書式設定とスタイル設定をご覧ください。

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

パラメータ 指定方法 説明
title 省略可、文字列

通知のタイトル。

body 省略可、文字列

通知の本文。

icon 省略可、文字列

通知のアイコンに使用する URL。

click_action 省略可、文字列

ユーザーが通知をクリックしたときに実行されるアクション。

すべての URL 値について、セキュアな HTTPS が必要です。

ダウンストリーム 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 メッセージの形式が適切であり、有効なフィールドが含まれていることを確認します(たとえば、正しいデータ型が渡されているか確認します)。
無効なパラメータ 400 + error:InvalidParameters 提供されたパラメータの名前と型が正しいことを確認します。
メッセージが大きすぎる 200 + error:MessageTooBig メッセージに含まれているペイロード データの合計サイズが、FCM の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 4,096 バイト、トピック メッセージでは 2,048 バイトです。これには、キーと値の両方が含まれます。
無効なデータキー 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 リクエストを処理しようとしてサーバーでエラーが発生しました。「タイムアウト」(上の行を参照)に記載されている要件に従って同じリクエストを再試行することができます。エラーが解消されない場合は、Firebase サポートまでお問い合わせください。
デバイス メッセージ レートの超過 200 + error:
DeviceMessageRate
Exceeded

特定の端末へのメッセージ レートが高すぎます。iOS アプリが APNs の制限を超えるレートでメッセージを送信した場合、このエラー メッセージが発生することがあります

この端末に送信されるメッセージの数を減らし、指数バックオフを使用して送信を再試行します。

トピック メッセージ レートの超過 200 + error:
TopicsMessageRate
Exceeded
特定のトピックの登録者へのメッセージ レートが高すぎます。このトピックに送信されるメッセージの数を減らし、指数バックオフを使用して送信を再試行します。
無効な APNs 認証情報 200 + error:
InvalidApnsCredential
必要な APNs 認証キーがアップロードされていないか、期限切れになっているため、iOS 端末を対象とするメッセージを送信できませんでした。開発用認証情報と本番用認証情報の有効性を確認します。

端末グループ管理

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

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

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

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

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