FCM-Nachrichten

Firebase Cloud Messaging (FCM) bietet eine breite Palette an 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.

Nachrichtentypen

Mit FCM können Sie zwei Arten von Nachrichten an Kunden senden:

• Benachrichtigungsnachrichten, die auch als „Displaynachrichten“ bezeichnet werden. Diese werden vom FCM SDK automatisch verarbeitet.
• Datennachrichten, die von der Client-App verarbeitet werden.

Benachrichtigungsnachrichten enthalten eine vordefinierte Reihe von für Nutzer sichtbaren Schlüsseln. Datennachrichten enthalten dagegen nur Ihre benutzerdefinierten benutzerdefinierten Schlüssel/Wert-Paare. Benachrichtigungsnachrichten können eine optionale Datennutzlast enthalten. Die maximale Nutzlast für beide Nachrichtentypen beträgt 4.096 Byte, es sei denn, Nachrichten werden über die Firebase-Konsole gesendet, in der ein Limit von 1.000 Zeichen erzwungen wird.

	Anwendungsszenario	So senden Sie eine Nachricht
Benachrichtigungsnachricht	FCM Das SDK zeigt die Mitteilung im Namen der Client-App auf den Geräten der Endnutzer an, wenn es im Hintergrund ausgeführt wird. Andernfalls, wenn die App beim Empfang der Benachrichtigung im Vordergrund ausgeführt wird, wird das Verhalten durch den Code der App bestimmt. Benachrichtigungsnachrichten haben einen vordefinierten Satz von für den Nutzer sichtbaren Schlüssel und eine optionale Datennutzlast aus benutzerdefinierten Schlüssel/Wert-Paaren.	Verwenden Sie in einer vertrauenswürdigen Umgebung wie Cloud Functions oder Ihrem Anwendungsserver das Admin SDK oder die HTTP v1 API. Legen Sie den Schlüssel notification fest. Kann eine optionale Datennutzlast haben. Sie können immer minimiert werden. Sehen Sie sich einige Beispiele für Displaybenachrichtigungen und Sende-Nutzlasten an. Mit dem Benachrichtigungs-Editor: Geben Sie den Text der Nachricht, den Titel usw. ein und senden Sie die Nachricht. Fügen Sie eine optionale Datennutzlast hinzu, indem Sie benutzerdefinierte Daten angeben.
Datennachricht	Die Client-App ist für die Verarbeitung von Datennachrichten verantwortlich. Datennachrichten enthalten nur benutzerdefinierte Schlüssel/Wert-Paare ohne reservierte Schlüsselnamen (siehe unten).	Verwenden Sie in einer vertrauenswürdigen Umgebung wie Cloud Functions oder auf Ihrem App-Server das Admin SDK oder die FCM-Serverprotokolle. Legen Sie in der Sendeanfrage den Schlüssel data fest.

Verwende Benachrichtigungen, wenn das FCM SDK automatisch eine Benachrichtigung anzeigen soll, wenn deine App im Hintergrund ausgeführt wird. Verwenden Sie Datennachrichten, wenn Sie die Nachrichten mit Ihrem eigenen Client-App-Code verarbeiten möchten.

FCM kann eine Benachrichtigung mit einer optionalen Datennutzlast senden. In solchen Fällen verarbeitet FCM die Benachrichtigungsnutzlast und die Clientanwendung verarbeitet die Datennutzlast.

Benachrichtigungen

Für Tests oder für Marketing und die erneute Interaktion mit Nutzern können Sie Benachrichtigungen über die Firebase-Konsole senden. Die Firebase-Konsole bietet analysebasierte A/B-Tests, mit denen Sie Ihre Werbebotschaften verfeinern und verbessern können.

Wenn Sie Benachrichtigungsnachrichten programmatisch über das Admin SDK oder die FCM-Protokolle senden möchten, legen Sie den Schlüssel „notification“ mit den erforderlichen vordefinierten Schlüssel/Wert-Optionen für den für Nutzer sichtbaren Teil der Benachrichtigungsnachricht fest. Hier sehen Sie als Beispiel eine Benachrichtigung im JSON-Format in einer IM-App. Der Nutzer erwartet auf dem Gerät eine Nachricht mit dem Titel „Portugal vs. Dänemark“ und dem Text „hervorragende Übereinstimmung!“:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "notification":{
      "title":"Portugal vs. Denmark",
      "body":"great match!"
    }
  }
}

Benachrichtigungsnachrichten werden an das Benachrichtigungs-Dock gesendet, wenn die App im Hintergrund ausgeführt wird. Bei Apps im Vordergrund werden Nachrichten über eine Rückruffunktion verarbeitet.

Eine vollständige Liste der vordefinierten Schlüssel, die zum Erstellen von Benachrichtigungsnachrichten verwendet werden können, finden Sie in der Referenzdokumentation zum HTTP-v1-Protokoll-Benachrichtigungsobjekt.

Datennachrichten

Legen Sie den entsprechenden Schlüssel mit Ihren benutzerdefinierten Schlüssel/Wert-Paaren fest, um eine Datennutzlast an die Client-App zu senden.

Verwenden Sie in Ihren benutzerdefinierten Schlüssel/Wert-Paaren keine reservierten Wörter. Reservierte Wörter sind „from“, „notification“, „message_type“ oder alle Wörter, die mit „google“ oder „gcm“ beginnen.

Hier sehen Sie beispielsweise eine Nachricht im JSON-Format in derselben IM-Anwendung wie oben, wobei die Informationen im gemeinsamen data-Schlüssel gekapselt sind und die Clientanwendung den Inhalt interpretieren soll:

{
  "message":{
    "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
    "data":{
      "Nick" : "Mario",
      "body" : "great match!",
      "Room" : "PortugalVSDenmark"
    }
  }
}

Im obigen Beispiel wird die Verwendung des data-Felds auf oberster Ebene oder des gemeinsamen data-Felds gezeigt, das von Clients auf allen Plattformen, die die Nachricht empfangen, interpretiert wird. Auf jeder Plattform empfängt die Client-App die Datennutzlast in einer Callback-Funktion.

Verschlüsselung für Datennachrichten

Android Transport Layer (siehe FCM-Architektur) verwendet Punkt-zu-Punkt-Verschlüsselung. Je nach Bedarf können Sie Datennachrichten eine Ende-zu-Ende-Verschlüsselung hinzufügen. FCM bietet keine End-to-End-Lösung. Es gibt jedoch externe Lösungen wie Capillary oder DTLS.

Benachrichtigungsnachrichten mit optionaler Datennutzlast

Sowohl programmatisch als auch über die Firebase-Konsole können Sie Benachrichtigungsnachrichten mit einer optionalen Nutzlast aus benutzerdefinierten Schlüssel/Wert-Paaren senden. Verwenden Sie im Benachrichtigungs-Editor die Felder Benutzerdefinierte Daten unter Erweiterte Optionen.

Das Verhalten der App beim Empfangen von Nachrichten, die sowohl Benachrichtigungs- als auch Datennutzlasten enthalten, hängt davon ab, ob die App im Hintergrund oder im Vordergrund ausgeführt wird, also ob sie zum Zeitpunkt des Empfangs aktiv ist oder nicht.

• Im Hintergrund erhalten Apps die Benachrichtigungsnutzlast im Benachrichtigungs-Tray und verarbeiten die Datennutzlast nur, wenn der Nutzer auf die Benachrichtigung tippt.
• Im Vordergrund empfängt Ihre App ein Nachrichtenobjekt, über das beide Nutzlasten verfügbar sind.

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"
    }
  }
}

Plattformübergreifende Anpassung einer Mitteilung

Sowohl mit dem Firebase Admin SDK als auch mit dem HTTP-Protokoll FCM v1 können in Ihren Nachrichtenanfragen alle verfügbaren Felder im message-Objekt festgelegt werden. Dazu zählen:

• eine gemeinsame Gruppe von Feldern, die von allen App-Instanzen interpretiert werden, die die Nachricht empfangen.
• plattformspezifische Felder wie AndroidConfig und WebpushConfig, die nur von App-Instanzen interpretiert werden, die auf der angegebenen Plattform ausgeführt werden.

Mit plattformspezifischen Blöcken können Sie Nachrichten flexibel für verschiedene Plattformen anpassen, damit sie beim Empfang richtig verarbeitet werden. Das FCM-Back-End berücksichtigt alle angegebenen Parameter und passt die Nachricht für jede Plattform an.

Wann werden allgemeine Felder verwendet?

Verwenden Sie allgemeine Felder, wenn Sie:

• Targeting auf App-Instanzen auf allen Plattformen – Apple, Android und Web
• Nachrichten an Themen senden

Alle App-Instanzen können unabhängig von der Plattform die folgenden gängigen Felder interpretieren:

• message.notification.title
• message.notification.body
• message.data

Wann sollten plattformspezifische Felder verwendet werden?

Plattformspezifische Felder eignen sich für Folgendes:

• Felder nur an bestimmte Plattformen senden
• Plattformspezifische Felder zusätzlich zu den allgemeinen Feldern senden

Wenn Sie Werte nur an bestimmte Plattformen senden möchten, verwenden Sie keine allgemeinen Felder, sondern plattformspezifische Felder. Wenn Sie beispielsweise eine Benachrichtigung nur an Apple-Plattformen und das Web, aber nicht an Android-Geräte senden möchten, müssen Sie zwei separate Felder verwenden, eines für Apple und eines für das Web.

Wenn Sie Nachrichten mit bestimmten Zustelloptionen senden, verwenden Sie plattformspezifische Felder, um diese festzulegen. Wenn Sie möchten, können Sie für jede Plattform unterschiedliche Werte angeben. Auch wenn Sie auf allen Plattformen im Wesentlichen denselben Wert festlegen möchten, müssen Sie plattformspezifische Felder verwenden. Das liegt daran, dass jede Plattform den Wert etwas unterschiedlich interpretieren kann. Beispielsweise wird die Gültigkeitsdauer unter Android als Ablaufzeit in Sekunden und in Apple als Ablaufdatum festgelegt.

Beispiel: Benachrichtigungsnachricht mit platformspezifischen Übermittlungsoptionen

Mit der folgenden V1-Sendeanfrage werden ein gemeinsamer Benachrichtigungstitel und -inhalt an alle Plattformen gesendet, aber auch einige plattformspezifische Überschreibungen. Insbesondere muss die Anfrage:

• legt eine lange Gültigkeitsdauer für Android- und Web-Plattformen fest und setzt die Priorität der APNs-Nachrichten (Apple-Plattformen) auf eine niedrige Einstellung.
• legt die entsprechenden Schlüssel fest, um das Ergebnis des Tippens auf die Benachrichtigung auf Android- und Apple-Geräten zu definieren – click_action bzw. category.

{
  "message":{
     "token":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
     "notification":{
       "title":"Match update",
       "body":"Arsenal goal in added time, score is now 3-0"
     },
     "android":{
       "ttl":"86400s",
       "notification"{
         "click_action":"OPEN_ACTIVITY_1"
       }
     },
     "apns": {
       "headers": {
         "apns-priority": "5",
       },
       "payload": {
         "aps": {
           "category": "NEW_MESSAGE_CATEGORY"
         }
       }
     },
     "webpush":{
       "headers":{
         "TTL":"86400"
       }
     }
   }
 }

Ausführliche Informationen zu den Schlüsseln, die in plattformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der HTTP v1-Referenzdokumentation. Weitere Informationen zum Erstellen von Sendeanfragen, die den Nachrichtentext enthalten, finden Sie unter Sendeanfragen erstellen.

Lieferoptionen

FCM bietet eine Reihe von Übermittlungsoptionen für Nachrichten, die an Android-Geräte gesendet werden, und ähnliche Optionen auf Apple-Plattformen und im Web. „Minimierbare“ Nachrichten werden beispielsweise unter Android über die collapse_key von FCM, auf Apple über apns-collapse-id und im JavaScript/Web über Topic unterstützt. Weitere Informationen finden Sie in den Beschreibungen in diesem Abschnitt und in der zugehörigen Referenzdokumentation.

Nicht minimierbare und minimierbare Nachrichten

Wenn eine Meldung nicht minimiert werden kann, wird jede einzelne Nachricht an das Gerät gesendet. Eine nicht minimierbare Nachricht enthält nützliche Inhalte, im Gegensatz zu einer minimierbaren Nachricht wie einem inhaltslosen „Ping“ an die mobile App, um den Server zum Abrufen von Daten zu kontaktieren.

FCM garantiert nicht die Reihenfolge der Lieferung.

Einige typische Anwendungsfälle für nicht minimierbare Nachrichten sind Chatnachrichten oder kritische Nachrichten. In einer Chat-App möchten Sie beispielsweise jede Nachricht senden, da jede Nachricht einen anderen Inhalt hat.

Unter Android können maximal 100 Nachrichten gespeichert werden, ohne dass die Liste minimiert wird. Wenn das Limit erreicht ist, werden alle gespeicherten Nachrichten verworfen. Wenn das Gerät wieder online ist, erhält es eine spezielle Meldung, dass das Limit erreicht wurde. Die App kann die Situation dann richtig verarbeiten, indem sie in der Regel eine vollständige Synchronisierung vom App-Server anfordert.

Eine minimierbare Nachricht ist eine Nachricht, die möglicherweise durch eine neue Nachricht ersetzt wird, wenn sie noch nicht an das Gerät zugestellt wurde.

Ein häufiger Anwendungsfall für minimierbare Meldungen sind Meldungen, mit denen eine mobile App aufgefordert wird, Daten vom Server zu synchronisieren. Ein Beispiel wäre eine Sport-App, die Nutzer über den aktuellen Spielstand informiert. Nur die neueste Nachricht ist relevant.

Wenn Sie eine Nachricht auf Android-Geräten als minimierbar kennzeichnen möchten, fügen Sie den Parameter collapse_key in die Nachrichtenn-Nutzlast ein. Der Minimierungsschlüssel ist standardmäßig der Name des App-Pakets, der in der Firebase-Konsole registriert ist. Der FCM-Server kann gleichzeitig vier verschiedene minimierbare Nachrichten pro Gerät mit jeweils einem anderen Minimierungsschlüssel speichern. Wenn Sie diese Anzahl überschreiten, behält FCM nur vier Minimierungsschlüssel bei. Es kann nicht garantiert werden, welche Schlüssel das sind.

Nachrichten zu Themen ohne Nutzlast sind standardmäßig minimierbar. Benachrichtigungsnachrichten sind immer minimierbar und der Parameter collapse_key wird ignoriert.

Welche sollte ich verwenden?

Zusammenklappbare Nachrichten sind aus Leistungsgründen die bessere Wahl, sofern in Ihrer App keine nicht zusammenklappbaren Nachrichten verwendet werden müssen. Wenn Sie jedoch minimierbare Nachrichten verwenden, beachten Sie, dass FCM jeweils nur vier verschiedene Minimierungsschlüssel pro Registrierungstoken zulässt. Diese Anzahl darf nicht überschritten werden, da dies unvorhersehbare Folgen haben kann.

	Anwendungsszenario	Anleitung zum Senden
Nicht minimierbar	Jede Nachricht ist für die Client-App wichtig und muss zugestellt werden.	Mit Ausnahme von Benachrichtigungsnachrichten können alle Nachrichten standardmäßig nicht minimiert werden.
Minimierbar	Wenn eine neuere Nachricht eine ältere, zusammengehörige Nachricht rendert, die für die Clientanwendung irrelevant ist, ersetzt FCM die ältere Nachricht. Beispiele: Nachrichten, mit denen eine Datensynchronisierung vom Server aus gestartet wird, oder veraltete Benachrichtigungsnachrichten.	Legen Sie in Ihrer Nachrichtenanfrage den entsprechenden Parameter fest: collapseKey für Android apns-collapse-id auf Apple Topic im Web collapse_key in Legacy-Protokollen (alle Plattformen)

Priorität einer Nachricht festlegen

Sie haben zwei Möglichkeiten, Downstream-Nachrichten Zustellungspriorität zuzuweisen: normale und hohe Priorität. Das Verhalten unterscheidet sich zwar je nach Plattform geringfügig, aber die Zustellung von Nachrichten mit normaler und hoher Priorität funktioniert so:

• Normale Priorität Nachrichten mit normaler Priorität werden sofort zugestellt, wenn die App im Vordergrund ausgeführt wird. Bei Apps im Hintergrund kann die Zustellung verzögert erfolgen. Wählen Sie für weniger zeitkritische Nachrichten wie Benachrichtigungen zu neuen E-Mails, die Synchronisierung der Benutzeroberfläche oder die Synchronisierung von App-Daten im Hintergrund die normale Übermittlungspriorität aus.

• Hohe Priorität. FCM versucht, Nachrichten mit hoher Priorität sofort zuzustellen, auch wenn sich das Gerät im Ruhemodus befindet. Nachrichten mit hoher Priorität sind für zeitkritische, für Nutzer sichtbare Inhalte gedacht.

Beim Senden von Datennachrichten an Apple-Geräte muss die Priorität auf 5 (normale Priorität) festgelegt sein. Nachrichten mit hoher Priorität werden vom FCM-Backend mit dem Fehler INVALID_ARGUMENT abgelehnt.

Hier ist ein Beispiel für eine Nachricht mit normaler Priorität, die über das FCM-HTTP-V1-Protokoll gesendet wird, um einen Zeitschriftenabonnenten darüber zu informieren, dass neue Inhalte zum Download 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-Nachrichten

Lebenswichtige Anwendungsfälle

Die FCM APIs sind nicht für Notfallwarnungen oder andere Aktivitäten mit hohem Risiko ausgelegt, bei denen die Verwendung oder der Ausfall der APIs zu Tod, Verletzungen oder Umweltschäden führen könnte (beispielsweise beim Betrieb von Kernenergieanlagen, Flugsicherungssystemen oder lebenserhaltenden Systemen). Jegliche solche Nutzung ist gemäß Abschnitt 4 a. 7 der Nutzungsbedingungen. Sie sind allein dafür verantwortlich, dass Ihre App die Nutzungsbedingungen einhält, und für alle Schäden, die sich aus einer Nichteinhaltung ergeben. Google stellt die APIs „wie besehen“ zur Verfügung und behält sich das Recht vor, die APIs oder einen Teil oder eine Funktion oder Ihren Zugriff darauf aus beliebigen Gründen und jederzeit ohne Haftung oder andere Verpflichtungen gegenüber Ihnen oder Ihren Nutzern einzustellen.

Gültigkeitsdauer einer Nachricht festlegen

FCM stellt Nachrichten normalerweise direkt nach dem Senden zu. Das ist jedoch nicht immer möglich. Wenn die Plattform beispielsweise Android ist, könnte 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 sendet sie so bald wie möglich. Das ist in den meisten Fällen in Ordnung, aber es gibt einige Apps, bei denen eine verspätete Nachricht möglicherweise nie zugestellt wird. Wenn die Nachricht beispielsweise eine Benachrichtigung zu einem eingehenden Anruf oder Videoanruf ist, ist sie nur für kurze Zeit relevant, bevor der Anruf beendet wird. Wenn die Nachricht eine Einladung zu einer Veranstaltung ist, ist sie nutzlos, wenn sie nach dem Ende der Veranstaltung empfangen wird.

Unter Android und Web/JavaScript können Sie die maximale Lebensdauer einer Nachricht angeben. Der Wert muss eine Dauer von 0 bis 2.419.200 Sekunden (28 Tage) sein. Er entspricht der maximalen Zeitspanne, in der 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 Anwendungsfälle für diese Funktion:

• Eingehende Videoanrufe
• Ablaufende Einladungsereignisse
• Kalendertermine

Ein weiterer Vorteil der Angabe der Lebensdauer einer Nachricht ist, dass FCM die Drosselung von minimierten Nachrichten nicht auf Nachrichten mit einem TTL-Wert von 0 Sekunden anwendet. FCM bietet eine Best-Effort-Verarbeitung von Nachrichten, die „sofort oder nie“ zugestellt werden müssen. Wenn der Wert für time_to_live 0 ist, werden Nachrichten, die nicht sofort zugestellt werden können, verworfen. Da solche Nachrichten jedoch nie gespeichert werden, ist die Latenz beim Senden von Benachrichtigungsnachrichten am niedrigsten.

Hier ein Beispiel für eine Anfrage mit TTL:

{
  "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 Anwendungsserver eine Nachricht an FCM sendet und eine Nachrichten-ID erhält, bedeutet dies nicht, dass die Nachricht bereits an das Gerät zugestellt wurde. Vielmehr bedeutet es, dass die Sendung zur Zustellung angenommen wurde. Was mit der Nachricht nach der Annahme passiert, hängt von vielen Faktoren ab.

Im Idealfall wird die Nachricht sofort zugestellt, wenn das Gerät mit FCM verbunden ist, das Display eingeschaltet ist und keine Drosselungsbeschränkungen vorliegen.

Wenn das Gerät verbunden ist, sich aber im Stromsparmodus befindet, wird von FCM eine Nachricht mit niedriger Priorität gespeichert, bis der Stromsparmodus für das Gerät beendet wird. Und hier kommt das Flag collapse_key ins Spiel: Wenn bereits eine Nachricht mit demselben Minimierungsschlüssel (und Registrierungstoken) gespeichert ist und auf die Zustellung wartet, wird die alte Nachricht verworfen und durch die neue ersetzt. Das bedeutet, dass die alte Nachricht durch die neue minimiert wird. Wenn der Zusammenklappungsschlüssel jedoch nicht festgelegt ist, werden sowohl die neuen als auch die alten Nachrichten 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. Dabei werden die Regeln für den Zusammenbruchsschlüssel berücksichtigt. Wenn eine Verbindung hergestellt wird, liefert FCM alle ausstehenden Nachrichten an das Gerät. Wenn das Gerät nie wieder verbunden wird (z. B. wenn es auf die Werkseinstellungen zurückgesetzt wurde), läuft die Meldung irgendwann 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 genauere Informationen zur Zustellung einer Nachricht:

Weitere Informationen zur Zustellung von Nachrichten auf Android- oder Apple-Plattformen finden Sie im FCMBerichtsdashboard. Dort werden die Anzahl der gesendeten und geöffneten Nachrichten auf Apple- und Android-Geräten sowie Daten zu „Impressionen“ (von Nutzern gesehene Benachrichtigungen) für Android-Apps erfasst.

Bei Android-Geräten mit aktivierten Direktnachrichten wird die Nachricht von FCM zwar akzeptiert, aber sofort verworfen, wenn das Gerät seit mehr als einem Monat keine Verbindung mehr zu FCM hergestellt hat. Wenn das Gerät innerhalb von vier Wochen nach der letzten von Ihnen gesendeten Datennachricht eine Verbindung herstellt, erhält Ihr Client den Rückruf onDeletedMessages(). Die App kann die Situation dann richtig verarbeiten, indem sie in der Regel eine vollständige Synchronisierung vom App-Server anfordert.

Wenn FCM schließlich versucht, eine Nachricht an das Gerät zu senden, die App aber 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.

Drosselung und Kontingente

Unser Ziel ist es, jede über FCM gesendete Nachricht zuzustellen. Allerdings kann es manchmal zu einer schlechten Nutzererfahrung führen, wenn alle Nachrichten gesendet werden. In anderen Fällen müssen wir Grenzen festlegen, damit FCM für alle Absender ein skalierbarer Dienst ist. Die in diesem Abschnitt beschriebenen Arten von Limits und Kontingenten helfen uns, diese wichtigen Faktoren auszubalancieren.

Hinweis: Die in diesem Abschnitt beschriebenen Limits können sich ändern.

Drosselung von Downstream-Nachrichten

Mit der HTTP v1 API wurden pro Projekt und pro Minute Kontingente für Downstream-Messaging eingeführt. Das Standardkontingent von 600.000 Nachrichten pro Minute deckt über 99% der FCM-Entwickler ab. Gleichzeitig wird die Stabilität des Systems gewährleistet und die Auswirkungen von Spitzenprojekten minimiert.

Starke Traffic-Muster können zu Fehlern bei Kontingentüberschreitungen führen. Wenn das Kontingent überschritten wird, gibt das System den HTTP-Statuscode 429 (QUOTA_EXCEEDED) zurück, bis das Kontingent in der nächsten Minute wieder aufgefüllt ist. Bei Überlastung können auch 429-Antworten zurückgegeben werden. Daher wird dringend empfohlen, 429-Antworten gemäß den veröffentlichten Empfehlungen zu verarbeiten.

Hinweis:

• Das nachgelagerte Kontingent misst Nachrichten, keine Anfragen.
• Clientfehler (HTTP-Statuscode 400–499) werden gezählt (außer 429).
• Die Kontingente gelten pro Minute, aber diese Minuten sind nicht auf die Uhr abgestimmt.

Kontingent für Monitoring

Kontingent, Nutzung und Fehler können Sie in der Google Cloud Console einsehen:

1. Zur Google Cloud-Konsole
2. Wählen Sie APIs und Dienste aus.
3. Wählen Sie in der Tabellenliste Firebase Cloud Messaging API aus.
4. Wählen Sie Kontingente und Systemlimits aus.

HINWEIS: Diese Grafiken sind nicht genau zeitlich auf die Kontingentminuten abgestimmt. Das bedeutet, dass 429-Antworten ausgegeben werden können, wenn der Traffic unter dem Kontingent liegt.

Kontingenterhöhung anfordern

Bevor Sie eine Kontingenterhöhung beantragen, müssen folgende Voraussetzungen erfüllt sein:

• Ihre Nutzung liegt regelmäßig mindestens 5 Minuten am Tag lang über 80 % des Kontingents.
• Die Clientfehlerrate liegt unter 5 %, insbesondere bei Spitzenauslastungen.
• Sie halten sich an die Best Practices für das Senden von Nachrichten im großen Umfang.

Wenn Sie diese Kriterien erfüllen, können Sie eine Anfrage zur Kontingenterhöhung um bis zu 25% stellen. FCM wird dann alles tun, um der Anfrage nachzukommen. Eine Erhöhung ist nicht garantiert.

Wenn Sie aufgrund eines bevorstehenden Starts oder eines temporären Ereignisses ein größeres Downstream-Messaging-Kontingent benötigen, fordern Sie Ihr Kontingent mindestens 15 Tage im Voraus an, damit genügend Zeit für die Bearbeitung der Anfrage bleibt. Bei großen Anfragen (mehr als 18 Millionen Nachrichten pro Minute) ist eine Vorabankündigung von mindestens 30 Tagen erforderlich. Für Launches und Anfragen zu Sonderereignissen gelten weiterhin die Anforderungen an das Verhältnis von Clientfehlern und Best Practices.

Weitere Informationen finden Sie in den häufig gestellten Fragen zu FCM-Kontingenten.

Maximale Anzahl von Themennachrichten

Die Rate für das Hinzufügen/Entfernen von Themenabos ist auf 3.000 Abfragen pro Sekunde pro Projekt beschränkt.

Informationen zu den Nachrichtenausgangsraten finden Sie unter Fan-out-Drosselung.

Fan-out-Drosselung

Beim Fan-out wird eine Nachricht an mehrere Geräte gesendet. Das ist beispielsweise der Fall, wenn Sie das Targeting auf Themen und Gruppen ausrichten oder den Benachrichtigungs-Editor verwenden, um das Targeting auf Zielgruppen oder Nutzersegmente auszurichten.

Die Nachrichtenweiterleitung erfolgt nicht sofort. Daher werden manchmal mehrere Weiterleitungen gleichzeitig ausgeführt. Die Anzahl gleichzeitiger Nachrichtenfanouts pro Projekt ist auf 1.000 beschränkt. Danach können wir zusätzliche Anfragen für die Verzweigung ablehnen oder die Verzweigung der Anfragen verschieben, bis einige der bereits laufenden Verzweigungen abgeschlossen sind.

Die tatsächlich erreichbare Fan-out-Rate wird von der Anzahl der Projekte beeinflusst, für die gleichzeitig Fan-outs angefordert werden. Eine Fan-out-Rate von 10.000 Abfragen pro Sekunde für ein einzelnes Projekt ist nicht ungewöhnlich. Diese Zahl ist jedoch keine Garantie und ergibt sich aus der Gesamtlast auf das System. Die verfügbare Fan-out-Kapazität wird auf Projekte und nicht auf Fan-out-Anfragen verteilt. Wenn für Ihr Projekt also zwei Verzweigungen ausgeführt werden, wird für jede Verzweigung nur die Hälfte der verfügbaren Verzweigungsrate verwendet. Um die Fanout-Geschwindigkeit zu maximieren, sollten Sie immer nur einen aktiven Fanout haben.

Minimierung von Nachrichten

Wie oben beschrieben, sind minimierbare Meldungen benachrichtigungsfreie Meldungen, die übereinander minimiert werden können. Wenn ein Entwickler dieselbe Nachricht zu häufig an eine App wiederholt, werden Nachrichten verzögert und gedrosselt, um den Akku eines Nutzers zu schonen.

Wenn Sie beispielsweise eine große Anzahl neuer E-Mail-Synchronisierungsanfragen an ein einzelnes Gerät senden, kann sich die nächste E-Mail-Synchronisierungsanfrage um einige Minuten verzögern, damit das Gerät mit einer geringeren durchschnittlichen Synchronisierungsrate synchronisiert werden kann. Diese Drosselung dient ausschließlich dazu, die Auswirkungen auf den Akku des Nutzers zu begrenzen.

Wenn Ihr Anwendungsfall hohe Burst-Sendemuster erfordert, sind nicht minimierbare Nachrichten möglicherweise die richtige Wahl. Achten Sie bei solchen Nachrichten darauf, den Inhalt in die Nachrichten aufzunehmen, um den Akkuverbrauch zu reduzieren.

Wir beschränken minimierte Nachrichten auf einen Burst von 20 Nachrichten pro App und Gerät, wobei alle 3 Minuten eine Nachricht nachgeladen wird.

Drosselung des XMPP-Servers

Achtung: Das Senden von Nachrichten (einschließlich Upstream-Nachrichten) mit den FCMXMPP- und HTTP-Legacy-APIs wurde am 20. Juni 2023 eingestellt und wird ab Juni 2024 entfernt. Wenn Sie die bisherigen FCM-Sende-APIs verwenden, empfehlen wir Ihnen dringend, zur HTTP v1 API zu migrieren oder das Admin SDK zum Erstellen von Sendeanfragen zu verwenden.

Wir begrenzen die Rate, mit der Sie eine Verbindung zu FCM-XMPP-Servern herstellen können, auf 400 Verbindungen pro Minute und Projekt. Dies sollte kein Problem für die Nachrichtenübermittlung darstellen, ist aber wichtig für die Stabilität des Systems. Für jedes Projekt erlaubt FCM 2.500 parallele Verbindungen.

Bei Upstream-Messaging mit XMPP begrenzt FCM die Anzahl der Upstream-Nachrichten auf 1.500.000 pro Minute und pro Projekt, um eine Überlastung der Upstream-Zielordner zu vermeiden.

Wir begrenzen Upstream-Nachrichten pro Gerät auf 1.000 pro Minute, um zu verhindern, dass der Akku durch schlechtes App-Verhalten entladen wird.

Maximale Nachrichtenrate für ein einzelnes Gerät

Unter Android können Sie bis zu 240 Nachrichten pro Minute und 5.000 Nachrichten pro Stunde an ein einzelnes Gerät senden. Dieser hohe Grenzwert soll kurzfristige Zugriffsspitzen abdecken, z. B. wenn Nutzer schnell über den Chat interagieren. Dieses Limit verhindert, dass Fehler in der Sendelogik den Akku eines Geräts versehentlich entladen.

Bei iOS wird ein Fehler zurückgegeben, wenn die Rate die APN-Limits überschreitet.

Achtung: Senden Sie nicht regelmäßig Nachrichten in der Nähe dieser maximalen Rate. Dies könnte die Ressourcen der Endnutzer verschwenden und Ihre App wird möglicherweise als missbräuchlich gekennzeichnet.

FCM-Ports und Ihre Firewall

Wenn Ihre Organisation eine Firewall hat, um den Traffic zu oder vom Internet einzuschränken, müssen Sie sie so konfigurieren, dass Mobilgeräte eine Verbindung zu FCM herstellen können, damit Geräte in Ihrem Netzwerk Nachrichten empfangen können. Für FCM wird normalerweise der Port 5228 verwendet, manchmal aber auch 443, 5229 und 5230.

Für Geräte, die eine Verbindung zu Ihrem Netzwerk herstellen, stellt FCM keine bestimmten IP-Adressen bereit, da sich unser IP-Bereich zu häufig ändert und Ihre Firewallregeln möglicherweise veraltet sind, was sich auf die Nutzerfreundlichkeit auswirken kann. Idealerweise sollten die Ports 5228–5230 und 443 ohne IP-Einschränkungen auf die Zulassungsliste gesetzt werden. Wenn jedoch eine IP-Einschränkung erforderlich ist, sollten Sie alle in goog.json aufgeführten IP-Adressen auf die Zulassungsliste setzen. Diese umfangreiche Liste wird regelmäßig aktualisiert. Wir empfehlen Ihnen, Ihre Regeln monatlich zu aktualisieren. Probleme, die durch Firewall-IP-Einschränkungen verursacht werden, treten oft nur sporadisch auf und sind schwer zu diagnostizieren.

Wir bieten eine Reihe von Domainnamen an, die anstelle von IP-Adressen auf die Zulassungsliste gesetzt werden können. Diese Hostnamen sind unten aufgeführt. Sollten wir zusätzliche Hostnamen verwenden, aktualisieren wir die Liste hier. Ob die Verwendung von Domainnamen für Ihre Firewallregel auf Ihrem Firewallgerät funktioniert, ist nicht vorhersehbar.

Zu öffnende TCP-Ports:

• 5228
• 5229
• 5230
• 443

Zu öffnende Hostnamen:

• mtalk.google.com
• mtalk4.google.com
• mtalk-staging.google.com
• mtalk-dev.google.com
• alt1-mtalk.google.com
• alt2-mtalk.google.com
• alt3-mtalk.google.com
• alt4-mtalk.google.com
• alt5-mtalk.google.com
• alt6-mtalk.google.com
• alt7-mtalk.google.com
• alt8-mtalk.google.com
• android.apis.google.com
• device-provisioning.googleapis.com
• firebaseinstallations.googleapis.com

Network Address Translation- und/oder stateful packet inspection-Firewalls:

Wenn in Ihrem Netzwerk Network Address Translation (NAT) oder Stateful Packet Inspection (SPI) implementiert ist, legen Sie für unsere Verbindungen über die Ports 5228–5230 ein Zeitlimit von mindestens 30 Minuten fest. So können wir eine zuverlässige Verbindung herstellen und gleichzeitig den Akkuverbrauch der Mobilgeräte Ihrer Nutzer reduzieren.

Hinweis: Wenn Sie Benachrichtigungen über APNs erhalten, müssen Sie auch die von Apple angegebenen Ports öffnen.

VPN-Interaktionen und Umgehung

Firebase Cloud Messaging ergreift verschiedene Maßnahmen, um dafür zu sorgen, dass die Push-Messaging-Verbindung vom Smartphone zum Server zuverlässig und so oft wie möglich verfügbar ist. Die Verwendung eines VPN erschwert diese Aufgabe.

VPNs verbergen die zugrunde liegenden Informationen, die FCM benötigt, um die Verbindung zu optimieren und so die Zuverlässigkeit und Akkulaufzeit zu maximieren. In einigen Fällen trennen VPNs aktiv langlebige Verbindungen, was zu einer schlechten Nutzererfahrung aufgrund von verpassten oder verzögerten Nachrichten oder hohen Akkukosten führt. Wenn das VPN entsprechend konfiguriert ist, umgehen wir das VPN mithilfe einer verschlüsselten Verbindung (über das Basisnetzwerk-WLAN oder LTE), um eine zuverlässige und akkufreundliche Nutzung zu gewährleisten. Die Nutzung umgehbarer VPNs durch FCM gilt speziell für den Push-Benachrichtigungskanal FCM. Anderer FCM-Traffic, z. B. Registrierungstraffic, verwendet das VPN, wenn es aktiv ist. Wenn die FCM-Verbindung das VPN umgeht, gehen zusätzliche Vorteile verloren, die das VPN bieten kann, z. B. die IP-Maskierung.

Unterschiedliche VPNs haben unterschiedliche Methoden, um zu steuern, ob sie umgangen werden können oder nicht. Eine Anleitung dazu finden Sie in der Dokumentation Ihres jeweiligen VPN.

Wenn das VPN nicht so konfiguriert ist, dass es umgangen werden kann, verwendet Firebase Cloud Messaging das VPN-Netzwerk, um eine Verbindung zum Server herzustellen. Dies kann zu Zeiträumen führen, in denen Nachrichten verzögert werden, und zu einer höheren Akkunutzung führen, da Cloud Messaging versucht, die Verbindung über die VPN-Verbindung aufrechtzuerhalten.

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 Console im Bereich Einstellungen verfügbar.
Registrierungstoken	Ein eindeutiger Tokenstring, der jede Client-App-Instanz identifiziert. Das Registrierungstoken ist für Nachrichten 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 erstellt wurde. Er ist auf dem Tab Cloud Messaging im Bereich Einstellungen der Firebase Console verfügbar. Anhand der Absender-ID wird jeder Absender identifiziert, der Nachrichten an die Clientanwendung 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.
Serverschlüssel (für **veraltete** Legacy-Protokolle)	Ein Serverschlüssel, der Ihren App-Server für den Zugriff auf Google-Dienste autorisiert, einschließlich des Sendens von Nachrichten über die eingestellten Firebase Cloud Messaging-Legacy-Protokolle. Wichtig: Fügen Sie den Serverschlüssel nicht in Ihren Clientcode ein. Verwenden Sie außerdem nur Serverschlüssel, um Ihren App-Server zu autorisieren. Android-, Apple-Plattform- und Browserschlüssel werden von FCM abgelehnt.