Firebase Cloud Messaging XMPP プロトコル

このドキュメントでは、アプリサーバー、クライアント アプリ、Firebase Cloud Messaging（FCM）の間でメッセージを渡すために使用される XMPP 構文のリファレンスを示します。アプリサーバーは、次のエンドポイントに接続する必要があります。

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

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

• ダウンストリーム メッセージの構文
• ダウンストリーム メッセージのエラー レスポンス コード
• アップストリーム メッセージの構文
• FCM コントロール メッセージ

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

このセクションでは、ダウンストリーム メッセージ送信時の構文について説明します。

ダウンストリーム XMPP メッセージ（JSON）

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

表 1 ダウンストリーム XMPP メッセージ（JSON）のターゲット、オプション、ペイロード

パラメータ	指定方法	説明
ターゲット
to	省略可、文字列	このパラメータでは、メッセージの受信者を指定します。 指定できる値は、デバイスの登録トークン、デバイス グループの通知キー、または（/topics/ の接頭辞が付いた）単一のトピックです。複数のトピックに送信するには、condition パラメータを使用します。
condition	省略可、文字列	このパラメータでは、メッセージのターゲットを決定する条件の論理式を指定します。 サポートされる条件: 「'yourTopic' in topics」の形式で表したトピック。この値は大文字と小文字が区別されません。 サポートされる演算子: &&、||。トピック メッセージ 1 つあたり演算子は 2 つまで使用できます。
オプション
message_id	必須、文字列	このパラメータにより、XMPP 接続でのメッセージを一意に識別します。
collapse_key	省略可、文字列	このパラメータは、配信が再開されるときに最後のメッセージだけが送信されるように、折りたたみ可能なメッセージのグループを（たとえば collapse_key: "Updates Available" により）識別します。これは、デバイスがオンラインに戻るか、Doze モードを抜けたときに、同じメッセージが過剰に送信されないようにするためのものです。 メッセージが送信される順序は保証されません。 注: 任意の時点で最大 4 つの異なる折りたたみキーを使用できます。つまり、FCM はクライアント アプリごとに 4 つの異なるメッセージを同時に保存できます。この数を超えた場合、FCM が保存する 4 つの折りたたみキーがどれになるかは保証されません。
priority	省略可、文字列	メッセージの優先度を設定します。有効な値は「normal」と「high」です。Apple プラットフォームでは、これらは APNs 優先度の 5 と 10 に相当します。 デフォルトでは、通知メッセージは high（高）の優先度で送信され、データ メッセージは normal（標準）の優先度で送信されます。優先度が normal の場合、クライアント アプリのバッテリー消費量が最適化されるため、すぐに配信する必要がない限り、これを使用してください。 この優先度を指定されたメッセージは、アプリで受信されるまでに不特定の遅延が発生する可能性があります。 優先度が high のメッセージはすぐに送信され、アプリに通知が表示されます。
content_available	省略可、ブール値	Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の content-available を表します。通知やメッセージの送信時にこのフィールドが true に設定されている場合、非アクティブなクライアント アプリのスリープ状態が解除されます。また、メッセージは FCM ではなく APNs を介して、サイレント通知として送信されます。APNs のサイレント通知の配信は保証されておらず、ユーザーが [低電力モード] をオンにする、アプリを強制終了するなどの要因によって結果が異なる場合があるので注意してください。Android では、デフォルトでデータ メッセージによってアプリが復帰します。Chrome では現在サポートされていません。
mutable_content	省略可、JSON ブール値	Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の mutable-content を表します。通知の送信時にこのフィールドが true に設定されている場合、その通知が表示される前に通知サービスアプリ拡張機能を使って通知の内容を変更できます。このパラメータは Android とウェブでは無視されます。
time_to_live	省略可、数値	このパラメータでは、デバイスがオフラインの場合にメッセージを FCM のストレージに保持する期間（秒単位）を指定します。サポートされている最大有効期間は 4 週間で、デフォルト値は 4 週間です。 詳細については、メッセージの有効期間の設定をご覧ください。
dry_run	省略可、ブール値	このパラメータが true に設定されている場合、デベロッパーは実際にメッセージを送信せずにリクエストをテストできます。 デフォルト値は false です。
ペイロード
data	省略可、オブジェクト	このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。 たとえば、data:{"score":"3x1"}: を使用すると、次のようになります。 Apple プラットフォームでは、メッセージが APNs によって配信された場合は、カスタムデータ フィールドを表します。FCM によって配信された場合は、AppDelegate application:didReceiveRemoteNotification: の Key-Value 辞書として表されます。 Android では、score というインテントの extra に文字列値 3x1 が設定されます。 キーを予約語（「from」や「message_type」、または「google」や「gcm」で始まる語）にすることはできません。この表に定義されたどの単語も使用しないでください（collapse_key など）。 値は文字列型にすることをおすすめします。オブジェクトに含まれる値や文字列型以外のデータ型（整数またはブール値）は、文字列型に変換する必要があります。
notification	省略可、オブジェクト	このパラメータは、通知ペイロードの事前定義されたユーザー表示用の Key-Value ペアを指定します。詳細については、通知ペイロードのサポートをご覧ください。通知メッセージとデータ メッセージのオプションの詳細については、メッセージ タイプをご覧ください。通知ペイロードが提供されている場合、または Apple デバイスへのメッセージについて content_available オプションが true に設定されている場合は、メッセージは APNs を介して送信されます。それ以外の場合は、FCM を介して送信されます。

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

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

表 2a. Apple - 通知メッセージのキー

パラメータ	指定方法	説明
title	省略可、文字列	通知のタイトル。 このフィールドはスマートフォンやタブレットには表示されません。
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 を送信しなかった場合、または提供されたチャネル ID がアプリによってまだ作成されていない場合は、アプリ マニフェストで指定されたチャネル ID が使用されます。
icon	省略可、文字列	通知アイコン。 通知アイコンをドローアブル リソース myicon の myicon に設定します。リクエストでこのキーを送信しなかった場合は、アプリ マニフェストで指定されたランチャー アイコンが表示されます。
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 が必須です。

ダウンストリーム XMPP メッセージ レスポンスを解釈する

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

表 3 ダウンストリーム メッセージ XMPP レスポンスの本文

パラメータ	指定方法	説明
from	必須、文字列	このパラメータでは、このレスポンスの送信者を指定します。 値は、クライアント アプリの登録トークンです。
message_id	必須、文字列	このパラメータにより、XMPP 接続でのメッセージを一意に識別します。 値は、関連付けられたメッセージを一意に識別する文字列です。
message_type	必須、文字列	このパラメータは、FCM からアプリサーバーへの ack または nack メッセージを指定します。 値が nack に設定されている場合、アプリサーバーは error と error_description を調べて、エラー情報を取得する必要があります。
error	省略可、文字列	このパラメータでは、ダウンストリーム メッセージに関連したエラーを指定します。message_type が nack のときに設定されます。詳細については、表 4 をご覧ください。
error_description	省略可、文字列	このパラメータでは、エラーの説明を示します。message_type が nack のときに設定されます。

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

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

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

エラー	XMPP コード	推奨される対処方法
登録トークンが見つからない	INVALID_JSON	登録トークンがリクエストに含まれているか調べます。書式なしテキスト メッセージでは registration_id 内、JSON では to フィールドまたは registration_ids フィールド内を確認してください。
APNs 登録が無効	INVALID_JSON	iOS 登録の場合は、クライアントからの登録リクエストに有効な APN トークンとアプリケーション ID が含まれていることを確認します。
無効な登録トークン	BAD_REGISTRATION	サーバーに渡す登録トークンの形式を確認します。登録トークンが、FCM への登録時にクライアント アプリが受信した登録トークンと一致していることを確認します。文字の追加や削除は行わないでください。
デバイスが登録されていない	DEVICE_UNREGISTERED	次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。 クライアント アプリが FCM から登録解除した場合。 クライアント アプリが自動的に登録解除された場合。これはユーザーがアプリケーションをアンインストールしたときに発生する可能性があります。たとえば、iOS では、APNs によって APNs トークンが無効であると報告された場合です。 登録トークンが期限切れになった場合（たとえば、Google が登録トークンを更新する場合、デバイスの APNs トークンが期限切れになった場合）。 クライアント アプリが更新されたが、新しいバージョンはメッセージを受信するように構成されていない場合。 上記のすべての状況で、アプリサーバーから既存の登録トークンを削除し、これを使用したメッセージの送信を停止してください。
送信者が一致しない	SENDER_ID_MISMATCH	登録トークンは、特定の送信者グループに結び付けられています。クライアント アプリを FCM に登録するときに、メッセージの送信が許可される送信者を指定する必要があります。メッセージをクライアント アプリに送信する場合は、これらの送信者 ID のいずれかを使用してください。別の送信者に切り替えると、既存の登録トークンは機能しなくなります。
無効な JSON です	INVALID_JSON	JSON メッセージの形式が適切であり、有効なフィールドが含まれていることを確認します（たとえば、正しいデータ型が渡されているか確認します）。
メッセージが大きすぎる	INVALID_JSON	メッセージに含まれているペイロード データの合計サイズが、FCM の上限を超えていないことを確認します。上限サイズは、ほとんどのメッセージでは 4,096 バイト、トピック メッセージでは 2,048 バイトです。これには、キーと値の両方が含まれます。
無効なデータキー	INVALID_JSON	ペイロード データに、FCM 内部で使用されるキー（from、gcm、先頭に google が付いた値など）が含まれていないことを確認します。一部の語（collapse_key など）は FCM でも使用されますが、ペイロードでも使用できます。この場合、ペイロードの値は FCM の値で上書きされます。
無効な有効期間	INVALID_JSON	time_to_live で使用される値が、0～2,419,200（4 週間）の期間（秒単位）を示す整数であることを確認します。
不正な ACK メッセージ	BAD_ACK	再試行する前に、ack メッセージが適切にフォーマットされていることを確認します。詳細については、表 6 をご覧ください。
タイムアウト	SERVICE_UNAVAILABLE	サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行してください。ただし、次の条件を満たす必要があります。 再試行メカニズムに指数バックオフを実装します。（例: 最初に再試行する前に 1 秒間待機した場合は、次の再試行までに少なくとも 2 秒間待機し、さらに次は 4 秒間待機します）。複数のメッセージを再送信する場合は、すべてのメッセージに対して新規リクエストが同時に発行されないように、各メッセージにランダムな秒数を加えて送信を個別に遅らせます。 最初の再試行の遅延は 1 秒に設定してください。 注: 問題を引き起こす送信者はブラックリストに登録されるおそれがあります。
内部サーバーエラー	INTERNAL_SERVER_ ERROR	リクエストを処理しようとしてサーバーでエラーが発生しました。「タイムアウト」（上の行を参照）に記載されている要件に従って同じリクエストを再試行できます。
デバイス メッセージ レートの超過	DEVICE_MESSAGE_RATE _EXCEEDED	特定のデバイスへのメッセージ レートが高すぎます。この端末に送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。
トピック メッセージ レートの超過	TOPICS_MESSAGE_RATE _EXCEEDED	特定のトピックのサブスクライバーへのメッセージ レートが高すぎます。このトピックについて送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。
接続ドレイン	CONNECTION_DRAINING	接続がドレインしているので、メッセージを処理できませんでした。FCM では負荷分散を行うために定期的に接続を閉じる必要があるため、このエラーが発生します。別の XMPP 接続でメッセージを再試行してください。
無効な APNs 認証情報	INVALID_APNS_CREDENTIAL	必要な APNs 認証キーがアップロードされていないか、期限切れになっているため、iOS デバイスを対象とするメッセージを送信できませんでした。開発用認証情報と本番用認証情報の有効性を確認します。
認証に失敗しました	AUTHENTICATION_FAILED	外部プッシュ サービスでの認証に失敗しました。正しいウェブプッシュ証明書を使用しているかどうかを確認してください。

アップストリーム メッセージの構文

アップストリーム メッセージは、クライアント アプリがアプリサーバーに送信するメッセージです。 現在、XMPP のみがアップストリーム メッセージングをサポートしています。クライアント アプリからのメッセージ送信について詳しくは、プラットフォームのドキュメントをご覧ください。

アップストリーム XMPP メッセージの解釈

次の表では、クライアント アプリからのアップストリーム メッセージ リクエストに応じて FCM が生成する XMPP スタンザ内のフィールドについて説明しています。

表 5 アップストリーム XMPP メッセージ

パラメータ	指定方法	説明
from	必須、文字列	このパラメータでは、メッセージの送信者を指定します。 値は、クライアント アプリの登録トークンです。
category	必須、文字列	このパラメータでは、メッセージを送信したクライアント アプリのアプリケーション パッケージ名を指定します。
message_id	必須、文字列	このパラメータでは、メッセージの一意の ID を指定します。
data	省略可、文字列	このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。

ACK メッセージを送信する

次の表では、アプリサーバーが受信したアップストリーム メッセージに応じて、アプリサーバーが FCM に送信することになっている ACK レスポンスについて説明しています。

表 6 アップストリーム XMPP メッセージ レスポンス

パラメータ	指定方法	説明
to	必須、文字列	このパラメータでは、レスポンス メッセージの受信者を指定します。 値は、アップストリーム メッセージを送信したクライアント アプリの登録トークンにする必要があります。
message_id	必須、文字列	このパラメータでは、レスポンスの対象であるメッセージを指定します。値は、対応するアップストリーム メッセージからの message_id 値にする必要があります。
message_type	必須、文字列	このパラメータでは、アプリサーバーから CCS への ack メッセージを指定します。 アップストリーム メッセージの場合、常に ack に設定する必要があります。

FCM サーバー メッセージ（XMPP）

これは、FCM からアプリサーバーに送信されるメッセージです。 FCM からアプリサーバーに送信される主要なメッセージの種類は次のとおりです。

• コントロール: これらの CCS 生成メッセージは、アプリサーバーにアクションを要求していることを示します。

次の表では、CCS がアプリサーバーに送信するメッセージに含まれるフィールドについて説明しています。

表 7 FCM コントロール メッセージ（XMPP）。

パラメータ	指定方法	説明
共通のフィールド
message_type	必須、文字列	このパラメータは、コントロール メッセージの種類を指定します。 control に設定されている場合、メッセージにはコントロール メッセージの種類を示す control_type が含まれます。
control_type	省略可、文字列	このパラメータでは、FCM から送信されたコントロール メッセージの種類が指定されます。 現時点でサポートされているのは CONNECTION_DRAINING のみです。FCM は、接続を閉じて負荷分散を行う前に、このコントロール メッセージを送信します。接続がドレインすると、同じ接続にはメッセージをそれ以上送信できなくなりますが、パイプライン内の既存のメッセージは引き続き処理されます。