Dieses Dokument enthält eine Referenz für die HTTP-Syntax, mit der Nachrichten über Firebase Cloud Messaging von einem Anwendungsserver an Client-Apps weitergeleitet werden.
Wenn Sie das Legacy-HTTP-Protokoll verwenden, muss Ihr Anwendungsserver alle HTTP-Anfragen an diesen Endpunkt weiterleiten:
https://fcm.googleapis.com/fcm/send
Die verfügbaren Parameter und Optionen lassen sich in folgende Kategorien einteilen:
Syntax von nachgelagerten Nachrichten
Dieser Abschnitt enthält die Syntax für das Senden von Downstream-Nachrichten und die Interpretation von HTTP-Antworten von Firebase Cloud Messaging.
Downstream-HTTP-Nachrichten (JSON)
In der folgenden Tabelle sind die Ziele, Optionen und Nutzlast für HTTP-JSON-Nachrichten aufgeführt.
Parameter | Nutzung | Beschreibung | |
---|---|---|---|
Ziele | |||
to |
Optional, String |
Dieser Parameter gibt den Empfänger einer Nachricht an.
Der Wert kann ein Registrierungstoken eines Geräts, ein Benachrichtigungsschlüssel einer Gerätegruppe oder ein einzelnes Thema (mit dem Präfix |
|
registration_ids | Optional, String-Array |
Dieser Parameter gibt den Empfänger einer Multicast-Nachricht an, einer Nachricht, die an mehrere Registrierungstokens gesendet wird.
Der Wert sollte ein Array von Registrierungstokens sein, an das die Multicast-Nachricht gesendet werden soll. Das Array muss mindestens 1 und darf höchstens 1.000 Registrierungstokens enthalten. Verwende den Parameter Multicast-Nachrichten sind nur mit dem HTTP-JSON-Format zulässig. |
|
condition |
Optional, String | Dieser Parameter gibt einen logischen Ausdruck von Bedingungen an, die das Nachrichtenziel bestimmen. Unterstützte Bedingung: Thema, formatiert in Themen als „yourTopic“. Bei diesem Wert wird die Groß-/Kleinschreibung nicht berücksichtigt. Unterstützte Operatoren: |
|
notification_key Eingestellt |
Optional, String | Dieser Parameter wurde eingestellt. Verwenden Sie stattdessen |
|
Optionen | |||
collapse_key |
Optional, String | Dieser Parameter identifiziert eine Gruppe von Nachrichten (z.B. mit Beachten Sie, dass die Reihenfolge, in der die Nachrichten gesendet werden, nicht garantiert werden kann. Hinweis: Es sind jeweils maximal vier verschiedene Minimierungsschlüssel zulässig. Das bedeutet, dass FCM pro Clientanwendung gleichzeitig vier verschiedene Nachrichten speichern kann. Wenn Sie diese Zahl überschreiten, gibt es keine Garantie, welche vier Minimierungsschlüssel FCM beibehalten kann. |
|
priority |
Optional, String | Legt die Priorität der Nachricht fest. Gültige Werte sind „normal“ und „high“. Auf Apple-Plattformen entsprechen diese den APNs-Prioritäten 5 und 10. Benachrichtigungen werden standardmäßig mit hoher Priorität und Datennachrichten mit normaler Priorität gesendet. Mit der normalen Priorität wird der Akkuverbrauch der Client-App optimiert. Diese Priorität sollte nur verwendet werden, wenn eine sofortige Bereitstellung erforderlich ist. Bei Nachrichten mit normaler Priorität erhält die Anwendung die Nachricht möglicherweise mit einer nicht angegebenen 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 |
|
mutable_content |
Optional, boolesch JSON | Auf Apple-Plattformen verwenden Sie dieses Feld, um |
|
time_to_live |
Optional, Nummer | 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 ist 4 Wochen. Weitere Informationen finden Sie unter Lebensdauer einer Nachricht festlegen. |
|
restricted_package_
(nur Android) |
Optional, String | Dieser Parameter gibt den Paketnamen der Anwendung an, bei der die Registrierungstokens ü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 Nutzlast der Nachricht an. Zum Beispiel mit Wenn die Nachricht auf Apple-Plattformen über APNs gesendet wird, stellt sie die benutzerdefinierten Datenfelder dar. Beim Senden über FCM wird es in Unter Android würde dies zu einem Intent-Extra mit dem Namen Der Schlüssel darf 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 Stringtypen werden empfohlen. Werte in Objekten oder anderen Nicht-String-Datentypen (z.B. Ganzzahlen oder boolesche Werte) müssen in Strings konvertiert werden. |
|
notification |
Optional, Objekt | Dieser Parameter gibt die vordefinierten, für den Nutzer sichtbaren Schlüssel/Wert-Paare der Benachrichtigungsnutzlast an. Weitere Informationen findest du unter Unterstützung der Benachrichtigungsnutzlast.
Weitere Informationen zu den Optionen für Benachrichtigungs- und Datennachrichten finden Sie unter
Nachrichtentypen. Wenn eine Benachrichtigungsnutzlast angegeben ist 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 wird sie über FCM gesendet.
|
Unterstützung der Nutzlast von Benachrichtigungen
In den folgenden Tabellen sind die vordefinierten Schlüssel zum Erstellen von Benachrichtigungen für iOS und Android aufgeführt.
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optional, String |
Der Titel der Benachrichtigung. Dieses Feld ist auf Smartphones und Tablets nicht sichtbar. |
body |
Optional, String |
Der Text der Benachrichtigung. |
sound |
Optional, String |
Der Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt.
String, der Audiodateien im Haupt-Bundle der Clientanwendung oder im Ordner |
badge |
Optional, String |
Der Wert des Logos auf dem App-Symbol auf dem Startbildschirm. Wenn keine Angabe erfolgt, wird das Logo nicht geändert.
Wenn der Wert auf |
click_action |
Optional, String |
Die Aktion, die einem Nutzerklick auf die Benachrichtigung zugeordnet ist.
Entspricht |
subtitle |
Optional, String |
Der Untertitel der Benachrichtigung |
body_loc_key |
Optional, String |
Der Schlüssel für den Textstring in den Stringressourcen der App, der zum Lokalisieren des Textes für die aktuelle Lokalisierung des Nutzers verwendet werden soll.
Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Remote Notifications. |
body_loc_args |
Optional: JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in
Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Remote Notifications. |
title_loc_key |
Optional, String |
Der Schlüssel für den Titelstring in den Stringressourcen der App, der zum Lokalisieren des Titeltexts für die aktuelle Lokalisierung des Nutzers verwendet werden soll.
Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Remote Notifications. |
title_loc_args |
Optional: JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in
Entspricht Weitere Informationen finden Sie unter Payload Key Reference und Localizing the Content of Remote Notifications. |
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optional, String |
Der Titel der Benachrichtigung. |
body |
Optional, String |
Der Text der Benachrichtigung. |
android_channel_id |
Optional, String |
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 angegebene Kanal-ID noch nicht von der App erstellt wurde, verwendet FCM die im App-Manifest angegebene Kanal-ID. |
icon |
Optional, String |
Das Benachrichtigungssymbol.
Legt das Benachrichtigungssymbol für die Drawable-Ressource |
sound |
Optional, String |
Der Ton, der abgespielt wird, wenn das Gerät die Benachrichtigung empfängt.
Unterstützt |
tag |
Optional, String |
Kennung, mit der vorhandene Benachrichtigungen auf der Benachrichtigungsleiste ersetzt werden. Wenn keine Angabe erfolgt, wird für jede Anfrage eine neue Benachrichtigung erstellt. Wenn angegeben und bereits eine Benachrichtigung mit demselben Tag angezeigt wird, ersetzt die neue Benachrichtigung die vorhandene Benachrichtigung auf der Benachrichtigungsleiste. |
color |
Optional, String |
Die Farbe des Benachrichtigungssymbols im |
click_action |
Optional, String |
Die Aktion, die einem Nutzerklick auf die Benachrichtigung zugeordnet ist. Wenn angegeben, wird eine Aktivität mit einem übereinstimmenden Intent-Filter gestartet, wenn ein Nutzer auf die Benachrichtigung klickt. |
body_loc_key |
Optional, String |
Der Schlüssel für den Textstring in den Stringressourcen der App, der zum Lokalisieren des Textes für die aktuelle Lokalisierung des Nutzers verwendet werden soll. Weitere Informationen finden Sie unter Stringressourcen. |
body_loc_args |
Optional: JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in Weitere Informationen finden Sie unter Formatierung und Stile. |
title_loc_key |
Optional, String |
Der Schlüssel für den Titelstring in den Stringressourcen der App, der zum Lokalisieren des Titeltexts für die aktuelle Lokalisierung des Nutzers verwendet werden soll. Weitere Informationen finden Sie unter Stringressourcen. |
title_loc_args |
Optional: JSON-Array als String |
Variable Stringwerte, die anstelle der Formatspezifizierer in Weitere Informationen finden Sie unter Formatierung und Stile. |
Parameter | Nutzung | Beschreibung |
---|---|---|
title |
Optional, String |
Der Titel der Benachrichtigung. |
body |
Optional, String |
Der Text der Benachrichtigung. |
icon |
Optional, String |
Die URL, die für das Benachrichtigungssymbol verwendet werden soll. |
click_action |
Optional, String |
Die Aktion, die einem Nutzerklick auf die Benachrichtigung zugeordnet ist. Für alle URL-Werte ist HTTPS erforderlich. |
Downstream-HTTP-Nachrichten (Nur-Text)
Die folgende Tabelle enthält die Syntax für Ziele, Optionen und Nutzlast in Downstream-HTTP-Nachrichten als Nur-Text.
Parameter | Nutzung | Beschreibung |
---|---|---|
Ziele | ||
registration_id |
Erforderlich, String | Dieser Parameter gibt die Client-Apps (Registrierungstokens) an, die die Nachricht empfangen. Multicast-Messaging, das an mehrere Registrierungstokens gesendet wird, ist nur im HTTP-JSON-Format zulässig. |
Optionen | ||
collapse_key |
Optional, String | Weitere Informationen finden Sie in Tabelle 1. |
time_to_live |
Optional, Nummer | Weitere Informationen finden Sie in Tabelle 1. |
restricted_package_name |
Optional, String | Weitere Informationen finden Sie in Tabelle 1. |
dry_run |
Optional, boolesch | Weitere Informationen finden Sie in Tabelle 1. |
Nutzlast | ||
data.<key> |
Optional, String | Dieser Parameter gibt die Schlüssel/Wert-Paare der Nutzlast der Nachricht an. Es gibt keine Beschränkung für die Anzahl der Schlüssel/Wert-Parameter, aber die Gesamtgröße der Nachricht beträgt 4.096 Byte. In Android würde Der Schlüssel darf 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 nachgelagerten Nachrichtenantwort
Der Anwendungsserver sollte sowohl den Nachrichtenantwortheader als auch den Text auswerten, um die von FCM gesendete Nachrichtenantwort zu interpretieren. In der folgenden Tabelle werden die möglichen Antworten beschrieben.
Antwort | Beschreibung |
---|---|
200 | Die Nachricht wurde erfolgreich verarbeitet. Der Antworttext enthält weitere Informationen zum Nachrichtenstatus. Das Format hängt jedoch davon ab, ob es sich um eine JSON- oder eine Nur-Text-Anfrage handelt. Weitere Informationen finden Sie in Tabelle 5. |
400 | Gilt nur für JSON-Anfragen. Gibt an, dass die Anfrage nicht als JSON geparst werden konnte oder ungültige Felder enthielt (z. B. die Übergabe eines Strings, bei dem eine Zahl erwartet wurde). Der genaue Grund für den Fehler wird in der Antwort beschrieben. Das Problem muss behoben werden, bevor die Anfrage wiederholt werden kann. |
401 | Bei der Authentifizierung des Absenderkontos ist ein Fehler aufgetreten. |
5xx | Fehler im Bereich von 500 bis 599 (z. B. 500 oder 503) weisen darauf hin, dass beim Versuch, die Anfrage zu verarbeiten, ein interner Fehler im FCM-Back-End aufgetreten ist oder dass der Server vorübergehend nicht verfügbar ist (z. B. aufgrund von Zeitüberschreitungen). Der Absender muss den Vorgang später unter Berücksichtigung des Retry-After -Headers in der Antwort wiederholen. Anwendungsserver müssen exponentielles Backoff implementieren. |
In der folgenden Tabelle sind die Felder in einem nachgelagerten Nachrichtenantworttext (JSON) aufgeführt.
Parameter | Nutzung | Beschreibung |
---|---|---|
multicast_id |
Erforderlich, Nummer | Eindeutige ID (Nummer), die die Multicast-Nachricht identifiziert. |
success |
Erforderlich, Nummer | Anzahl der Nachrichten, die ohne Fehler verarbeitet wurden. |
failure |
Erforderlich, Nummer | Anzahl der Nachrichten, die nicht verarbeitet werden konnten. |
results |
Erforderlich, Array der Objekte | 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 selben Index in der Antwort aufgeführt).
|
Parameter | Nutzung | Beschreibung |
---|---|---|
message_id |
Optional, Nummer | Die Nachrichten-ID des Themas, wenn FCM die Anfrage erhalten hat und versucht, sie an alle abonnierten Geräte zu senden. |
error |
Optional, String | Fehler, der beim Verarbeiten der Nachricht aufgetreten ist. Die möglichen Werte finden Sie in Tabelle 9. |
Parameter | Nutzung | Beschreibung |
---|---|---|
id |
Erforderlich, String | Dieser Parameter gibt die eindeutige Nachrichten-ID an, die von FCM erfolgreich verarbeitet wurde. |
registration_id |
Optional, String | Dieser Parameter gibt das Registrierungstoken für die Clientanwendung an, an die die Nachricht verarbeitet und gesendet wurde. |
Parameter | Nutzung | Beschreibung |
---|---|---|
Error |
Erforderlich, String | Dieser Parameter gibt den Fehlerwert an, während die Nachricht für den Empfänger verarbeitet wird. Weitere Informationen finden Sie in Tabelle 9. |
Fehlerantwortcodes für Downstream-Nachrichten
In der folgenden Tabelle sind die Fehlerantwortcodes für nachgelagerte Meldungen aufgeführt.
Fehler | HTTP-Code | Empfohlene Maßnahme |
---|---|---|
Registrierungstoken fehlt | 200 und Fehler:MissingRegistration | Prüfe, ob die Anfrage ein Registrierungstoken enthält (im Feld registration_id bei einer Textnachricht oder im Feld to oder registration_ids im JSON-Format). |
Ungültiges Registrierungstoken | 200 und Fehler:InvalidRegistration | Prüfen Sie das Format des Registrierungstokens, das Sie an den Server übergeben. Es muss mit dem Registrierungstoken übereinstimmen, das die Client-App bei der Registrierung bei Firebase Notifications erhält. Kürzen Sie die Datei nicht und fügen Sie keine zusätzlichen Zeichen hinzu. |
Nicht registriertes Gerät | 200 + Fehler:NotRegistered | Ein vorhandenes Registrierungstoken kann unter anderem in folgenden Fällen nicht mehr gültig sein:
|
Ungültiger Paketname | 200 + Fehler:UngültigerPackageName | Prüfen Sie, ob die Nachricht an ein Registrierungstoken adressiert ist, dessen Paketname mit dem in der Anfrage übergebenen Wert übereinstimmt. |
Authentifizierungsfehler | 401 | Das Absenderkonto, über das eine Nachricht gesendet wurde, konnte nicht authentifiziert werden. Mögliche Ursachen:
|
Absender stimmt nicht überein | 200 + Fehler:MismatchSenderId | Ein Registrierungstoken ist an eine bestimmte Gruppe von Absendern gebunden. Bei der Registrierung einer Client-App für FCM 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ültiges JSON-Format | 400 | Prüfen Sie, ob die JSON-Nachricht richtig formatiert ist und gültige Felder enthält (z. B., ob der richtige Datentyp übergeben wird). |
Ungültige Parameter | 400 und Fehler:InvalidParameters | Achten Sie darauf, dass die angegebenen Parameter den richtigen Namen und Typ haben. |
Nachricht zu groß | 200 + Fehler:MessageTooBig | Achten Sie darauf, dass die Gesamtgröße der Nutzlastdaten in einer Nachricht die FCM-Limits nicht überschreitet: 4.096 Byte für die meisten Nachrichten oder 2.048 Byte für Nachrichten an Themen. Dazu gehören sowohl die Schlüssel als auch die Werte. |
Ungültiger Datenschlüssel | Fehler 200 und Fehler:
UngültigerDataKey |
Achten Sie darauf, dass die Nutzlastdaten keinen Schlüssel (z. B. from , gcm oder einen 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 Gültigkeitsdauer | 200 und Fehler:UngültigeTtl | Prüfen Sie, ob der in time_to_live verwendete Wert eine Ganzzahl für eine Dauer in Sekunden zwischen 0 und 2.419.200 (4 Wochen) ist. |
Zeitlimit | 5xx oder 200 + Fehler:nicht verfügbar | Die Anfrage konnte vom Server nicht rechtzeitig verarbeitet werden. Wiederholen Sie die gleiche Anfrage. Sie müssen aber Folgendes tun:
Absender, die Probleme verursachen, werden möglicherweise auf die schwarze Liste gesetzt. |
Internal Server Error (Interner Serverfehler) | 500 oder 200 + Fehler:InternalServerError | Beim Verarbeiten der Anfrage ist auf dem Server ein Fehler aufgetreten. Sie können dieselbe Anfrage nach den unter „Zeitüberschreitung“ aufgeführten Anforderungen (siehe Zeile oben) wiederholen. Wenn der Fehler weiterhin auftritt, wenden Sie sich an den Firebase-Support. |
Nachrichtenrate des Geräts überschritten | Fehler 200:
DeviceMessageRate Überschritten |
Die Anzahl der Nachrichten an ein bestimmtes Gerät ist zu hoch. Wenn eine Apple-App Nachrichten mit einer Rate sendet, die die APNs-Limits überschreitet, wird möglicherweise diese Fehlermeldung angezeigt Reduzieren Sie die Anzahl der Nachrichten, die an dieses Gerät gesendet werden, und verwenden Sie den exponentiellen Backoff, um den Sendeversuch zu wiederholen. |
Nachrichtenrate zu Themen überschritten | Mehr als 200 Fehler:
TopicsMessageRate Überschritten |
Die Rate der Nachrichten an Abonnenten zu einem bestimmten Thema ist zu hoch. Reduzieren Sie die Anzahl der Nachrichten, die für dieses Thema gesendet werden, und verwenden Sie den exponentiellen Backoff, um den Sendeversuch zu wiederholen. |
Ungültige APNs-Anmeldedaten | Fehler 200 oder höher:
UngültigeApnsCredential |
Eine an ein Apple-Gerät gerichtete Nachricht konnte nicht gesendet werden, da der erforderliche APNs-Authentifizierungsschlüssel nicht hochgeladen wurde oder abgelaufen ist. Prüfen Sie die Gültigkeit Ihrer Entwicklungs- und Produktionsanmeldedaten. |
Verwaltung von Gerätegruppen
In der folgenden Tabelle sind die Schlüssel zum Erstellen von Gerätegruppen und zum Hinzufügen und Entfernen von Mitgliedern aufgeführt. Weitere Informationen finden Sie im Leitfaden für Ihre Plattform, iOS+ oder Android.
Parameter | Nutzung | Beschreibung |
---|---|---|
operation |
Erforderlich, String | Der auszuführende Vorgang.Gültige Werte sind create , add und remove . |
notification_key_name |
Erforderlich, String | Der benutzerdefinierte Name der Gerätegruppe, die erstellt oder geändert werden soll. |
notification_key |
Erforderlich (außer create -Vorgang, String |
Eindeutige Kennung der Gerätegruppe. Dieser Wert wird in der Antwort auf einen erfolgreichen create -Vorgang zurückgegeben und ist für alle nachfolgenden Vorgänge in der Gerätegruppe erforderlich. |
registration_ids |
Erforderlich, String-Array | Die Gerätetokens, die hinzugefügt oder entfernt werden sollen. Wenn du alle vorhandenen Registrierungstokens aus einer Gerätegruppe entfernst, wird die Gerätegruppe von FCM gelöscht. |