Dieses Dokument enthält eine Referenz für die XMPP-Syntax, die zum Übertragen von Nachrichten zwischen Ihrem App-Server, Client-Apps und Firebase Cloud Messaging (FCM) verwendet wird. Ihr App-Server muss eine Verbindung zu diesen Endpunkten herstellen:
// Production fcm-xmpp.googleapis.com:5235 // Testing fcm-xmpp.googleapis.com:5236
Die verfügbaren Parameter und Optionen fallen in diese Kategorien:
- Downstream-Nachrichtensyntax
- Fehlerantwortcodes für Downstream-Nachrichten
- Upstream-Nachrichtensyntax
- FCM-Steuernachrichten
Downstream-Nachrichtensyntax
In diesem Abschnitt wird die Syntax zum Senden von Downstream-Nachrichten beschrieben.
Downstream-XMPP-Nachrichten (JSON)
In der folgenden Tabelle sind die Ziele, Optionen und Nutzdaten für XMPP-JSON-Nachrichten aufgeführt.
Parameter | Verwendung | Beschreibung | |
---|---|---|---|
Ziel | |||
to | Optional, Zeichenfolge | Dieser Parameter gibt den Empfänger einer Nachricht an. Der Wert kann das Registrierungstoken eines Geräts, der Benachrichtigungsschlüssel einer Gerätegruppe oder ein einzelnes Thema (mit dem Präfix | |
condition | Optional, Zeichenfolge | Dieser Parameter gibt einen logischen Ausdruck von Bedingungen an, der das Nachrichtenziel bestimmt. Unterstützte Bedingung: Thema, formatiert als „‚IhrThema‘ in Themen“. Bei diesem Wert wird die Groß-/Kleinschreibung nicht beachtet. Unterstützte Operatoren: | |
Optionen | |||
message_id | Erforderlich, Zeichenfolge | Dieser Parameter identifiziert eine Nachricht in einer XMPP-Verbindung eindeutig. | |
collapse_key | Optional, Zeichenfolge | 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 jeweils maximal 4 verschiedene Minimierungstasten zulässig. Das bedeutet, dass FCM gleichzeitig 4 verschiedene Nachrichten pro Client-App speichern kann. Wenn Sie diese Zahl überschreiten, gibt es keine Garantie dafür, welche 4 Klappschlüssel FCM behält. | |
priority | Optional, Zeichenfolge | Legt die Priorität der Nachricht fest. Gültige Werte sind „normal“ und „hoch“. Auf Apple-Plattformen entsprechen diese den APNs-Prioritäten 5 und 10. Standardmäßig werden Benachrichtigungsnachrichten mit hoher Priorität und Datennachrichten mit normaler Priorität gesendet. Die normale Priorität optimiert den Batterieverbrauch der Client-App und sollte verwendet werden, es sei denn, eine sofortige Lieferung ist erforderlich. Bei Nachrichten mit normaler Priorität empfängt die App die Nachricht möglicherweise mit unbestimmter Verzögerung. Wenn eine Nachricht mit hoher Priorität gesendet wird, wird sie sofort gesendet und die App kann eine Benachrichtigung anzeigen. | |
content_available | Optional, boolesch | Auf Apple-Plattformen verwenden Sie dieses Feld, um den in der APNs-Nutzlast | |
mutable_content | Optional, JSON-Boolescher Wert | Auf Apple-Plattformen verwenden Sie dieses Feld, um | |
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 Supportdauer beträgt 4 Wochen, der Standardwert beträgt 4 Wochen. Weitere Informationen finden Sie unter „Lebensdauer 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 Nutzdaten der Nachricht an. Zum Beispiel mit Wenn die Nachricht auf Apple-Plattformen über APNs übermittelt wird, stellt sie die benutzerdefinierten Datenfelder dar. Wenn es von FCM bereitgestellt wird, wird es als Schlüsselwertwörterbuch in Unter Android führt dies zu einem zusätzlich benannten Intent- Der Schlüssel sollte kein reserviertes Wort sein („from“, „message_type“ oder ein Wort, das mit „google“ oder „gcm“ beginnt). Verwenden Sie keines der in dieser Tabelle definierten Wörter (z. B. Werte in Zeichenfolgentypen werden empfohlen. Sie müssen Werte in Objekten oder anderen Datentypen, die keine Zeichenfolgen sind (z. B. ganze Zahlen oder boolesche Werte), in Zeichenfolgen konvertieren. | |
notification | Optional, Objekt | Dieser Parameter gibt die vordefinierten, für den Benutzer sichtbaren Schlüssel-Wert-Paare der Benachrichtigungsnutzlast an. Weitere Informationen finden Sie unter Unterstützung der Benachrichtigungsnutzlast. Weitere Informationen zu Optionen für Benachrichtigungsnachrichten und Datennachrichten finden Sie unter Nachrichtentypen . Wenn eine Benachrichtigungsnutzlast bereitgestellt wird oder die Option „ content_available für eine Nachricht an ein Apple-Gerät auf „ true gesetzt ist, wird die Nachricht über APNs gesendet , andernfalls über FCM. |
Unterstützung der 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 | Verwendung | Beschreibung |
---|---|---|
title | Optional, Zeichenfolge | Der Titel der Benachrichtigung. Dieses Feld ist auf Telefonen und Tablets nicht sichtbar. |
body | Optional, Zeichenfolge | Der Textkörper der Benachrichtigung. |
sound | Optional, Zeichenfolge | Der Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt. Zeichenfolge, die Sounddateien im Hauptpaket der Client-App oder im Ordner |
badge | Optional, Zeichenfolge | Der Wert des Abzeichens auf dem App-Symbol auf dem Startbildschirm. Wenn nicht angegeben, wird das Abzeichen nicht geändert. Bei der Einstellung |
click_action | Optional, Zeichenfolge | Die mit einem Benutzerklick auf die Benachrichtigung verbundene Aktion. Entspricht der |
subtitle | Optional, Zeichenfolge | Der Untertitel der Benachrichtigung. |
body_loc_key | Optional, Zeichenfolge | Der Schlüssel zur Textzeichenfolge in den Zeichenfolgenressourcen der App, der zum Lokalisieren des Textkörpers an die aktuelle Lokalisierung des Benutzers verwendet werden soll. Entspricht dem Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Your Remote Notifications . |
body_loc_args | Optional, JSON-Array als String | Variable Zeichenfolgenwerte, die anstelle der Formatbezeichner in Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Your Remote Notifications . |
title_loc_key | Optional, Zeichenfolge | Der Schlüssel zur Titelzeichenfolge in den Zeichenfolgenressourcen der App, der zum Lokalisieren des Titeltexts an die aktuelle Lokalisierung des Benutzers verwendet werden soll. Entspricht dem Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Your Remote Notifications . |
title_loc_args | Optional, JSON-Array als String | Variable Zeichenfolgenwerte, die anstelle der Formatbezeichner in Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Your Remote Notifications . |
Parameter | Verwendung | Beschreibung |
---|---|---|
title | Optional, Zeichenfolge | Der Titel der Benachrichtigung. |
body | Optional, Zeichenfolge | Der Textkörper der Benachrichtigung. |
android_channel_id | Optional, Zeichenfolge | Die Kanal-ID der Benachrichtigung (neu in Android O). Die App muss einen Kanal mit dieser Kanal-ID erstellen, bevor eine Benachrichtigung mit dieser Kanal-ID empfangen wird. Wenn Sie diese Kanal-ID nicht in der Anfrage senden oder die bereitgestellte Kanal-ID noch nicht von der App erstellt wurde, verwendet FCM die im App-Manifest angegebene Kanal-ID. |
icon | Optional, Zeichenfolge | Das Symbol der Benachrichtigung. Setzt das Benachrichtigungssymbol für die zeichnbare Ressource |
sound | Optional, Zeichenfolge | Der Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt. Unterstützt |
tag | Optional, Zeichenfolge | Bezeichner, der zum Ersetzen vorhandener Benachrichtigungen in der Benachrichtigungsleiste verwendet wird. Wenn nicht angegeben, erstellt jede Anfrage eine neue Benachrichtigung. Wenn angegeben und bereits eine Benachrichtigung mit demselben Tag angezeigt wird, ersetzt die neue Benachrichtigung die vorhandene in der Benachrichtigungsleiste. |
color | Optional, Zeichenfolge | Die Symbolfarbe der Benachrichtigung, ausgedrückt im |
click_action | Optional, Zeichenfolge | Die mit einem Benutzerklick auf die Benachrichtigung verbundene Aktion. Wenn angegeben, wird eine Aktivität mit einem passenden Absichtsfilter gestartet, wenn ein Benutzer auf die Benachrichtigung klickt. |
body_loc_key | Optional, Zeichenfolge | Der Schlüssel zur Textzeichenfolge in den Zeichenfolgenressourcen der App, der zum Lokalisieren des Textkörpers an die aktuelle Lokalisierung des Benutzers verwendet werden soll. Weitere Informationen finden Sie unter String-Ressourcen . |
body_loc_args | Optional, JSON-Array als String | Variable Zeichenfolgenwerte, die anstelle der Formatbezeichner in Weitere Informationen finden Sie unter Formatierung und Stil . |
title_loc_key | Optional, Zeichenfolge | Der Schlüssel zur Titelzeichenfolge in den Zeichenfolgenressourcen der App, der zum Lokalisieren des Titeltexts an die aktuelle Lokalisierung des Benutzers verwendet werden soll. Weitere Informationen finden Sie unter String-Ressourcen . |
title_loc_args | Optional, JSON-Array als String | Variable Zeichenfolgenwerte, die anstelle der Formatbezeichner in Weitere Informationen finden Sie unter Formatierung und Stil . |
Parameter | Verwendung | Beschreibung |
---|---|---|
title | Optional, Zeichenfolge | Der Titel der Benachrichtigung. |
body | Optional, Zeichenfolge | Der Textkörper der Benachrichtigung. |
icon | Optional, Zeichenfolge | Die URL, die für das Symbol der Benachrichtigung verwendet werden soll. |
click_action | Optional, Zeichenfolge | Die mit einem Benutzerklick auf die Benachrichtigung verbundene Aktion. Für alle URL-Werte ist HTTPS erforderlich. |
Interpretieren Sie eine Downstream-XMPP-Nachrichtenantwort
In der folgenden Tabelle sind die Felder aufgeführt, die in einer Downstream-XMPP-Nachrichtenantwort angezeigt werden.
Parameter | Verwendung | Beschreibung |
---|---|---|
from | Erforderlich, Zeichenfolge | Dieser Parameter gibt an, wer diese Antwort gesendet hat. Der Wert ist das Registrierungstoken der Client-App. |
message_id | Erforderlich, Zeichenfolge | Dieser Parameter identifiziert eine Nachricht in einer XMPP-Verbindung eindeutig. Der Wert ist eine Zeichenfolge, die die zugehörige Nachricht eindeutig identifiziert. |
message_type | Erforderlich, Zeichenfolge | Dieser Parameter gibt eine Wenn der Wert auf |
error | Optional, Zeichenfolge | Dieser Parameter gibt einen Fehler im Zusammenhang mit der Downstream-Nachricht an. Es wird gesetzt, wenn der message_type nack ist. Einzelheiten finden Sie in Tabelle 4 . |
error_description | Optional, Zeichenfolge | Dieser Parameter stellt beschreibende Informationen zum Fehler bereit. Es wird gesetzt, wenn der message_type nack ist. |
Fehlerantwortcodes für Downstream-Nachrichten
In der folgenden Tabelle sind die Fehlerantwortcodes für Downstream-Nachrichten aufgeführt.
Fehler | XMPP-Code | Empfohlene Maßnahme |
---|---|---|
Fehlendes Registrierungstoken | INVALID_JSON | Überprüfen Sie, ob die Anfrage ein Registrierungstoken enthält (in der registration_id in einer Nur-Text-Nachricht oder im Feld „ to oder „ registration_ids in JSON). |
Ungültige APNs-Registrierung | INVALID_JSON | Überprüfen Sie bei iOS-Registrierungen, ob die Registrierungsanfrage des Clients ein gültiges APNs-Token und eine gültige Anwendungs-ID enthält. |
Ungültiges Registrierungstoken | BAD_REGISTRATION | Überprüfen Sie das Format des Registrierungstokens, das Sie an den Server übergeben. Stellen Sie sicher, dass es mit dem Registrierungstoken übereinstimmt, das die Client-App durch die Registrierung bei FCM erhält. Schneiden Sie keine Zeichen ab und fügen Sie keine weiteren Zeichen hinzu. |
Nicht registriertes Gerät | DEVICE_UNREGISTERED | Ein vorhandener Registrierungstoken kann in einer Reihe von Szenarien seine Gültigkeit verlieren, darunter:
|
Nicht übereinstimmender Absender | SENDER_ID_MISMATCH | Ein Registrierungstoken ist an eine bestimmte Gruppe von Absendern gebunden. Wenn sich eine Client-App für FCM registriert, muss sie angeben, welche Absender Nachrichten senden dürfen. Sie sollten eine dieser Absender-IDs verwenden, wenn Sie Nachrichten an die Client-App senden. Wenn Sie zu einem anderen Absender wechseln, funktionieren die vorhandenen Registrierungstokens nicht. |
Ungültiger JSON | INVALID_JSON | Überprüfen Sie, ob die JSON-Nachricht ordnungsgemäß formatiert ist und gültige Felder enthält (stellen Sie beispielsweise sicher, dass der richtige Datentyp übergeben wird). |
Nachricht zu groß | INVALID_JSON | Stellen Sie sicher, dass die Gesamtgröße der in einer Nachricht enthaltenen Nutzdaten die FCM-Grenzwerte nicht überschreitet: 4096 Byte für die meisten Nachrichten oder 2048 Byte bei Nachrichten zu Themen. Dazu gehören sowohl die Schlüssel als auch die Werte. |
Ungültiger Datenschlüssel | INVALID_JSON | Stellen Sie sicher, dass die Nutzdaten keinen Schlüssel (z. B. from , gcm oder einen beliebigen Wert mit dem Präfix google ) enthalten, der intern von FCM verwendet wird. Beachten Sie, dass einige Wörter (z. B. collapse_key ) auch von FCM verwendet werden, aber in der Nutzlast zulässig sind. In diesem Fall wird der Nutzlastwert durch den FCM-Wert überschrieben. |
Ungültige Lebenszeit | INVALID_JSON | Überprüfen Sie, ob der in time_to_live verwendete Wert eine Ganzzahl ist, die eine Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen) darstellt. |
Ungültige ACK-Nachricht | BAD_ACK | Überprüfen Sie, ob die ack richtig formatiert ist, bevor Sie es erneut versuchen. Einzelheiten finden Sie in Tabelle 6 . |
Auszeit | SERVICE_UNAVAILABLE | Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Versuchen Sie dieselbe Anfrage erneut, aber Sie müssen:
Hinweis: Absender, die Probleme verursachen, laufen Gefahr, auf die schwarze Liste gesetzt zu werden. |
interner Serverfehler | INTERNAL_SERVER_ | Beim Versuch, die Anfrage zu verarbeiten, ist auf dem Server ein Fehler aufgetreten. Sie können dieselbe Anfrage erneut versuchen, indem Sie die unter „Timeout“ aufgeführten Anforderungen erfüllen (siehe Zeile oben). |
Gerätenachrichtenrate überschritten | DEVICE_MESSAGE_RATE | Die Nachrichtenrate an ein bestimmtes Gerät ist zu hoch. Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und versuchen Sie nicht sofort erneut, sie an dieses Gerät zu senden. |
Themen-Nachrichtenrate überschritten | TOPICS_MESSAGE_RATE | Die Nachrichtenrate an Abonnenten zu einem bestimmten Thema ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und versuchen Sie nicht sofort erneut, sie zu senden. |
Anschluss Entleerung | CONNECTION_DRAINING | Die Nachricht konnte nicht verarbeitet werden, da die Verbindung erschöpft ist. Dies liegt daran, dass FCM in regelmäßigen Abständen eine Verbindung schließen muss, um einen Lastausgleich durchzuführen. Wiederholen Sie die Nachricht über eine andere XMPP-Verbindung. |
Ungültige APNs-Anmeldeinformationen | INVALID_APNS_CREDENTIAL | Eine an ein iOS-Gerät gerichtete Nachricht konnte nicht gesendet werden, da der erforderliche APNs-Authentifizierungsschlüssel nicht hochgeladen wurde oder abgelaufen ist. Überprüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionsnachweise. |
Authentifizierung fehlgeschlagen | AUTHENTICATION_FAILED | Die Authentifizierung bei externen Push-Diensten ist fehlgeschlagen. Überprüfen Sie, ob Sie die richtigen Web-Push-Zertifikate verwenden. |
Upstream-Nachrichtensyntax
Eine Upstream-Nachricht ist eine Nachricht, die die Client-App an den App-Server sendet. Derzeit unterstützt nur XMPP Upstream-Messaging. Weitere Informationen zum Senden von Nachrichten von Client-Apps finden Sie in der Dokumentation Ihrer Plattform.
Interpretieren einer Upstream-XMPP-Nachricht
In der folgenden Tabelle werden die Felder in der XMPP-Zeilengruppe beschrieben, die von FCM als Reaktion auf Upstream-Nachrichtenanforderungen von Client-Apps generiert werden.
Parameter | Verwendung | Beschreibung |
---|---|---|
from | Erforderlich, Zeichenfolge | Dieser Parameter gibt an, wer die Nachricht gesendet hat. Der Wert ist das Registrierungstoken der Client-App. |
category | Erforderlich, Zeichenfolge | Dieser Parameter gibt den Anwendungspaketnamen der Client-App an, die die Nachricht gesendet hat. |
message_id | Erforderlich, Zeichenfolge | Dieser Parameter gibt die eindeutige ID der Nachricht an. |
data | Optional, Zeichenfolge | Dieser Parameter gibt die Schlüssel-Wert-Paare der Nutzlast der Nachricht an. |
Senden einer ACK-Nachricht
In der folgenden Tabelle wird die ACK-Antwort beschrieben, die der App-Server als Reaktion auf eine Upstream-Nachricht, die der App-Server empfangen hat, an FCM senden soll.
Parameter | Verwendung | Beschreibung |
---|---|---|
to | Erforderlich, Zeichenfolge | Dieser Parameter gibt den Empfänger einer Antwortnachricht an. Der Wert muss ein Registrierungstoken der Client-App sein, die die Upstream-Nachricht gesendet hat. |
message_id | Erforderlich, Zeichenfolge | Dieser Parameter gibt an, für welche Nachricht die Antwort gedacht ist. Der Wert muss der message_id Wert der entsprechenden Upstream-Nachricht sein. |
message_type | Erforderlich, Zeichenfolge | Dieser Parameter gibt eine ack von einem App-Server an CCS an. Für Upstream-Nachrichten sollte es immer auf ack gesetzt sein. |
FCM-Servernachrichten (XMPP)
Dies ist eine Nachricht, die von FCM an einen App-Server gesendet wird. Hier sind die wichtigsten Arten von Nachrichten, die FCM an den App-Server sendet:
- Kontrolle: Diese von CCS generierten Nachrichten weisen darauf hin, dass eine Aktion vom App-Server erforderlich ist.
In der folgenden Tabelle werden die Felder beschrieben, die in den Nachrichten enthalten sind, die CCS an einen App-Server sendet.
Parameter | Verwendung | Beschreibung |
---|---|---|
Gemeinsames Feld | ||
message_type | Erforderlich, Zeichenfolge | Dieser Parameter gibt den Typ der Nachricht an: Steuerung. Wenn es auf |
control_type | Optional, Zeichenfolge | Dieser Parameter gibt den Typ der vom FCM gesendeten Steuernachricht an. Derzeit wird nur |