Dieses Dokument enthält eine Referenz für die HTTP-Syntax, die zum Weiterleiten von Nachrichten von Ihrem App-Server an Client-Apps über Firebase Cloud Messaging verwendet wird.
Wenn Sie das alte HTTP-Protokoll verwenden, muss Ihr App-Server alle HTTP-Anfragen an diesen Endpunkt weiterleiten:
https://fcm.googleapis.com/fcm/send
Die verfügbaren Parameter und Optionen fallen in die folgenden großen Kategorien:
Downstream-Nachrichtensyntax
In diesem Abschnitt wird die Syntax zum Senden von Downstream-Nachrichten und zum Interpretieren von HTTP-Antworten von Firebase Cloud Messaging beschrieben.
Downstream-HTTP-Nachrichten (JSON)
In der folgenden Tabelle sind die Ziele, Optionen und Nutzdaten für HTTP-JSON-Nachrichten aufgeführt.
Parameter | Verwendung | Beschreibung | |
---|---|---|---|
Ziele | |||
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 | |
registration_ids | Optional, Array von Zeichenfolgen | Dieser Parameter gibt den Empfänger einer Multicast-Nachricht an, einer Nachricht, die an mehr als ein Registrierungstoken gesendet wird. Der Wert sollte ein Array von Registrierungstokens sein, an die die Multicast-Nachricht gesendet werden soll. Das Array muss mindestens 1 und höchstens 1000 Registrierungstoken enthalten. Um eine Nachricht an ein einzelnes Gerät zu senden, verwenden Sie den Parameter Multicast-Nachrichten sind nur im HTTP-JSON-Format zulässig. | |
condition | Optional, Zeichenfolge | Dieser Parameter gibt einen logischen Ausdruck von Bedingungen an, die das Nachrichtenziel bestimmen. Unterstützte Bedingung: Thema, formatiert als „‚IhrThema‘ in Themen“. Bei diesem Wert wird die Groß-/Kleinschreibung nicht beachtet. Unterstützte Operatoren: | |
notification_key Veraltet | Optional, Zeichenfolge | Dieser Parameter ist veraltet. Verwenden Sie stattdessen | |
Optionen | |||
collapse_key | Optional, Zeichenfolge | Dieser Parameter identifiziert eine Gruppe von Nachrichten (z. B. mit Beachten Sie, dass es keine Garantie für die Reihenfolge gibt, 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“ . | |
restricted_package_ (nur Android) | Optional, Zeichenfolge | Dieser Parameter gibt den Paketnamen der Anwendung an, bei der die Registrierungstoken übereinstimmen müssen, um die Nachricht zu empfangen. | |
dry_run | Optional, boolesch | Wenn dieser Parameter auf Der Standardwert ist | |
Nutzlast | |||
data | Optional, Objekt | Dieser Parameter gibt die benutzerdefinierten Schlüssel-Wert-Paare der Nutzdaten der Nachricht an. Zum Beispiel mit Wenn die Nachricht auf Apple-Plattformen über APNs gesendet wird, stellt sie die benutzerdefinierten Datenfelder dar. Wenn es über FCM gesendet wird, wird es als Schlüsselwertwörterbuch in Unter Android würde 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 iOS 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. |
Downstream-HTTP-Nachrichten (einfacher Text)
In der folgenden Tabelle ist die Syntax für Ziele, Optionen und Nutzlast in nachgeschalteten HTTP-Nachrichten im Klartext aufgeführt.
Parameter | Verwendung | Beschreibung |
---|---|---|
Ziele | ||
registration_id | Erforderlich, Zeichenfolge | Dieser Parameter gibt die Client-Apps (Registrierungstokens) an, die die Nachricht empfangen. Multicast-Messaging (Senden an mehr als ein Registrierungstoken) ist nur im HTTP-JSON-Format zulässig. |
Optionen | ||
collapse_key | Optional, Zeichenfolge | Einzelheiten finden Sie in Tabelle 1 . |
time_to_live | Optional, Zahl | Einzelheiten finden Sie in Tabelle 1 . |
restricted_package_name | Optional, Zeichenfolge | Einzelheiten finden Sie in Tabelle 1 . |
dry_run | Optional, boolesch | Einzelheiten finden Sie in Tabelle 1 . |
Nutzlast | ||
data.<key> | Optional, Zeichenfolge | Dieser Parameter gibt die Schlüssel-Wert-Paare der Nutzlast der Nachricht an. Es gibt keine Begrenzung für die Anzahl der Schlüsselwertparameter, die Gesamtgröße der Nachricht ist jedoch auf 4.000 Byte begrenzt. In Android würde beispielsweise 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. |
Interpretieren einer Downstream-Nachrichtenantwort
Der App-Server sollte sowohl den Header als auch den Text der Nachrichtenantwort auswerten, um die von FCM gesendete Nachrichtenantwort zu interpretieren. Die folgende Tabelle beschreibt die möglichen Antworten.
Antwort | Beschreibung |
---|---|
200 | Die Nachricht wurde erfolgreich verarbeitet. Der Antworttext enthält weitere Details zum Nachrichtenstatus, sein Format hängt jedoch davon ab, ob die Anfrage JSON oder Nur-Text war. Weitere Einzelheiten finden Sie in Tabelle 5 . |
400 | Gilt nur für JSON-Anfragen. Zeigt an, dass die Anfrage nicht als JSON geparst werden konnte oder ungültige Felder enthielt (z. B. die Übergabe einer Zeichenfolge an der Stelle, an der eine Zahl erwartet wurde). Der genaue Fehlergrund wird in der Antwort beschrieben und das Problem sollte behoben werden, bevor die Anfrage erneut versucht werden kann. |
401 | Bei der Authentifizierung des Absenderkontos ist ein Fehler aufgetreten. |
5xx | Fehler im Bereich 500–599 (z. B. 500 oder 503) weisen darauf hin, dass beim Versuch, die Anforderung zu verarbeiten, ein interner Fehler im FCM-Backend aufgetreten ist oder dass der Server vorübergehend nicht verfügbar ist (z. B. aufgrund von Zeitüberschreitungen). Der Absender muss es später erneut versuchen und dabei alle in der Antwort enthaltenen Retry-After Header berücksichtigen. Anwendungsserver müssen einen exponentiellen Backoff implementieren. |
In der folgenden Tabelle sind die Felder in einem Downstream-Nachrichtenantworttext (JSON) aufgeführt.
Parameter | Verwendung | Beschreibung |
---|---|---|
multicast_id | Erforderlich, Anzahl | Eindeutige ID (Nummer), die die Multicast-Nachricht identifiziert. |
success | Erforderlich, Anzahl | Anzahl der Nachrichten, die ohne Fehler verarbeitet wurden. |
failure | Erforderlich, Anzahl | Anzahl der Nachrichten, die nicht verarbeitet werden konnten. |
results | Erforderlich, Array von Objekten | Array von Objekten, die den Status der verarbeiteten Nachrichten darstellen. Die Objekte werden in der gleichen Reihenfolge wie die Anfrage aufgelistet (d. h. für jede Registrierungs-ID in der Anfrage wird das Ergebnis im gleichen Index in der Antwort aufgeführt).
|
Parameter | Verwendung | Beschreibung |
---|---|---|
message_id | Optional, Zahl | Die Themennachrichten-ID, wenn FCM die Anfrage erfolgreich empfangen hat und versucht, sie an alle abonnierten Geräte zuzustellen. |
error | Optional, Zeichenfolge | Beim Verarbeiten der Nachricht ist ein Fehler aufgetreten. Die möglichen Werte finden Sie in Tabelle 9 . |
Parameter | Verwendung | Beschreibung |
---|---|---|
id | Erforderlich, Zeichenfolge | Dieser Parameter gibt die eindeutige Nachrichten-ID an, die FCM erfolgreich verarbeitet hat. |
registration_id | Optional, Zeichenfolge | Dieser Parameter gibt das Registrierungstoken für die Client-App an, an die die Nachricht verarbeitet und gesendet wurde. |
Parameter | Verwendung | Beschreibung |
---|---|---|
Error | Erforderlich, Zeichenfolge | Dieser Parameter gibt den Fehlerwert bei der Verarbeitung der Nachricht für den Empfänger an. Einzelheiten finden Sie in Tabelle 9 . |
Fehlerantwortcodes für Downstream-Nachrichten
In der folgenden Tabelle sind die Fehlerantwortcodes für Downstream-Nachrichten aufgeführt.
Fehler | HTTP-Code | Empfohlene Maßnahme |
---|---|---|
Fehlendes Registrierungstoken | 200 + Fehler: Fehlende Registrierung | Ü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ültiges Registrierungstoken | 200 + Fehler: Ungültige Registrierung | Ü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 Firebase Notifications erhält. Schneiden Sie keine Zeichen ab und fügen Sie keine weiteren Zeichen hinzu. |
Nicht registriertes Gerät | 200 + Fehler: NotRegistered | Ein vorhandener Registrierungstoken kann in einer Reihe von Szenarien seine Gültigkeit verlieren, darunter:
|
Ungültiger Paketname | 200 + Fehler:InvalidPackageName | Stellen Sie sicher, dass die Nachricht an ein Registrierungstoken adressiert war, dessen Paketname mit dem in der Anfrage übergebenen Wert übereinstimmt. |
Authentifizierungsfehler | 401 | Das zum Senden einer Nachricht verwendete Absenderkonto konnte nicht authentifiziert werden. Mögliche Ursachen sind:
|
Nicht übereinstimmender Absender | 200 + Fehler: MismatchSenderId | 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 | 400 | Ü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). |
Ungültige Parameter | 400 + Fehler: Ungültige Parameter | Überprüfen Sie, ob die bereitgestellten Parameter den richtigen Namen und Typ haben. |
Nachricht zu groß | 200 + Fehler:MessageTooBig | 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 im Fall von Nachrichten zu Themen. Dazu gehören sowohl die Schlüssel als auch die Werte. |
Ungültiger Datenschlüssel | 200 + Fehler: Ungültiger Datenschlüssel | Stellen Sie sicher, dass die Nutzdaten keinen Schlüssel (z. B. from oder 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 | 200 + Fehler:InvalidTtl | Ü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. |
Auszeit | 5xx oder 200 + Fehler: Nicht verfügbar | Der Server konnte die Anfrage nicht rechtzeitig verarbeiten. Versuchen Sie dieselbe Anfrage erneut, aber Sie müssen:
Absender, die Probleme verursachen, laufen Gefahr, auf die schwarze Liste gesetzt zu werden. |
interner Serverfehler | 500 oder 200 + Fehler:InternalServerError | Beim Versuch, die Anfrage zu verarbeiten, ist auf dem Server ein Fehler aufgetreten. Sie können dieselbe Anfrage erneut versuchen, indem Sie die unter „Zeitüberschreitung“ aufgeführten Anforderungen erfüllen (siehe Zeile oben). Wenn der Fehler weiterhin besteht, wenden Sie sich bitte an den Firebase-Support . |
Gerätenachrichtenrate überschritten | 200 + Fehler: DeviceMessageRate Übertroffen | Die Nachrichtenrate an ein bestimmtes Gerät ist zu hoch. Wenn eine Apple-App Nachrichten mit einer Geschwindigkeit sendet, die die APN-Grenzwerte überschreitet, wird möglicherweise diese Fehlermeldung angezeigt Reduzieren Sie die Anzahl der an dieses Gerät gesendeten Nachrichten und versuchen Sie den Versand mithilfe eines exponentiellen Backoffs erneut. |
Themen-Nachrichtenrate überschritten | 200 + Fehler: ThemenNachrichtRate Übertroffen | Die Nachrichtenrate an Abonnenten zu einem bestimmten Thema ist zu hoch. Reduzieren Sie die Anzahl der für dieses Thema gesendeten Nachrichten und verwenden Sie den exponentiellen Backoff, um den Versand erneut zu versuchen. |
Ungültige APNs-Anmeldeinformationen | 200 + Fehler: Ungültiges ApnsCredential | Eine an ein Apple-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. |
Gerätegruppenverwaltung
In der folgenden Tabelle sind die Schlüssel zum Erstellen von Gerätegruppen sowie zum Hinzufügen und Entfernen von Mitgliedern aufgeführt. Weitere Informationen finden Sie im Handbuch für Ihre Plattform, iOS+ oder Android .
Parameter | Verwendung | Beschreibung |
---|---|---|
operation | Erforderlich, Zeichenfolge | Der auszuführende Vorgang. Gültige Werte sind create , add und remove . |
notification_key_name | Erforderlich, Zeichenfolge | Der benutzerdefinierte Name der Gerätegruppe, die erstellt oder geändert werden soll. |
notification_key | Erforderlich (außer für den create , string | Eindeutiger Bezeichner der Gerätegruppe. Dieser Wert wird in der Antwort für einen erfolgreichen create zurückgegeben und ist für alle nachfolgenden Vorgänge für die Gerätegruppe erforderlich. |
registration_ids | Erforderlich, Array von Zeichenfolgen | Die Geräte-Tokens, die hinzugefügt oder entfernt werden sollen. Wenn Sie alle vorhandenen Registrierungstoken aus einer Gerätegruppe entfernen, löscht FCM die Gerätegruppe. |