Dieses Dokument enthält eine Referenz für die XMPP-Syntax, die zur Übergabe Nachrichten zwischen Ihrem Anwendungsserver, Client-Apps und Firebase Cloud Messaging (FCM) senden. Ihr Anwendungsserver muss eine Verbindung zu diesen Endpunkten herstellen:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Die verfügbaren Parameter und gliedern sich die Optionen in folgende Kategorien:
- Syntax von Downstream-Nachrichten
- Antwortcodes für Downstream-Nachrichtenfehler
- Syntax von vorgelagerten Nachrichten
- FCM Kontrollnachrichten
Nachgelagerte Nachrichtensyntax
In diesem Abschnitt wird die Syntax für das Senden von Downstream-Nachrichten beschrieben.
Downstream-XMPP-Nachrichten (JSON)
In der folgenden Tabelle sind die Ziele, Optionen und Nutzlasten für XMPP-JSON-Nachrichten aufgeführt.
Parameter | Nutzung | Beschreibung | |
---|---|---|---|
Ziel | |||
to |
Optionaler String |
Dieser Parameter gibt den Empfänger einer Nachricht an.
Der Wert kann das Registrierungstoken eines Geräts, das einer Gerätegruppe
oder einem einzelnen Thema (mit vorangestelltem
|
|
condition |
Optionaler String | Dieser Parameter gibt einen logischen Ausdruck für Bedingungen an, die das Nachrichtenziel bestimmt. Unterstützte Bedingung: Thema, formatiert als „yourTopic“ in Themen“. Dieses beim -Wert wird die Groß-/Kleinschreibung nicht berücksichtigt. Unterstützte Operatoren: |
|
Optionen | |||
message_id |
Erforderlich, String | Dieser Parameter identifiziert eine Nachricht in einer XMPP-Verbindung eindeutig. |
|
collapse_key |
Optionaler String | Dieser Parameter identifiziert eine Gruppe von Nachrichten (z.B. mit
Es gibt keine Garantie für die Reihenfolge, in der Nachrichten gesendet werden. Hinweis: Es sind maximal vier verschiedene Minimierungsschlüssel gleichzeitig zulässig. Das bedeutet, FCM kann gleichzeitig vier verschiedene Nachrichten pro Client-App. Wenn Sie diese Zahl überschreiten, gibt es keine Garantie, welche vier Minimierungsschlüssel FCM beibehalten werden. |
|
priority |
Optionaler String | Legt die Priorität der Nachricht fest. Gültige Werte sind „normal“ und „hoch“. Auf Apple-Plattformen entsprechen diese den APN-Prioritäten 5 und 10. Standardmäßig werden Benachrichtigungen mit hoher Priorität gesendet mit normaler Priorität gesendet. Mit der normalen Priorität wird die Leistung der Client-App und sollte verwendet werden, sofern keine sofortige Lieferung erforderlich ist. Die App empfängt Nachrichten mit normaler Priorität nicht angegebene Verzögerung. Wenn eine Nachricht mit hoher Priorität gesendet wird, wird sie sofort gesendet und die App eine Benachrichtigung anzeigen kann. |
|
content_available |
Optional, boolesch | Verwenden Sie dieses Feld auf Apple-Plattformen, um |
|
mutable_content |
Optional, boolescher JSON-Wert | Auf Apple-Plattformen: Verwenden Sie dieses Feld für
|
|
time_to_live |
Optional, Zahl | Dieser Parameter gibt an, wie lange (in Sekunden) die Nachricht im FCM-Speicher aufbewahrt werden soll wenn das Gerät offline ist. Die maximale Gültigkeitsdauer beträgt 4 Wochen und der Standardwert 4 Wochen. Weitere Informationen finden Sie unter Gültigkeitsdauer einer Nachricht festlegen. |
|
dry_run |
Optional, boolesch | Wenn dieser Parameter auf Der Standardwert ist |
|
Nutzlast | |||
data |
Optional, Objekt | Dieser Parameter gibt die Schlüssel/Wert-Paare der Nachrichtennutzlast an. Beispiel: Wenn die Nachricht auf Apple-Plattformen über APNs zugestellt wird, entspricht sie den benutzerdefinierten Datenfeldern. Wenn
Lieferung bis FCM,
wird er in Unter Android führt dies zu einem Intent-Extra namens Der Schlüssel darf kein reserviertes Wort sein ("from", "message_type" oder ein anderes Wort, das mit
„Google“ oder „gcm“). Keines der in dieser Tabelle definierten Wörter verwenden
(z. B. Es werden Werte in Stringtypen empfohlen. Sie müssen Werte in Objekten oder anderen Datentypen, die keine Strings sind (z. B. Ganzzahlen oder Boolesche Werte), in Strings konvertieren. |
|
notification |
Optional, Objekt | Dieser Parameter gibt die vordefinierten, für den Nutzer sichtbaren Schlüssel/Wert-Paare des
Benachrichtigungsnutzlast. Weitere Informationen finden Sie unter „Unterstützung für Benachrichtigungsnutzlast“. Weitere Informationen
Informationen zu den Optionen für Benachrichtigungs- und Datennachrichten finden Sie unter
Nachrichtentypen: Wenn eine Benachrichtigungsnutzlast bereitgestellt wird oder der
Die Option content_available ist für eine Nachricht an einen Apple auf true gesetzt.
wird die Nachricht über APNs gesendet, andernfalls über
FCM
|
Unterstützung für Benachrichtigungsnutzlast
In den folgenden Tabellen sind die vordefinierten Schlüssel aufgeführt, die zum Erstellen von Benachrichtigungsnachrichten für Apple-Plattformen und Android verfügbar sind.
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optionaler String |
Der Titel der Benachrichtigung. Auf Smartphones und Tablets ist dieses Feld nicht sichtbar. |
body |
Optionaler String |
Der Text der Benachrichtigung. |
sound |
Optionaler String |
Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt
String, der Sounddateien im Haupt-Bundle der Client-App oder in der
|
badge |
Optional, String |
Der Wert des Logos auf dem App-Symbol des Startbildschirms. Wenn keine Angabe erfolgt, wird das Logo nicht geändert.
Wenn |
click_action |
Optionaler String |
Die mit einem Nutzerklick verknüpfte Aktion auf die Benachrichtigung.
Entspricht |
subtitle |
Optionaler String |
Der Untertitel der Benachrichtigung. |
body_loc_key |
Optionaler String |
Der Schlüssel für den Bodystring in den Stringressourcen der App, der verwendet werden soll, um den Text in die aktuelle Lokalisierung des Nutzers übersetzen.
Entspricht Weitere Informationen finden Sie unter Nutzlastschlüsselreferenz und Lokalisieren des Inhalts Ihrer Remote-Benachrichtigungen Informationen. |
body_loc_args |
Optional, JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in
Entspricht Weitere Informationen finden Sie unter Nutzlastschlüsselreferenz und Lokalisieren des Inhalts Ihrer Remote-Benachrichtigungen Informationen. |
title_loc_key |
Optional, String |
Der Schlüssel für den Titelstring in den Stringressourcen der App, der verwendet werden soll, um den Titeltext entsprechend der aktuellen Lokalisierung des Nutzers lokalisieren.
Entspricht Weitere Informationen finden Sie unter Nutzlastschlüsselreferenz und Lokalisieren des Inhalts Ihrer Remote-Benachrichtigungen Informationen. |
title_loc_args |
Optional, JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in
Entspricht Weitere Informationen finden Sie unter Nutzlastschlüsselreferenz und Lokalisieren des Inhalts Ihrer Remote-Benachrichtigungen Informationen. |
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optionaler String |
Der Titel der Benachrichtigung. |
body |
Optionaler String |
Der Text der Benachrichtigung. |
android_channel_id |
Optionaler String |
Die Kanal-ID der Benachrichtigung (neu in Android O). Die App muss einen Kanal mit dieser Kanal-ID erstellen, bevor Benachrichtigungen mit dieser Kanal-ID erhalten haben. Wenn du diese Kanal-ID nicht in der Anfrage angibst oder die angegebene Kanal-ID noch nicht von der App erstellt wurde, verwendet FCM die im App-Manifest angegebene Kanal-ID. |
icon |
Optionaler String |
Das Benachrichtigungssymbol.
Legt das Benachrichtigungssymbol für die Drawable-Ressource auf |
sound |
Optionaler String |
Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt
Unterstützt |
tag |
Optionaler String |
ID, mit der vorhandene Benachrichtigungen in der Benachrichtigung ersetzt werden Leiste. Wenn nicht angegeben, wird für jede Anfrage eine neue Benachrichtigung erstellt. Wenn angegeben und bereits eine Benachrichtigung mit demselben Tag gesendet wird ersetzt die neue Benachrichtigung die vorhandene im Benachrichtigungsleiste. |
color |
Optionaler String |
Die Farbe des Benachrichtigungssymbols im Format |
click_action |
Optional, String |
Die mit einem Nutzerklick verknüpfte Aktion auf die Benachrichtigung. Wenn angegeben, wird eine Aktivität mit einem übereinstimmenden Intent-Filter gestartet, wenn wenn ein Nutzer auf die Benachrichtigung klickt. |
body_loc_key |
Optionaler String |
Der Schlüssel für den Bodystring in den Stringressourcen der App, der verwendet werden soll, um den Text in die aktuelle Lokalisierung des Nutzers übersetzen. Weitere Informationen finden Sie unter String Resources. |
body_loc_args |
Optional, JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in
Weitere Informationen finden Sie unter Weitere Informationen finden Sie unter „Formatierung und Gestaltung“. |
title_loc_key |
Optionaler String |
Der Schlüssel für den Titelstring in den Stringressourcen der App, der verwendet werden soll, um den Titeltext entsprechend der aktuellen Lokalisierung des Nutzers lokalisieren. Weitere Informationen finden Sie unter String Resources. |
title_loc_args |
Optional, JSON-Array als String |
Variable Stringwerte, die anstelle der Formatanweisungen in Weitere Informationen finden Sie unter Weitere Informationen finden Sie unter „Formatierung und Gestaltung“. |
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optionaler String |
Der Titel der Benachrichtigung. |
body |
Optionaler String |
Der Text der Benachrichtigung. |
icon |
Optionaler String |
Die URL, die für das Benachrichtigungssymbol verwendet werden soll. |
click_action |
Optionaler String |
Die mit einem Nutzerklick verknüpfte Aktion auf die Benachrichtigung. Für alle URL-Werte ist HTTPS erforderlich. |
Antwort auf eine XMPP-Nachricht interpretieren
In der folgenden Tabelle sind die Felder aufgeführt, die in einer nachgelagerten XMPP-Nachrichtenantwort angezeigt werden.
Parameter | Nutzung | Beschreibung |
---|---|---|
from |
Erforderlich, String | Dieser Parameter gibt an, wer diese Antwort gesendet hat. Der Wert ist das Registrierungstoken der Clientanwendung. |
message_id |
Erforderlich, String | Mit diesem Parameter wird eine Nachricht in einer XMPP-Verbindung eindeutig identifiziert. Der Wert ist eine Zeichenfolge, die die zugehörige Nachricht eindeutig identifiziert. |
message_type |
Erforderlich, String | Dieser Parameter gibt eine Wenn der Wert auf |
error |
Optional, String | Dieser Parameter gibt einen Fehler an, der sich auf die nachfolgende Nachricht bezieht. Er wird festgelegt, wenn der
message_type ist nack . Weitere Informationen finden Sie in Tabelle 4. |
error_description |
Optionaler String | Dieser Parameter enthält beschreibende Informationen zum Fehler. Sie wird festgelegt, wenn message_type den Wert nack hat. |
Fehlerantwortcodes für nachgelagerte Nachrichten
In der folgenden Tabelle sind die Fehlerantwortcodes für nachgelagerte Nachrichten aufgeführt.
Fehler | XMPP-Code | Empfohlene Maßnahmen |
---|---|---|
Registrierungstoken fehlt | INVALID_JSON |
Prüfe, ob die Anfrage ein Registrierungstoken enthält (in registration_id in einer Nur-Text-Nachricht oder im Feld to oder registration_ids in JSON). |
Ungültige APNs-Registrierung | INVALID_JSON |
Prüfen Sie bei iOS-Registrierungen, ob die Registrierungsanfrage vom Client Folgendes enthält: gültiges APNs-Token und Anwendungs-ID. |
Ungültiges Registrierungstoken | BAD_REGISTRATION |
Prüfen Sie das Format des Registrierungstokens, das Sie an den Server übergeben. Achten Sie darauf, stimmt mit dem Registrierungstoken überein, das die Client-App durch die Registrierung bei FCM erhält. Das sollten Sie nicht tun: oder fügen Sie zusätzliche Zeichen hinzu. |
Nicht registriertes Gerät | DEVICE_UNREGISTERED |
Ein bestehendes Registrierungstoken kann in verschiedenen Szenarien nicht mehr gültig sein, z. B.:
|
Nicht übereinstimmender Absender | SENDER_ID_MISMATCH |
Ein Registrierungstoken ist an eine bestimmte Gruppe von Absendern gebunden. Wenn sich eine Client-App registriert Für FCM muss angegeben werden, welche Absender Nachrichten senden dürfen. Eine beim Senden von Nachrichten an die Client-App zu verwenden. Wenn Sie zu einem anderen werden die vorhandenen Registrierungstokens nicht verwendet. |
Ungültiges JSON-Format | INVALID_JSON |
Prüfen Sie, ob die JSON-Nachricht richtig formatiert ist und gültige Felder enthält. Achten Sie beispielsweise darauf, dass der richtige Datentyp übergeben wird. |
Nachricht zu groß | INVALID_JSON |
Prüfen Sie, ob die Gesamtgröße der in einer Nachricht enthaltenen Nutzlastdaten die FCM-Limits nicht überschreiten: 4.096 Byte für die meisten Nachrichten oder 2.048 Byte im Fall von Nachrichten zu Themen. Dazu gehören sowohl die Schlüssel und Werte. |
Ungültiger Datenschlüssel | INVALID_JSON |
Die Nutzlastdaten dürfen keinen Schlüssel enthalten (z. B. from ,
gcm oder ein beliebiger Wert
google ) vorangestellt, das intern von FCM verwendet wird. Beachten Sie, dass einige Wörter (z. B. collapse_key )
werden auch von FCM verwendet, sind aber in der Nutzlast zulässig.
wird der Nutzlastwert vom Wert FCM überschrieben. |
Ungültige Gültigkeitsdauer | INVALID_JSON |
Prüfen Sie, ob der in time_to_live verwendete Wert eine Ganzzahl ist, die ein
Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen). |
Fehlerhafte ACK-Nachricht | BAD_ACK |
Prüfen Sie, ob die ack -Nachricht richtig formatiert ist, bevor Sie es noch einmal versuchen. Weitere Informationen finden Sie unter
Tabelle 6. |
Zeitlimit | SERVICE_UNAVAILABLE |
Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Wiederholen Sie dieselbe Anfrage. Beachten Sie dabei jedoch Folgendes:
Hinweis: Absender, die Probleme verursachen, laufen Gefahr, auf die schwarze Liste gesetzt zu werden. |
Interner Serverfehler | INTERNAL_SERVER_
|
Beim Verarbeiten der Anfrage ist auf dem Server ein Fehler aufgetreten. Du kannst es noch einmal versuchen dieselbe Anfrage gemäß den unter „Zeitüberschreitung“ aufgeführten Anforderungen (siehe Zeile oben). |
Gerätenachrichtenrate überschritten | DEVICE_MESSAGE_RATE |
Die Rate der Nachrichten an ein bestimmtes Gerät ist zu hoch. Reduzieren Sie Anzahl an Nachrichten, die an dieses Gerät gesendet wurden, und versuchen Sie nicht sofort, sie zu senden. |
Nachrichtenrate für Themen überschritten | TOPICS_MESSAGE_RATE |
Die Rate der Nachrichten an Abonnenten zu einem bestimmten Thema ist zu hoch. Reduzieren Sie Anzahl der zu diesem Thema gesendeten Nachrichten. Versuchen Sie nicht sofort, sie zu senden. |
Verbindungsausgleich | CONNECTION_DRAINING |
Die Nachricht konnte nicht verarbeitet werden, da die Verbindung per Drain beendet wird. Das liegt daran, In regelmäßigen Abständen muss FCM eine Verbindung für das Load-Balancing beenden. Senden Sie die Nachricht noch einmal über eine andere XMPP-Verbindung. |
Ungültige APNs-Anmeldedaten | INVALID_APNS_CREDENTIAL |
Eine an ein iOS-Gerät gerichtete Nachricht konnte nicht gesendet werden, da die erforderlichen APNs vorhanden sind Der Authentifizierungsschlüssel wurde nicht hochgeladen oder ist abgelaufen. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionsanmeldedaten. |
Authentifizierung fehlgeschlagen | AUTHENTICATION_FAILED |
Authentifizierung bei externen Push-Diensten fehlgeschlagen. Überprüfen Sie, ob Sie das die richtigen Web-Push-Zertifikate zu erhalten. |
Upstream-Nachrichtensyntax
Eine vorgelagerte Nachricht ist eine Nachricht, die die Client-App an den Anwendungsserver sendet. Derzeit unterstützt nur XMPP Upstream-Messaging. Weitere Informationen finden Sie unter finden Sie in der Dokumentation zu Ihrer Plattform Informationen zum Senden von Nachrichten von Client-Apps.
Interpretieren einer vorgelagerten XMPP-Nachricht
In der folgenden Tabelle werden die Felder der generierten XMPP-Stanza beschrieben. von FCM als Reaktion auf vorgelagerte Nachrichtenanfragen von Client-Apps verwendet.
Parameter | Nutzung | Beschreibung |
---|---|---|
from |
Erforderlich, String | Dieser Parameter gibt an, wer die Nachricht gesendet hat. Der Wert ist das Registrierungstoken der Client-App. |
category |
Erforderlich, String | Dieser Parameter gibt den Namen des Anwendungspakets der Client-App an, die die Nachricht gesendet hat. |
message_id |
Erforderlich, String | Dieser Parameter gibt die eindeutige ID der Nachricht an. |
data |
Optional, String | Mit diesem Parameter werden die Schlüssel/Wert-Paare der Nutzlast der Nachricht angegeben. |
Bestätigungsnachricht senden
In der folgenden Tabelle wird die ACK-Antwort beschrieben, an die der Anwendungsserver senden soll FCM als Antwort auf eine Upstream-Nachricht, die der Anwendungsserver empfangen hat.
Parameter | Nutzung | Beschreibung |
---|---|---|
to |
Erforderlich, String | Dieser Parameter gibt den Empfänger einer Antwortnachricht an. Der Wert muss ein Registrierungstoken der Client-App sein, die die vorgelagerte Nachricht gesendet hat. |
message_id |
Erforderlich, String | Dieser Parameter gibt an, für welche Nachricht die Antwort bestimmt ist. Der Wert muss
Den message_id -Wert aus der entsprechenden Upstream-Nachricht. |
message_type |
Erforderlich, String | Dieser Parameter gibt eine ack -Nachricht von einem Anwendungsserver an CCS an.
Für vorgelagerte Nachrichten sollte der Wert immer auf ack festgelegt werden. |
FCM Servernachrichten (XMPP)
Diese Nachricht wurde von FCM an einen Anwendungsserver gesendet. Im Folgenden sind die Haupttypen von Nachrichten aufgeführt, die FCM an den App-Server sendet:
- Kontrolle: Diese von CCS generierten Nachrichten weisen darauf hin, dass -Aktion vom Anwendungsserver erforderlich.
In der folgenden Tabelle werden die Felder beschrieben, die in den CCS-Nachrichten enthalten sind. an einen Anwendungsserver sendet.
Parameter | Nutzung | Beschreibung |
---|---|---|
Gemeinsames Feld | ||
message_type |
Erforderlich, String | Dieser Parameter gibt die Art der Nachricht an: Steuerelement. Wenn der Wert auf |
control_type |
Optionaler String | Dieser Parameter gibt die Art der von FCM gesendeten Kontrollnachricht an. Derzeit wird nur |