Google is committed to advancing racial equity for Black communities. See how.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Votre environnement serveur et FCM

Le côté serveur de Firebase Cloud Messaging se compose de deux composants:

  • Le backend FCM fourni par Google.
  • Votre serveur d'applications ou tout autre environnement de serveur de confiance dans lequel la logique de votre serveur s'exécute, comme Cloud Functions for Firebase ou d'autres environnements cloud gérés par Google.

Votre serveur d'applications ou votre environnement de serveur approuvé envoie des demandes de messages au backend FCM, qui achemine ensuite les messages vers les applications clientes exécutées sur les appareils des utilisateurs.

Conditions requises pour l'environnement de serveur approuvé

Votre environnement de serveur d'applications doit répondre aux critères suivants:

  • Capable d'envoyer des demandes de message correctement formatées au backend FCM.
  • Capable de gérer les demandes et de les renvoyer en utilisant un back-off exponentiel.
  • Capable de stocker en toute sécurité les informations d'identification d'autorisation du serveur et les jetons d'enregistrement client.
  • Pour le protocole XMPP (s'il est utilisé), le serveur doit être capable de générer des ID de message pour identifier de manière unique chaque message qu'il envoie (le backend HTTP FCM génère des ID de message et les renvoie dans la réponse). Les ID de message XMPP doivent être uniques par ID d'expéditeur.

Choisir une option de serveur

Vous devrez décider d'un moyen d'interagir avec les serveurs FCM: soit en utilisant le SDK Firebase Admin ou les protocoles bruts. En raison de sa prise en charge dans les langages de programmation courants et de ses méthodes pratiques pour gérer l'authentification et l'autorisation, le SDK Firebase Admin est la méthode recommandée.

Les options d'interaction avec les serveurs FCM sont les suivantes:
  • Le SDK d'administration Firebase, qui prend en charge Node , Java , Python , C # et Go .
  • L' API FCM HTTP v1 , qui est la plus à jour des options de protocole, avec une autorisation plus sécurisée et des capacités de messagerie multiplateforme flexibles (le SDK Firebase Admin est basé sur ce protocole et offre tous ses avantages inhérents).
  • Le protocole HTTP hérité.
  • Le protocole du serveur XMPP . Notez que si vous souhaitez utiliser la messagerie en amont depuis vos applications clientes, vous devez utiliser XMPP.

SDK d'administration Firebase pour FCM

L'API Admin FCM gère l'authentification avec le backend et facilite l'envoi de messages et la gestion des abonnements aux rubriques. Avec le SDK Firebase Admin, vous pouvez:

  • Envoyer des messages à des appareils individuels
  • Envoyez des messages à des sujets et des déclarations de condition qui correspondent à un ou plusieurs sujets.
  • Abonnez-vous et désabonnez des appareils vers et depuis des sujets
  • Construire des charges utiles de messages adaptées à différentes plates-formes cibles

Le SDK Admin Node.js fournit des méthodes pour envoyer des messages à des groupes d'appareils.

Pour configurer le SDK Firebase Admin, consultez Ajouter le SDK Firebase Admin à votre serveur . Si vous disposez déjà d'un projet Firebase, commencez par Ajouter le SDK . Ensuite, une fois que le SDK Firebase Admin est installé, vous pouvez commencer à écrire une logique pour créer des demandes d'envoi .

Protocoles de serveur FCM

Actuellement, FCM fournit ces protocoles de serveur bruts:

Votre serveur d'applications peut utiliser ces protocoles séparément ou en tandem. Étant donné qu'il s'agit de la solution la plus à jour et la plus flexible pour l'envoi de messages à plusieurs plates-formes, l'API FCM HTTP v1 est recommandée dans la mesure du possible. Si vos exigences incluent la messagerie en amont des appareils vers le serveur, vous devrez implémenter le protocole XMPP.

La messagerie XMPP diffère de la messagerie HTTP des manières suivantes:

  • Messages en amont / en aval
    • HTTP: en aval uniquement, cloud-à-appareil.
    • XMPP: en amont et en aval (appareil à cloud, cloud à appareil).
  • Messagerie (synchrone ou asynchrone)
    • HTTP: synchrone. Les serveurs d'applications envoient des messages sous forme de requêtes HTTP POST et attendent une réponse. Ce mécanisme est synchrone et empêche l'expéditeur d'envoyer un autre message jusqu'à ce que la réponse soit reçue.
    • XMPP: asynchrone. Les serveurs d'applications envoient / reçoivent des messages vers / depuis tous leurs appareils à pleine vitesse de ligne via des connexions XMPP persistantes. Le serveur de connexion XMPP envoie des notifications d'accusé de réception ou d'échec (sous la forme de messages XMPP spéciaux ACK et NACK codés JSON) de manière asynchrone.
  • JSON
    • HTTP: messages JSON envoyés en tant que HTTP POST.
    • XMPP: messages JSON encapsulés dans des messages XMPP.
  • Texte brut
    • HTTP: messages en texte brut envoyés en tant que HTTP POST.
    • XMPP: non pris en charge.
  • Multicast en aval envoyer à plusieurs jetons d'enregistrement.
    • HTTP: pris en charge dans le format de message JSON.
    • XMPP: non pris en charge.

Implémentation du protocole de serveur HTTP

Pour envoyer un message, le serveur d'application émet une requête POST avec un en-tête HTTP et un corps HTTP composé de paires de valeurs de clé JSON. Pour plus d'informations sur les options d'en-tête et de corps, voir Créer des demandes d'envoi de serveur d'applications

Implémentation du protocole serveur XMPP

La charge utile JSON pour les messages FCM est similaire au protocole HTTP, avec ces exceptions:

  • Il n'y a pas de prise en charge pour plusieurs destinataires.
  • FCM ajoute le champ message_id , qui est obligatoire. Cet ID identifie de manière unique le message dans une connexion XMPP. L'ACK ou NACK de FCM utilise le message_id pour identifier un message envoyé des serveurs d'applications à FCM. Par conséquent, il est important que ce message_id non seulement unique (par ID d'expéditeur ), mais toujours présent.
  • XMPP utilise la clé de serveur pour autoriser une connexion persistante à FCM. Voir Autoriser les demandes d'envoi pour plus d'informations.

En plus des messages FCM normaux, des messages de contrôle sont envoyés, indiqués par le champ message_type dans l'objet JSON. La valeur peut être «ack» ou «nack» ou «control» (voir les formats ci-dessous). Tout message FCM avec un message_type inconnu peut être ignoré par votre serveur.

Pour chaque message d'appareil que votre serveur d'application reçoit de FCM, il doit envoyer un message ACK. Il n'a jamais besoin d'envoyer un message NACK. Si vous n'envoyez pas un ACK pour un message, FCM le renvoie la prochaine fois qu'une nouvelle connexion XMPP est établie, à moins que le message n'expire d'abord.

FCM envoie également un ACK ou NACK pour chaque message de serveur à périphérique. Si vous ne recevez pas non plus, cela signifie que la connexion TCP a été fermée au milieu de l'opération et que votre serveur doit renvoyer les messages. Voir Contrôle de flux pour plus de détails.

Voir la référence de protocole pour une liste de tous les paramètres de message.

Format de la demande

Message avec charge utile - message de notification

Voici une strophe XMPP pour un message de notification:

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

Message avec charge utile - message de données

Voici une strophe XMPP contenant le message JSON d'un serveur d'application à FCM:

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

Format de réponse

Une réponse FCM peut avoir trois formes possibles. Le premier est un message régulier d'acquittement. Mais lorsque la réponse contient une erreur, le message peut prendre 2 formes différentes, décrites ci-dessous.

Message ACK

Voici une strophe XMPP contenant le message ACK / NACK de FCM au serveur d'application:

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

Message NACK

Une erreur NACK est un message XMPP normal dans lequel le message d'état message_type est "nack". Un message NACK contient:

  • Un code d'erreur NACK.
  • Une description d'erreur NACK.

Voici quelques exemples.

Mauvaise inscription:

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

JSON non valide:

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

Débit de messages de l'appareil dépassé:

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

Consultez la référence du serveur pour une liste complète des codes d'erreur NACK. Sauf indication contraire, un message NACKed ne doit pas être retenté. Les codes d'erreur NACK inattendus doivent être traités de la même manière que INTERNAL_SERVER_ERROR .

Erreur de strophe

Vous pouvez également obtenir une erreur de strophe dans certains cas. Une erreur de strophe contient:

  • Code d'erreur de strophe.
  • Description de l'erreur de strophe (texte libre).

Par exemple:

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

Messages de contrôle

Régulièrement, FCM doit fermer une connexion pour effectuer l'équilibrage de charge. Avant de fermer la connexion, FCM envoie un message CONNECTION_DRAINING pour indiquer que la connexion est en cours de vidange et sera bientôt fermée. «Vidange» fait référence à l'arrêt du flux de messages entrant dans une connexion, mais permettant à tout ce qui est déjà dans le pipeline de continuer. Lorsque vous recevez un message CONNECTION_DRAINING , vous devez immédiatement commencer à envoyer des messages à une autre connexion FCM, en ouvrant une nouvelle connexion si nécessaire. Vous devez, cependant, garder la connexion d'origine ouverte et continuer à recevoir les messages qui peuvent arriver sur la connexion (et les ACK) —FCM gère l'initiation d'une connexion fermée lorsqu'elle est prête.

Le message CONNECTION_DRAINING ressemble à ceci:

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

CONNECTION_DRAINING est actuellement le seul type de control_type pris en charge.

Contrôle de flux

Chaque message envoyé à FCM reçoit une réponse ACK ou NACK. Les messages qui n'ont pas reçu l'une de ces réponses sont considérés comme en attente. Si le nombre de messages en attente atteint 100, le serveur d'application doit arrêter d'envoyer de nouveaux messages et attendre que FCM acquitte certains des messages en attente existants, comme illustré dans la figure 1:

Figure 1. Flux de message / accusé de réception.

Inversement, pour éviter de surcharger le serveur d'applications, FCM arrête l'envoi s'il y a trop de messages non acquittés. Par conséquent, le serveur d'application doit «ACK» les messages en amont, reçus de l'application client via FCM, dès que possible pour maintenir un flux constant de messages entrants. La limite de messages en attente susmentionnée ne s'applique pas à ces ACK. Même si le nombre de messages en attente atteint 100, le serveur d'application doit continuer à envoyer des ACK pour les messages reçus de FCM pour éviter de bloquer la remise de nouveaux messages en amont.

Les ACK ne sont valides que dans le contexte d'une seule connexion. Si la connexion est fermée avant qu'un message puisse être ACKé, le serveur d'application doit attendre que FCM renvoie le message en amont avant de l'acquitter à nouveau. De même, tous les messages en attente pour lesquels un ACK / NACK n'a pas été reçu de FCM avant la fermeture de la connexion doivent être renvoyés.