Google setzt sich dafür ein, die Rassengerechtigkeit für schwarze Gemeinschaften zu fördern. Siehe wie.
Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

Ihre Serverumgebung und FCM

Die Serverseite von Firebase Cloud Messaging besteht aus zwei Komponenten:

  • Das von Google bereitgestellte FCM-Backend .
  • Ihr App-Server oder eine andere vertrauenswürdige Serverumgebung, in der Ihre Serverlogik ausgeführt wird, z. B. Cloud-Funktionen für Firebase oder andere von Google verwaltete Cloud-Umgebungen.

Ihr App-Server oder Ihre vertrauenswürdige Serverumgebung sendet Nachrichtenanforderungen an das FCM-Backend, das Nachrichten an Client-Apps weiterleitet, die auf den Geräten der Benutzer ausgeführt werden.

Anforderungen an die vertrauenswürdige Serverumgebung

Ihre App Server-Umgebung muss die folgenden Kriterien erfüllen:

  • Kann ordnungsgemäß formatierte Nachrichtenanforderungen an das FCM-Backend senden.
  • Kann Anfragen bearbeiten und mit exponentiellem Backoff erneut senden .
  • Kann Serverautorisierungsdaten und Clientregistrierungstoken sicher speichern.
  • Für das XMPP-Protokoll (falls verwendet) muss der Server in der Lage sein, Nachrichten-IDs zu generieren, um jede gesendete Nachricht eindeutig zu identifizieren (das FCM-HTTP-Backend generiert Nachrichten-IDs und gibt sie in der Antwort zurück). XMPP-Nachrichten-IDs sollten pro Absender-ID eindeutig sein.

Serveroption auswählen

Sie müssen sich für eine Art der Interaktion mit FCM-Servern entscheiden: entweder mithilfe des Firebase Admin SDK oder der Raw-Protokolle. Aufgrund seiner Unterstützung für gängige Programmiersprachen und seiner praktischen Methoden für die Authentifizierung und Autorisierung wird das Firebase Admin SDK empfohlen.

Folgende Optionen für die Interaktion mit FCM-Servern stehen zur Verfügung:

Firebase Admin SDK für FCM

Die Admin FCM-API verwaltet die Authentifizierung beim Backend und erleichtert das Senden von Nachrichten und das Verwalten von Themenabonnements. Mit dem Firebase Admin SDK können Sie:

  • Senden Sie Nachrichten an einzelne Geräte
  • Senden Sie Nachrichten an Themen und Bedingungsanweisungen, die einem oder mehreren Themen entsprechen.
  • Abonnieren und Abbestellen von Geräten zu und von Themen
  • Erstellen Sie Nachrichtennutzdaten, die auf verschiedene Zielplattformen zugeschnitten sind

Das Admin Node.js SDK bietet Methoden zum Senden von Nachrichten an Gerätegruppen.

Informationen zum Einrichten des Firebase Admin SDK finden Sie unter Hinzufügen des Firebase Admin SDK zu Ihrem Server . Wenn Sie bereits ein Firebase-Projekt haben, beginnen Sie mit Hinzufügen des SDK . Sobald das Firebase Admin SDK installiert ist, können Sie mit dem Schreiben von Logik zum Erstellen von Sendeanforderungen beginnen .

FCM-Serverprotokolle

Derzeit bietet FCM folgende Raw-Server-Protokolle an:

Ihr App-Server kann diese Protokolle separat oder zusammen verwenden. Da es am aktuellsten und flexibelsten ist, Nachrichten an mehrere Plattformen zu senden, wird die FCM HTTP v1-API empfohlen, wo immer dies möglich ist. Wenn Ihre Anforderungen Upstream-Nachrichten von Geräten an den Server umfassen, müssen Sie das XMPP-Protokoll implementieren.

XMPP-Nachrichten unterscheiden sich von HTTP-Nachrichten in folgenden Punkten:

  • Upstream / Downstream-Nachrichten
    • HTTP: Nur Downstream, Cloud-to-Device.
    • XMPP: Upstream und Downstream (Gerät-zu-Cloud, Cloud-zu-Gerät).
  • Messaging (synchron oder asynchron)
    • HTTP: Synchron. App-Server senden Nachrichten als HTTP-POST-Anforderungen und warten auf eine Antwort. Dieser Mechanismus ist synchron und verhindert, dass der Absender eine weitere Nachricht sendet, bis die Antwort empfangen wird.
    • XMPP: Asynchron. App-Server senden / empfangen Nachrichten an alle Geräte mit voller Leitungsgeschwindigkeit über dauerhafte XMPP-Verbindungen. Der XMPP-Verbindungsserver sendet asynchron Bestätigungs- oder Fehlerbenachrichtigungen (in Form spezieller ACK- und NACK-JSON-codierter XMPP-Nachrichten).
  • JSON
    • HTTP: JSON-Nachrichten, die als HTTP-POST gesendet werden.
    • XMPP: JSON-Nachrichten, die in XMPP-Nachrichten gekapselt sind.
  • Klartext
    • HTTP: Nur-Text-Nachrichten, die als HTTP-POST gesendet werden.
    • XMPP: Wird nicht unterstützt.
  • Multicast-Downstream-Send an mehrere Registrierungstoken.
    • HTTP: Wird im JSON-Nachrichtenformat unterstützt.
    • XMPP: Wird nicht unterstützt.

Implementierung des HTTP-Serverprotokolls

Um eine Nachricht zu senden, gibt der App-Server eine POST-Anforderung mit einem HTTP-Header und einem HTTP-Body aus JSON-Schlüsselwertpaaren aus. Ausführliche Informationen zu den Header- und Body-Optionen finden Sie unter Build App Server-Sendeanforderungen

Implementierung des XMPP-Serverprotokolls

Die JSON-Nutzdaten für FCM-Nachrichten ähneln dem HTTP-Protokoll, mit folgenden Ausnahmen:

  • Es gibt keine Unterstützung für mehrere Empfänger.
  • FCM fügt das Feld message_id , das erforderlich ist. Diese ID identifiziert die Nachricht in einer XMPP-Verbindung eindeutig. Das ACK oder NACK von FCM verwendet die message_id , um eine Nachricht zu identifizieren, die von App-Servern an FCM gesendet wurde. Daher ist es wichtig, dass diese message_id nicht nur eindeutig (pro Absender-ID ), sondern immer vorhanden ist.
  • XMPP verwendet den Serverschlüssel, um eine dauerhafte Verbindung zu FCM zu autorisieren. Weitere Informationen finden Sie unter Autorisieren von Sendeanfragen .

Zusätzlich zu regulären FCM-Nachrichten werden Kontrollnachrichten gesendet, die durch das Feld message_type im JSON-Objekt angezeigt werden. Der Wert kann entweder 'ack' oder 'nack' oder 'control' sein (siehe Formate unten). Jede FCM-Nachricht mit einem unbekannten message_type kann von Ihrem Server ignoriert werden.

Für jede Gerätenachricht, die Ihr App-Server von FCM empfängt, muss er eine ACK-Nachricht senden. Es muss niemals eine NACK-Nachricht gesendet werden. Wenn Sie keine ACK für eine Nachricht senden, sendet FCM diese erneut, wenn eine neue XMPP-Verbindung hergestellt wird, es sei denn, die Nachricht läuft zuerst ab.

FCM sendet außerdem eine ACK oder NACK für jede Server-zu-Gerät-Nachricht. Wenn Sie auch keine empfangen, bedeutet dies, dass die TCP-Verbindung während des Vorgangs geschlossen wurde und Ihr Server die Nachrichten erneut senden muss. Siehe Flow Control für weitere Einzelheiten.

In der Protokollreferenz finden Sie eine Liste aller Nachrichtenparameter.

Anforderungsformat

Nachricht mit Nutzlast - Benachrichtigungsnachricht

Hier ist eine XMPP-Zeilengruppe für eine Benachrichtigungsnachricht:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
     "notification": {
        "title": "Portugal vs. Denmark”,
        "body”: "5 to 1”
      },
      "time_to_live":"600"
}

  }
  </gcm>
</message>

Nachricht mit Nutzlast - Datennachricht

Hier ist eine XMPP-Zeilengruppe, die die JSON-Nachricht von einem App-Server an FCM enthält:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "to":"REGISTRATION_ID",  // "to" replaces "registration_ids"
      "message_id":"m-1366082849205" // new required field
      "data":
      {
          "hello":"world",
      }
      "time_to_live":"600",
  }
  </gcm>
</message>

Antwortformat

Eine FCM-Antwort kann drei mögliche Formen haben. Die erste ist eine reguläre Bestätigungsnachricht. Wenn die Antwort jedoch einen Fehler enthält, kann die Nachricht zwei verschiedene Formen annehmen, die im Folgenden beschrieben werden.

ACK-Nachricht

Hier ist eine XMPP-Zeilengruppe mit der ACK / NACK-Nachricht von FCM an den App-Server:

<message id="">
  <gcm xmlns="google:mobile:data">
  {
      "from":"REGID",
      "message_id":"m-1366082849205"
      "message_type":"ack"
  }
  </gcm>
</message>

NACK-Nachricht

Ein NACK-Fehler ist eine reguläre XMPP-Nachricht, bei der die message_type "nack" lautet. Eine NACK-Nachricht enthält:

  • Ein NACK-Fehlercode.
  • Eine NACK-Fehlerbeschreibung.

Nachfolgend einige Beispiele.

Schlechte Registrierung:

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationId",
    "error":"BAD_REGISTRATION",
    "error_description":"Invalid token on 'to' field: SomeInvalidRegistrationId"
  }
  </gcm>
</message>

Ungültiger JSON:

<message>
 <gcm xmlns="google:mobile:data">
 {
   "message_type":"nack",
   "message_id":"msgId1",
   "from":"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
   "error":"INVALID_JSON",
   "error_description":"InvalidJson: JSON_TYPE_ERROR : Field \"time_to_live\" must be a JSON java.lang.Number: abc"
 }
 </gcm>
</message>

Gerätemeldungsrate überschritten:

<message id="...">
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"REGID",
    "error":"DEVICE_MESSAGE_RATE_EXCEEDED",
    "error_description":"Downstream message rate exceeded for this registration id"
  }
  </gcm>
</message>

Finden Sie in das Server - Handbuch für eine vollständige Liste des NACK - Fehlercodes. Sofern nicht anders angegeben, sollte eine NACKed-Nachricht nicht wiederholt werden. Unerwartete NACK-Fehlercodes sollten genauso behandelt werden wie INTERNAL_SERVER_ERROR .

Zeilengruppenfehler

In bestimmten Fällen kann auch ein Zeilengruppenfehler auftreten. Ein Zeilengruppenfehler enthält:

  • Zeilengruppenfehlercode.
  • Zeilengruppenfehlerbeschreibung (Freitext).

Beispielsweise:

<message id="3" type="error" to="123456789@fcm.googleapis.com/ABC">
  <gcm xmlns="google:mobile:data">
     {"random": "text"}
  </gcm>
  <error code="400" type="modify">
    <bad-request xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
    <text xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">
      InvalidJson: JSON_PARSING_ERROR : Missing Required Field: message_id\n
    </text>
  </error>
</message>

Kontrollmeldungen

In regelmäßigen Abständen muss FCM eine Verbindung schließen, um einen Lastausgleich durchzuführen. Bevor die Verbindung geschlossen wird, sendet FCM eine CONNECTION_DRAINING Nachricht, um anzuzeigen, dass die Verbindung CONNECTION_DRAINING wird und bald geschlossen wird. "Entleeren" bezieht sich auf das Unterbrechen des Nachrichtenflusses, der in eine Verbindung eingeht, aber das Fortfahren von allem, was sich bereits in der Pipeline befindet. Wenn Sie eine CONNECTION_DRAINING Nachricht erhalten, sollten Sie sofort mit dem Senden von Nachrichten an eine andere FCM-Verbindung beginnen und gegebenenfalls eine neue Verbindung herstellen. Sie sollten jedoch die ursprüngliche Verbindung offen lassen und weiterhin Nachrichten empfangen, die möglicherweise über die Verbindung eingehen (und diese bestätigen). FCM übernimmt das Initiieren eines Verbindungsabschlusses, wenn diese bereit ist.

Die Nachricht CONNECTION_DRAINING sieht folgendermaßen aus:

<message>
  <data:gcm xmlns:data="google:mobile:data">
  {
    "message_type":"control"
    "control_type":"CONNECTION_DRAINING"
  }
  </data:gcm>
</message>

CONNECTION_DRAINING ist derzeit der einzige unterstützte control_type .

Ablaufsteuerung

Jede an FCM gesendete Nachricht erhält entweder eine ACK- oder eine NACK-Antwort. Nachrichten, die keine dieser Antworten erhalten haben, gelten als ausstehend. Wenn die Anzahl der ausstehenden Nachrichten 100 erreicht, sollte der App-Server das Senden neuer Nachrichten beenden und darauf warten, dass FCM einige der vorhandenen ausstehenden Nachrichten bestätigt, wie in Abbildung 1 dargestellt:

Abbildung 1. Nachrichten- / Bestätigungsfluss.

Um den App-Server nicht zu überlasten, sendet FCM nicht mehr, wenn zu viele nicht bestätigte Nachrichten vorhanden sind. Daher sollte der App-Server Upstream-Nachrichten, die von der Client-Anwendung über FCM empfangen wurden, so schnell wie möglich "ACK", um einen konstanten Fluss eingehender Nachrichten aufrechtzuerhalten. Das oben genannte Limit für ausstehende Nachrichten gilt nicht für diese ACKs. Selbst wenn die Anzahl der ausstehenden Nachrichten 100 erreicht, sollte der App-Server weiterhin ACKs für von FCM empfangene Nachrichten senden, um zu vermeiden, dass die Zustellung neuer Upstream-Nachrichten blockiert wird.

ACKs sind nur im Kontext einer Verbindung gültig. Wenn die Verbindung geschlossen wird, bevor eine Nachricht bestätigt werden kann, sollte der App-Server warten, bis FCM die Upstream-Nachricht erneut sendet, bevor er sie erneut bestätigt. Ebenso sollten alle ausstehenden Nachrichten, für die vor dem Schließen der Verbindung kein ACK / NACK von FCM empfangen wurde, erneut gesendet werden.