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. Dort gilt ein Limit von 1.000 Zeichen.

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 eine vordefinierte Reihe von für den Nutzer sichtbaren Schlüsseln und eine optionale Datennutzlast mit benutzerdefinierten Schlüssel/Wert-Paaren.
  1. Verwenden Sie in einer vertrauenswürdigen Umgebung wie Cloud Functions oder auf Ihrem App-Server das Admin SDK oder die HTTP v1 API. Legen Sie den notification-Schlüssel fest. Kann eine optionale Datennutzlast haben. Sie können immer minimiert werden.

    Sehen Sie sich einige Beispiele für Displaybenachrichtigungen und Sende-Nutzlasten an.

  2. Mit dem Benachrichtigungs-Editor: Geben Sie den Text der Nachricht, den Titel usw. ein und senden Sie die Nachricht. Optionale Datennutzlast hinzufügen, 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.

Verwenden Sie Benachrichtigungsnachrichten, wenn das FCM SDK automatisch eine Benachrichtigung anzeigen soll, wenn Ihre 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 Benachrichtigungsnachricht mit einer optionalen Datennutzlast senden. In solchen Fällen wird die Anzeige der Benachrichtigungsnutzlast von FCM und die Datennutzlast von der Clientanwendung verarbeitet.

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 Console bietet analysenbasierte A/B-Tests, mit denen Sie Marketingbotschaften optimieren 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 ist beispielsweise eine Benachrichtigungsnachricht in einer Messaging-App im JSON-Format. Der Nutzer sollte auf dem Gerät eine Nachricht mit dem Titel „Portugal gegen Dänemark“ und dem Text „Guter Spiel!“ sehen:

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

Benachrichtigungsnachrichten werden an die Benachrichtigungsleiste 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.

Hier ist beispielsweise eine JSON-formatierte Nachricht in derselben IM-Anwendung wie oben, bei der die Informationen im gemeinsamen Schlüssel data 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

Die Android-Transportschicht (siehe FCM-Architektur) verwendet die 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.
  • Wenn sich die App im Vordergrund befindet, empfängt sie ein Nachrichtenobjekt 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"
    }
  }
}

Plattformübergreifende Anpassung einer Mitteilung

Sowohl das Firebase Admin SDK- als auch das FCM v1-HTTP-Protokoll ermöglichen es, in Ihren Nachrichtenanfragen alle im message-Objekt verfügbaren Felder festzulegen. 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 sollten gemeinsame Felder verwendet werden?

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:

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 Zustellungsoptionen senden, verwenden Sie platformspezifische Felder, um sie festzulegen. Du kannst pro 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 möglicherweise etwas anders interpretiert. So wird die Gültigkeitsdauer unter Android beispielsweise als Ablaufzeit in Sekunden festgelegt, während sie unter Apple als Ablaufdatum festgelegt wird.

Beispiel: Benachrichtigungsnachricht mit platformspezifischen Zustellungsoptionen

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

  • eine lange Gültigkeitsdauer für Android- und Webplattformen festlegt, während die Nachrichtenpriorität für APNs (Apple-Plattformen) auf eine niedrige Einstellung gesetzt wird
  • 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 platformspezifischen Blöcken im Nachrichtentext verfügbar sind, finden Sie in der Referenzdokumentation zu HTTP v1. 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. Das Verhalten „Zusammenklappbar“ wird beispielsweise unter Android über FCM mit collapse_key, unter Apple über apns-collapse-id und unter 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

Eine nicht minimierbare Meldung bedeutet, dass jede einzelne Nachricht an das Gerät gesendet wird. 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.

Typische Anwendungsfälle für nicht minimierbare Meldungen sind Chatnachrichten oder kritische Meldungen. 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. Sobald 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, in der Regel durch Anfordern einer vollständigen Synchronisierung vom App-Server.

Eine minimierbare Nachricht kann durch eine neue Nachricht ersetzt werden, 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 letzte 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. Standardmäßig ist der Zusammenklappungsschlüssel der Name des App-Pakets, das 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.FCM Diese Anzahl darf nicht überschritten werden, da dies unvorhersehbare Folgen haben kann.

Anwendungsszenario So senden Sie eine Nachricht
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 es eine neuere Nachricht gibt, die eine ältere, zugehörige Nachricht für die Client-App irrelevant macht, ersetzt FCM die ältere Nachricht. Beispiele: Nachrichten, mit denen eine Datensynchronisierung vom Server initiiert 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 eine Zustellpriorität zuzuweisen: normale und hohe Priorität. Das Verhalten unterscheidet sich zwar geringfügig je nach Plattform, die Zustellung von Nachrichten mit normaler und hoher Priorität funktioniert aber 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.

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:

Lebenswichtige Anwendungsfälle

Die FCM APIs sind nicht für Notfallwarnungen oder andere Aktivitäten mit hohem Risiko konzipiert, bei denen die Nutzung oder der Ausfall der APIs zu Tod, Verletzungen oder Umweltschäden führen könnte (z. B. der 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 in der Regel sofort 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 gar nicht“ 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 App-Server eine Nachricht an FCM postet und eine Nachrichten-ID zurück erhält, bedeutet das 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, aber im Ruhemodus ist, wird eine Nachricht mit niedriger Priorität von FCM gespeichert, bis der Ruhemodus 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 weitere 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. Die Zustellung jeder Nachricht führt jedoch manchmal zu einer schlechten Nutzererfahrung. 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.

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, schützt die Stabilität des Systems und minimiert die Auswirkungen von Spitzenprojekten.

Unregelmäßige Zugriffsmuster können zu Fehlern beim Überschreiten des Kontingents 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. Antworten vom Typ 429 können auch bei Überlastungen zurückgegeben werden. Wir empfehlen Ihnen daher dringend, 429-Antworten gemäß den veröffentlichten Empfehlungen zu behandeln.

Hinweis:

  • Das Downstream-Kontingent wird anhand von Nachrichten und nicht anhand von Anfragen gemessen.
  • Clientfehler (HTTP-Statuscode 400–499) werden gezählt (außer 429).
  • Die Kontingente gelten pro Minute, die Minutenzählung ist jedoch nicht an die Uhr gekoppelt.

Kontingent

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

  1. Rufen Sie die Google Cloud Console auf.
  2. Wählen Sie APIs & 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 lang pro Tag ü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 Kontingenterhöhung von bis zu 25% beantragen. FCM wird sich bemühen, Ihrem Antrag nachzukommen. Eine Erhöhung kann jedoch nicht garantiert werden.

Wenn Sie aufgrund einer bevorstehenden Markteinführung oder eines vorübergehenden Ereignisses mehr Kontingent für Downstream-Messaging benötigen, beantragen Sie Ihr Kontingent mindestens 15 Tage im Voraus, damit wir genügend Zeit haben, die Anfrage zu bearbeiten. 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.

Limit für Themennachrichten

Die Rate für das Hinzufügen und 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, steht für jede Verzweigung nur die Hälfte der verfügbaren Verzweigungsrate zur Verfügung. Um die Fanout-Geschwindigkeit zu maximieren, sollten Sie immer nur einen aktiven Fanout haben.

Drosselung von minimierten Nachrichten

Wie oben beschrieben, sind minimierbare Meldungen benachrichtigungsfreie Meldungen, die übereinander minimiert werden können. Wenn ein Entwickler dieselbe Nachricht für eine App zu oft wiederholt, verzögern wir die Nachrichten, um die Auswirkungen auf den Akku des Nutzers zu reduzieren.

Wenn Sie beispielsweise eine große Anzahl neuer E-Mail-Synchronisierungsanfragen an ein einzelnes Gerät senden, verzögern wir die nächste E-Mail-Synchronisierungsanfrage möglicherweise um einige Minuten, damit das Gerät mit einer niedrigeren durchschnittlichen Rate synchronisiert werden kann. Diese Drosselung dient ausschließlich dazu, die Auswirkungen auf den Akku für den Nutzer zu begrenzen.

Wenn Ihr Anwendungsfall hohe Burst-Sendemuster erfordert, sind nicht minimierbare Nachrichten möglicherweise die richtige Wahl. Fügen Sie bei solchen Nachrichten den Inhalt hinzu, um den Akkuverbrauch zu senken.

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

Die Häufigkeit, mit der Sie eine Verbindung zu FCM-XMPP-Servern herstellen können, ist auf 400 Verbindungen pro Minute und Projekt beschränkt. 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 die Anzahl der Upstream-Nachrichten pro Gerät auf 1.000 pro Minute,um den Akku vor dem Entladen durch schädliches App-Verhalten zu schützen.

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.

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 Sie jedoch eine IP-Einschränkung benötigen, 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. Die Verwendung von Domainnamen für Ihre Firewallregel funktioniert auf Ihrem Firewallgerät möglicherweise nicht.

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, müssen Sie für unsere Verbindungen über die Ports 5228–5230 ein Zeitlimit von mindestens 30 Minuten festlegen. So können wir eine zuverlässige Verbindung bieten und gleichzeitig den Akkuverbrauch der Mobilgeräte Ihrer Nutzer reduzieren.

VPN-Interaktionen und Umgehungsmöglichkeiten

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 VPNs 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 so konfiguriert ist, dass wir dies tun können, umgehen wir das VPN mit einer verschlüsselten Verbindung (über das Basisnetzwerk, WLAN oder LTE), um eine zuverlässige, Akku schonende Nutzung zu ermöglichen. Die Verwendung von umgehbaren VPNs durch FCM ist spezifisch für den FCM-Push-Benachrichtigungskanal. Anderer FCM-Traffic, z. B. Registrierungstraffic, verwendet das VPN, wenn es aktiv ist. Wenn die FCM-Verbindung das VPN umgeht, gehen zusätzliche Vorteile des VPN verloren, z. B. die IP-Maskierung.

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

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 Verzögerungen bei Nachrichten führen und die Akkunutzung erhöhen, da Cloud Messaging die Verbindung über die VPN-Verbindung aufrechterhalten muss.

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 im Bereich Einstellungen der Firebase-Konsole verfügbar.
Registrierungstoken

Ein eindeutiger Token-String, 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.