このドキュメントでは、アプリサーバー、クライアント アプリ、Firebase Cloud Messaging(FCM)の間でメッセージを渡すために使用される XMPP 構文のリファレンスを示します。アプリサーバーは、次のエンドポイントに接続する必要があります。
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
使用可能なパラメータとオプションは、次のカテゴリに分類されます。
ダウンストリーム メッセージの構文
このセクションでは、ダウンストリーム メッセージ送信時の構文について説明します。
ダウンストリーム XMPP メッセージ(JSON)
次の表は、XMPP JSON メッセージのターゲット、オプション、ペイロードを示しています。
パラメータ | 指定方法 | 説明 | |
---|---|---|---|
ターゲット | |||
to |
省略可、文字列 |
このパラメータでは、メッセージの受信者を指定します。 指定できる値は、デバイスの登録トークン、デバイス グループの通知キー、または( |
|
condition |
省略可、文字列 | このパラメータでは、メッセージのターゲットを決定する条件の論理式を指定します。 サポートされる条件: 「'yourTopic' in topics」の形式で表したトピック。この値は大文字と小文字が区別されません。 サポートされる演算子: |
|
オプション | |||
message_id |
必須、文字列 | このパラメータにより、XMPP 接続でのメッセージを一意に識別します。 |
|
collapse_key |
省略可、文字列 | このパラメータは、配信が再開されるときに最後のメッセージだけが送信されるように、折りたたみ可能なメッセージのグループを(たとえば メッセージが送信される順序は保証されません。 注: 任意の時点で最大 4 つの異なる折りたたみキーを使用できます。つまり、FCM はクライアント アプリごとに 4 つの異なるメッセージを同時に保存できます。この数を超えた場合、FCM が保存する 4 つの折りたたみキーがどれになるかは保証されません。 |
|
priority |
省略可、文字列 | メッセージの優先度を設定します。有効な値は「normal」と「high」です。Apple プラットフォームでは、これらは APNs 優先度の 5 と 10 に相当します。 デフォルトでは、通知メッセージは high(高)の優先度で送信され、データ メッセージは normal(標準)の優先度で送信されます。優先度が normal の場合、クライアント アプリのバッテリー消費量が最適化されるため、すぐに配信する必要がない限り、これを使用してください。 この優先度を指定されたメッセージは、アプリで受信されるまでに不特定の遅延が発生する可能性があります。 優先度が high のメッセージはすぐに送信され、アプリに通知が表示されます。 |
|
content_available |
省略可、ブール値 | Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の |
|
mutable_content |
省略可、JSON ブール値 | Apple プラットフォームでは、このフィールドを使用して APNs ペイロード内の |
|
time_to_live |
省略可、数値 | このパラメータでは、デバイスがオフラインの場合にメッセージを FCM のストレージに保持する期間(秒単位)を指定します。サポートされている最大有効期間は 4 週間で、デフォルト値は 4 週間です。 詳細については、メッセージの有効期間の設定をご覧ください。 |
|
dry_run |
省略可、ブール値 | このパラメータが デフォルト値は |
|
ペイロード | |||
data |
省略可、オブジェクト | このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。 たとえば、 Apple プラットフォームでは、メッセージが APNs によって配信された場合は、カスタムデータ フィールドを表します。FCM によって配信された場合は、 Android では、 キーを予約語(「from」や「message_type」、または「google」や「gcm」で始まる語)にすることはできません。この表に定義されたどの単語も使用しないでください( 値は文字列型にすることをおすすめします。オブジェクトに含まれる値や文字列型以外のデータ型(整数またはブール値)は、文字列型に変換する必要があります。 |
|
notification |
省略可、オブジェクト | このパラメータは、通知ペイロードの事前定義されたユーザー表示用の Key-Value ペアを指定します。詳細については、通知ペイロードのサポートをご覧ください。通知メッセージとデータ メッセージのオプションの詳細については、メッセージ タイプをご覧ください。通知ペイロードが提供されている場合、または Apple デバイスへのメッセージについて content_available オプションが true に設定されている場合は、メッセージは APNs を介して送信されます。それ以外の場合は、FCM を介して送信されます。 |
通知ペイロードのサポート
次の表は、Apple プラットフォームおよび Android 用の通知メッセージの構築に使用できる事前定義されたキーの一覧を示しています。
パラメータ | 指定方法 | 説明 |
---|---|---|
title |
省略可、文字列 |
通知のタイトル。 このフィールドはスマートフォンやタブレットには表示されません。 |
body |
省略可、文字列 |
通知の本文。 |
sound |
省略可、文字列 |
デバイスが通知を受信したときに再生される通知音。
クライアント アプリのメインバンドル内またはアプリのデータコンテナの |
badge |
省略可、文字列 |
ホーム画面のアプリアイコンのバッジの値。 これを指定しなかった場合、バッジは変更されません。
|
click_action |
省略可、文字列 |
ユーザーが通知をクリックしたときに実行されるアクション。 APNs ペイロード内の |
subtitle |
省略可、文字列 |
通知のサブタイトル。 |
body_loc_key |
省略可、文字列 |
ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。
APNs ペイロード内の 詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。 |
body_loc_args |
省略可、文字列による JSON 配列 |
ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、
APNs ペイロード内の 詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。 |
title_loc_key |
省略可、文字列 |
ユーザーの現在のローカライズに合わせてタイトル テキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。
APNs ペイロード内の 詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。 |
title_loc_args |
省略可、文字列による JSON 配列 |
ユーザーの現在のローカライズに合わせてタイトル テキストをローカライズするために使用する、
APNs ペイロード内の 詳細については、ペイロードキーのリファレンスとリモート通知内容のローカライズをご覧ください。 |
パラメータ | 指定方法 | 説明 |
---|---|---|
title |
省略可、文字列 |
通知のタイトル。 |
body |
省略可、文字列 |
通知の本文。 |
android_channel_id |
省略可、文字列 |
通知のチャネル ID(Android O の新機能)。 このチャネル ID を含む通知を受け取るには、アプリが事前にこのチャネル ID を持つチャネルを作成する必要があります。 リクエストでこのチャネル ID を送信しなかった場合、または提供されたチャネル ID がアプリによってまだ作成されていない場合は、FCMでは、アプリ マニフェストで指定されたチャネル ID が使用されます。 |
icon |
省略可、文字列 |
通知アイコン。
通知アイコンをドローアブル リソース |
sound |
省略可、文字列 |
デバイスが通知を受信したときに再生される通知音。
|
tag |
省略可、文字列 |
通知ドロワーにある既存の通知を置き換えるために使用される識別子。 指定されていない場合、リクエストごとに新しい通知が作成されます。 このタグが指定されていて、同じタグを持つ通知がすでに表示されている場合は、新しい通知によって通知ドロワー内の既存の通知が置き換えられます。 |
color |
省略可、文字列 |
通知のアイコンの色。 |
click_action |
省略可、文字列 |
ユーザーが通知をクリックしたときに実行されるアクション。 これが指定されている場合、ユーザーが通知をクリックすると、一致するインテント フィルタを持つアクティビティが起動します。 |
body_loc_key |
省略可、文字列 |
ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、アプリの文字列リソース内の本文文字列のキー。 詳細については、文字列リソースをご覧ください。 |
body_loc_args |
省略可、文字列による JSON 配列 |
ユーザーの現在のローカライズに合わせて本文テキストをローカライズするために使用する、 詳細については、書式設定とスタイル設定をご覧ください。 |
title_loc_key |
省略可、文字列 |
ユーザーの現在のローカライズに合わせてタイトル テキストをローカライズするために使用する、アプリの文字列リソース内のタイトル文字列のキー。 詳細については、文字列リソースをご覧ください。 |
title_loc_args |
省略可、文字列による JSON 配列 |
ユーザーの現在のローカライズに合わせてタイトル テキストをローカライズするために使用する、 詳細については、書式設定とスタイル設定をご覧ください。 |
パラメータ | 指定方法 | 説明 |
---|---|---|
title |
省略可、文字列 |
通知のタイトル。 |
body |
省略可、文字列 |
通知の本文。 |
icon |
省略可、文字列 |
通知のアイコンに使用する URL。 |
click_action |
省略可、文字列 |
ユーザーが通知をクリックしたときに実行されるアクション。 すべての URL 値で HTTPS が必須です。 |
ダウンストリーム XMPP メッセージ レスポンスを解釈する
次の表は、ダウンストリーム XMPP メッセージ レスポンスに表示されるフィールドを示しています。
パラメータ | 指定方法 | 説明 |
---|---|---|
from |
必須、文字列 | このパラメータでは、このレスポンスの送信者を指定します。 値は、クライアント アプリの登録トークンです。 |
message_id |
必須、文字列 | このパラメータにより、XMPP 接続でのメッセージを一意に識別します。 値は、関連付けられたメッセージを一意に識別する文字列です。 |
message_type |
必須、文字列 | このパラメータは、FCM からアプリサーバーへの 値が |
error |
省略可、文字列 | このパラメータでは、ダウンストリーム メッセージに関連したエラーを指定します。message_type が nack のときに設定されます。詳細については、表 4 をご覧ください。 |
error_description |
省略可、文字列 | このパラメータでは、エラーの説明を示します。message_type が nack のときに設定されます。 |
ダウンストリーム メッセージのエラー レスポンス コード
次の表は、ダウンストリーム メッセージのエラー レスポンス コードを示しています。
エラー | XMPP コード | 推奨される対処方法 |
---|---|---|
登録トークンが見つからない | INVALID_JSON |
登録トークンがリクエストに含まれているか調べます。書式なしテキスト メッセージでは registration_id 内、JSON では to フィールドまたは registration_ids フィールド内を確認してください。 |
APNs 登録が無効 | INVALID_JSON |
iOS 登録の場合は、クライアントからの登録リクエストに有効な APN トークンとアプリケーション ID が含まれていることを確認します。 |
無効な登録トークン | BAD_REGISTRATION |
サーバーに渡す登録トークンの形式を確認します。登録トークンが、FCM への登録時にクライアント アプリが受信した登録トークンと一致していることを確認します。文字の追加や削除は行わないでください。 |
デバイスが登録されていない | DEVICE_UNREGISTERED |
次のようないくつかの状況では、既存の登録トークンが有効でなくなることがあります。
|
送信者が一致しない | 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 |
サーバーで時間内にリクエストを処理できませんでした。同じリクエストを再試行してください。ただし、次の条件を満たす必要があります。
注: 問題を引き起こす送信者はブラックリストに登録されるおそれがあります。 |
内部サーバーエラー | INTERNAL_SERVER_
|
リクエストを処理しようとしてサーバーでエラーが発生しました。「タイムアウト」(上の行を参照)に記載されている要件に従って同じリクエストを再試行できます。 |
デバイス メッセージ レートの超過 | DEVICE_MESSAGE_RATE |
特定のデバイスへのメッセージ レートが高すぎます。この端末に送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。 |
トピック メッセージ レートの超過 | TOPICS_MESSAGE_RATE |
特定のトピックのサブスクライバーへのメッセージ レートが高すぎます。このトピックについて送信されるメッセージの数を減らして、送信を再試行するまでにしばらく時間を空けてください。 |
接続ドレイン | CONNECTION_DRAINING |
接続がドレインしているので、メッセージを処理できませんでした。FCM では負荷分散を行うために定期的に接続を閉じる必要があるため、このエラーが発生します。別の XMPP 接続でメッセージを再試行してください。 |
無効な APNs 認証情報 | INVALID_APNS_CREDENTIAL |
必要な APNs 認証キーがアップロードされていないか、期限切れになっているため、iOS デバイスを対象とするメッセージを送信できませんでした。開発用認証情報と本番用認証情報の有効性を確認します。 |
認証に失敗しました | AUTHENTICATION_FAILED |
外部プッシュ サービスでの認証に失敗しました。正しいウェブプッシュ証明書を使用しているかどうかを確認してください。 |
アップストリーム メッセージの構文
アップストリーム メッセージは、クライアント アプリがアプリサーバーに送信するメッセージです。 現在、XMPP のみがアップストリーム メッセージングをサポートしています。クライアント アプリからのメッセージ送信について詳しくは、プラットフォームのドキュメントをご覧ください。
アップストリーム XMPP メッセージの解釈
次の表では、クライアント アプリからのアップストリーム メッセージ リクエストに応じて、FCM で生成された XMPP スタンザのフィールドについて説明します。
パラメータ | 指定方法 | 説明 |
---|---|---|
from |
必須、文字列 | このパラメータでは、メッセージの送信者を指定します。 値は、クライアント アプリの登録トークンです。 |
category |
必須、文字列 | このパラメータでは、メッセージを送信したクライアント アプリのアプリケーション パッケージ名を指定します。 |
message_id |
必須、文字列 | このパラメータでは、メッセージの一意の ID を指定します。 |
data |
省略可、文字列 | このパラメータでは、メッセージのペイロードの Key-Value ペアを指定します。 |
ACK メッセージを送信する
次の表では、アプリサーバーが受信したアップストリーム メッセージに応じて、アプリサーバーが FCM に送信する予定の ACK レスポンスについて説明します。
パラメータ | 指定方法 | 説明 |
---|---|---|
to |
必須、文字列 | このパラメータでは、レスポンス メッセージの受信者を指定します。 値は、アップストリーム メッセージを送信したクライアント アプリの登録トークンにする必要があります。 |
message_id |
必須、文字列 | このパラメータでは、レスポンスの対象であるメッセージを指定します。値は、対応するアップストリーム メッセージからの message_id 値にする必要があります。 |
message_type |
必須、文字列 | このパラメータでは、アプリサーバーから CCS への ack メッセージを指定します。
アップストリーム メッセージの場合、常に ack に設定する必要があります。 |
FCM サーバー メッセージ(XMPP)
これは、FCM からアプリサーバーに送信されるメッセージです。 FCM からアプリサーバーに送信される主要なメッセージの種類は次のとおりです。
- コントロール: これらの CCS 生成メッセージは、アプリサーバーにアクションを要求していることを示します。
次の表では、CCS がアプリサーバーに送信するメッセージに含まれるフィールドについて説明しています。
パラメータ | 指定方法 | 説明 |
---|---|---|
共通のフィールド | ||
message_type |
必須、文字列 | このパラメータは、コントロール メッセージの種類を指定します。
|
control_type |
省略可、文字列 | このパラメータでは、FCM から送信されたコントロール メッセージの種類が指定されます。 現時点でサポートされているのは |