Firebase Cloud Messaging (FCM) bietet eine Vielzahl von Messaging-Optionen und ‑Funktionen. Die Informationen auf dieser Seite sollen Ihnen helfen, die verschiedenen Arten von FCM-Mitteilungen zu verstehen und zu erfahren, was Sie damit tun können.
Benachrichtigungen mit optionaler Daten-Payload
Sowohl programmatisch als auch über die Firebase-Konsole können Sie Benachrichtigungen mit einer optionalen Nutzlast aus benutzerdefinierten Schlüssel/Wert-Paaren senden. Verwenden Sie im Benachrichtigungs-Composer die Felder Benutzerdefinierte Daten unter Erweiterte Optionen.
Das Verhalten der App beim Empfang von Nachrichten, die sowohl Benachrichtigungs- als auch Daten-Payloads enthalten, hängt davon ab, ob die App im Hintergrund oder im Vordergrund ausgeführt wird – also davon, ob sie zum Zeitpunkt des Empfangs aktiv ist.
- Im Hintergrund empfangen Apps die Benachrichtigungs-Payload in der Benachrichtigungsleiste und verarbeiten die Daten-Payload erst, wenn der Nutzer auf die Benachrichtigung tippt.
- Wenn sich die App im Vordergrund befindet, empfängt sie ein Message-Objekt mit beiden verfügbaren Nutzlasten.
Hier ist eine JSON-formatierte Nachricht, die sowohl den Schlüssel notification als auch den Schlüssel data enthält:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"notification":{
"title":"Portugal vs. Denmark",
"body":"great match!"
},
"data" : {
"Nick" : "Mario",
"Room" : "PortugalVSDenmark"
}
}
}Lieferoptionen
FCM bietet eine Reihe von Zustellungsoptionen für Nachrichten, die an Android-Geräte gesendet werden, und ähnliche Optionen für Apple-Plattformen und das Web. Das Verhalten von „minimierbaren“ Nachrichten wird beispielsweise auf Android über FCM collapse_key, auf Apple über apns-collapse-id und auf JavaScript/Web über Topic unterstützt. Weitere Informationen finden Sie in den Beschreibungen in diesem Abschnitt und in der zugehörigen Referenzdokumentation.
Priorität einer Nachricht festlegen
Sie haben zwei Optionen zum Zuweisen der Zustellpriorität für Downstream-Nachrichten: „normal“ und „hoch“. Das Verhalten unterscheidet sich zwar geringfügig zwischen den Plattformen, die Zustellung von Nachrichten mit normaler und hoher Priorität funktioniert jedoch so:
Normale Priorität: Nachrichten mit normaler Priorität werden sofort zugestellt, wenn die App im Vordergrund ausgeführt wird. Bei Apps, die im Hintergrund ausgeführt werden, kann es zu Verzögerungen bei der Zustellung kommen. Für weniger zeitkritische Nachrichten wie Benachrichtigungen über neue E‑Mails, die Synchronisierung der Benutzeroberfläche oder die Synchronisierung von App-Daten im Hintergrund sollten Sie die normale Priorität für die Zustellung wählen.
Hohe Priorität: FCM versucht, Nachrichten mit hoher Priorität sofort zu senden, auch wenn sich das Gerät im Inaktivmodus befindet. Nachrichten mit hoher Priorität sind für zeitkritische, für Nutzer sichtbare Inhalte vorgesehen.
Hier ist ein Beispiel für eine Nachricht mit normaler Priorität, die über das FCM-HTTP v1-Protokoll gesendet wird, um einen Abonnenten einer Zeitschrift darüber zu informieren, dass neue Inhalte zum Herunterladen verfügbar sind:
{
"message":{
"topic":"subscriber-updates",
"notification":{
"body" : "This week's edition is now available.",
"title" : "NewsMagazine.com",
},
"data" : {
"volume" : "3.21.15",
"contents" : "http://www.news-magazine.com/world-week/21659772"
},
"android":{
"priority":"normal"
},
"apns":{
"headers":{
"apns-priority":"5"
}
},
"webpush": {
"headers": {
"Urgency": "high"
}
}
}
}Weitere plattformspezifische Informationen zum Festlegen der Nachrichtenpriorität:
- APNs-Dokumentation
- Nachrichtenpriorität festlegen und verwalten (Android)
- Dringlichkeit von Web-Push-Benachrichtigungen
Lebenswichtige Anwendungsfälle
Die FCM-APIs sind nicht für Notfallbenachrichtigungen oder andere Aktivitäten mit hohem Risiko konzipiert, bei denen die Nutzung oder der Ausfall der APIs zu Todesfällen, Verletzungen oder Umweltschäden führen könnte (z. B. der Betrieb von kerntechnischen Anlagen, die Überwachung des Flugverkehrs oder Lebenserhaltungssysteme). Eine solche Nutzung ist gemäß Abschnitt 4.a. ausdrücklich untersagt. 7 der Nutzungsbedingungen. Sie sind allein dafür verantwortlich, dass Ihre App den Nutzungsbedingungen entspricht, und haften für alle Schäden, die durch Ihre Nichteinhaltung entstehen. Google stellt die APIs „wie besehen“ zur Verfügung und behält sich das Recht vor, die APIs oder einen Teil bzw. eine Funktion davon oder Ihren Zugriff darauf aus einem beliebigen Grund und zu einem beliebigen Zeitpunkt ohne Haftung oder sonstige Verpflichtung Ihnen oder Ihren Nutzern gegenüber einzustellen.
Gültigkeitsdauer einer Nachricht festlegen
FCM stellt Nachrichten in der Regel sofort nach dem Senden zu. Das ist jedoch nicht immer möglich. Wenn die Plattform beispielsweise Android ist, kann das Gerät ausgeschaltet, offline oder anderweitig nicht verfügbar sein. Oder FCM verzögert Nachrichten absichtlich, um zu verhindern, dass eine App zu viele Ressourcen verbraucht und die Akkulaufzeit negativ beeinflusst.
In diesem Fall speichert FCM die Nachricht und stellt sie so bald wie möglich zu. In den meisten Fällen ist das kein Problem, aber bei einigen Apps sollte eine verspätete Nachricht gar nicht zugestellt werden. Wenn die Nachricht beispielsweise eine Benachrichtigung über einen eingehenden Anruf oder Videochat ist, ist sie nur für kurze Zeit relevant, bevor der Anruf beendet wird. Oder wenn die Nachricht eine Einladung zu einem Termin ist, ist sie nutzlos, wenn sie nach dem Ende des Termins empfangen wird.
Unter Android und Web/JavaScript können Sie die maximale Lebensdauer einer Nachricht angeben. Der Wert muss eine Dauer zwischen 0 und 2.419.200 Sekunden (28 Tage) sein. Er entspricht dem maximalen Zeitraum, in dem FCM die Nachricht speichert und versucht, sie zuzustellen. Bei Anfragen, die dieses Feld nicht enthalten, wird standardmäßig der maximale Zeitraum von vier Wochen verwendet.
Hier sind einige mögliche Anwendungsbereiche für diese Funktion:
- Eingehende Videoanrufe
- Ablaufende Einladungsereignisse
- Kalendertermine
Ein weiterer Vorteil der Angabe der Lebensdauer einer Nachricht ist, dass FCM die Drosselung von minimierbaren Nachrichten nicht auf Nachrichten mit einem TTL-Wert von 0 Sekunden anwendet.
FCM bietet eine Best-Effort-Verarbeitung von Nachrichten, die „jetzt oder nie“ zugestellt werden müssen. Beachten Sie, dass ein time_to_live-Wert von 0 bedeutet, dass Nachrichten, die nicht sofort zugestellt werden können, verworfen werden. Da solche Nachrichten jedoch nie gespeichert werden, ist die Latenz beim Senden von Benachrichtigungen am geringsten.
Hier ist ein Beispiel für eine Anfrage, die die TTL enthält:
{
"message":{
"token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
"data":{
"Nick" : "Mario",
"body" : "great match!",
"Room" : "PortugalVSDenmark"
},
"apns":{
"headers":{
"apns-expiration":"1604750400"
}
},
"android":{
"ttl":"4500s"
},
"webpush":{
"headers":{
"TTL":"4500"
}
}
}
}Lebensdauer einer Nachricht
Wenn ein App-Server eine Nachricht an FCM sendet und eine Nachrichten-ID zurückerhält, bedeutet das nicht, dass die Nachricht bereits auf dem Gerät zugestellt wurde. Das bedeutet nicht, dass es bereits ausgeliefert wurde, sondern dass es für die Auslieferung angenommen wurde. Was mit der Nachricht passiert, nachdem sie akzeptiert wurde, hängt von vielen Faktoren ab.
Im Best-Case-Szenario, wenn das Gerät mit FCM verbunden ist, das Display eingeschaltet ist und keine Einschränkungen durch Drosselung vorliegen, wird die Nachricht sofort zugestellt.
Wenn das Gerät verbunden ist, sich aber im Inaktivmodus befindet, wird eine Nachricht mit niedriger Priorität von FCM gespeichert, bis das Gerät den Inaktivmodus verlässt. Hier kommt das Flag collapse_key ins Spiel: Wenn bereits eine Nachricht mit demselben Collapse-Schlüssel (und Registrierungstoken) gespeichert ist und auf die Zustellung wartet, wird die alte Nachricht verworfen und die neue Nachricht tritt an ihre Stelle (d. h. die alte Nachricht wird durch die neue Nachricht zusammengefasst). Wenn der Collapse-Schlüssel jedoch nicht festgelegt ist, werden sowohl die neue als auch die alte Nachricht für die zukünftige Zustellung gespeichert.
Wenn das Gerät nicht mit FCM verbunden ist, wird die Nachricht gespeichert, bis eine Verbindung hergestellt wird (wobei die Regeln für den Collapse-Schlüssel beachtet werden). Wenn eine Verbindung hergestellt wird, werden alle ausstehenden Nachrichten von FCM an das Gerät gesendet. Wenn das Gerät nie wieder verbunden wird (z. B. wenn es auf die Werkseinstellungen zurückgesetzt wurde), läuft die Meldung schließlich ab und wird aus dem FCM-Speicher gelöscht. Die Standardzeitüberschreitung beträgt vier Wochen, sofern das Flag time_to_live nicht festgelegt ist.
So erhalten Sie weitere Informationen zur Zustellung einer Nachricht:
Weitere Informationen zur Zustellung von Nachrichten auf Android- oder Apple-Plattformen finden Sie im FCM-Berichtsdashboard. Dort wird die Anzahl der auf Apple- und Android-Geräten gesendeten und geöffneten Nachrichten sowie Daten zu „Impressionen“ (Benachrichtigungen, die von Nutzern gesehen wurden) für Android-Apps erfasst.
Wenn auf Android-Geräten mit aktivierter Direktkanal-Messaging-Funktion das Gerät seit mehr als einem Monat nicht mit FCM verbunden war, akzeptiert FCM die Nachricht zwar, verwirft sie aber sofort. Wenn sich das Gerät innerhalb von vier Wochen nach der letzten Datenmeldung, die Sie an das Gerät gesendet haben, verbindet, erhält Ihr Client den onDeletedMessages()-Callback. Die App kann dann entsprechend reagieren, in der Regel durch Anfordern einer vollständigen Synchronisierung vom App-Server.
Wenn FCM schließlich versucht, eine Nachricht an das Gerät zu senden, und die App deinstalliert wurde, verwirft FCM diese Nachricht sofort und macht das Registrierungstoken ungültig. Bei zukünftigen Versuchen, eine Nachricht an dieses Gerät zu senden, wird der Fehler NotRegistered ausgegeben.
Anmeldedaten
Je nachdem, welche FCM-Funktionen Sie implementieren, benötigen Sie möglicherweise die folgenden Anmeldedaten aus Ihrem Firebase-Projekt:
| Projekt-ID | Eine eindeutige Kennung für Ihr Firebase-Projekt, die in Anfragen an den FCM v1-HTTP-Endpunkt verwendet wird. Dieser Wert ist in der Firebase-Konsole im Bereich Einstellungen verfügbar. |
| Registrierungstoken | Ein eindeutiger Token-String, der jede Client-App-Instanz identifiziert. Das Registrierungstoken ist für die Nachrichtenübermittlung an einzelne Geräte und Gerätegruppen erforderlich. Registrierungstokens müssen geheim gehalten werden. |
| Sender-ID | Ein eindeutiger numerischer Wert, der beim Erstellen Ihres Firebase-Projekts generiert wird. Sie finden ihn in der Registerkarte Cloud MessagingFirebase-Konsole. Die Absender-ID wird verwendet, um jeden Absender zu identifizieren, der Nachrichten an die Client-App senden kann. |
| Zugriffstoken | Ein kurzlebiges OAuth 2.0-Token, das Anfragen an die HTTP v1 API autorisiert. Dieses Token ist mit einem Dienstkonto verknüpft, das zu Ihrem Firebase-Projekt gehört. Wenn Sie Zugriffstokens erstellen und rotieren möchten, folgen Sie der Anleitung unter Sendeanfragen autorisieren. |