Check out what’s new from Firebase@ Google I/O 2021, and join our alpha program for early access to the new Remote Config personalization feature. Learn more

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 un autre environnement de serveur de confiance sur lequel votre logique de serveur s'exécute, comme Cloud Functions for Firebase ou d'autres environnements cloud gérés par Google.

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

Exigences pour l'environnement de serveur de confiance

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 choisir un moyen d'interagir avec les serveurs FCM : soit à l'aide du SDK Firebase Admin, soit à l'aide des protocoles bruts. En raison de sa prise en charge des langages de programmation courants et de ses méthodes pratiques de gestion de l'authentification et de 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 Firebase Admin, qui prend en charge Node , Java , Python , C# et Go .
  • L' API FCM HTTP v1 , qui est la plus récente des options de protocole, avec une autorisation plus sécurisée et des capacités de messagerie multiplateformes flexibles (le SDK Firebase Admin est basé sur ce protocole et offre tous ses avantages inhérents).
  • L'ancien protocole HTTP .
  • Le protocole du serveur XMPP . Notez que si vous souhaitez utiliser la messagerie en amont de 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 aux rubriques et aux déclarations de condition qui correspondent à une ou plusieurs rubriques.
  • S'abonner et se désabonner des appareils vers et depuis des sujets
  • Construire des charges utiles de messages adaptées aux 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 Admin Firebase, consultez Ajouter le SDK Admin Firebase à votre serveur . Si vous avez déjà un projet Firebase, commencez par Ajouter le SDK . Ensuite, une fois le SDK Firebase Admin 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. Parce qu'elle est la plus à jour et la plus flexible pour envoyer des messages à plusieurs plates-formes, l'API FCM HTTP v1 est recommandée dans la mesure du possible. Si vos besoins 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 (de périphérique à cloud, de cloud à périphérique).
  • 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/de tous leurs appareils à pleine vitesse sur 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 codés ACK et NACK JSON) de manière asynchrone.
  • JSON
    • HTTP : messages JSON envoyés en HTTP POST.
    • XMPP : messages JSON encapsulés dans des messages XMPP.
  • Texte brut
    • HTTP : messages en texte brut envoyés en HTTP POST.
    • XMPP : non pris en charge.
  • Envoi multidiffusion en aval vers plusieurs jetons d'enregistrement.
    • HTTP : pris en charge au format de message JSON.
    • XMPP : non pris en charge.

Implémentation du protocole de serveur HTTP

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

Implémentation du protocole de serveur XMPP

La charge utile JSON pour les messages FCM est similaire au protocole HTTP, à quelques exceptions près :

  • 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 le 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é du serveur pour autoriser une connexion persistante à FCM. Voir Autoriser l'envoi de demandes pour plus d'informations.

En plus des messages FCM réguliers, 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 de la FCM avec un inconnu message_type peut être ignoré par votre serveur.

Pour chaque message d'appareil que votre serveur d'applications 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 d'ACK pour un message, FCM le renvoie la prochaine fois qu'une nouvelle connexion XMPP est établie, à moins que le message n'expire en premier.

Le FCM envoie également un ACK ou un 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'applications vers 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 "ack" régulier. Mais lorsque la réponse contient une erreur, le message peut prendre 2 formes différentes, décrites ci-dessous.

Message d'accusé de réception

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.

Vous trouverez ci-dessous quelques exemples.

Mauvaise inscription :

<message>
  <gcm xmlns="google:mobile:data">
  {
    "message_type":"nack",
    "message_id":"msgId1",
    "from":"SomeInvalidRegistrationToken",
    "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épassement du taux de messages de l'appareil :

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

Voir 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 réessayé. 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 example:

<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

Périodiquement, 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 drainage et sera bientôt fermée. « Drainer » 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'établissement 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 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'applications doit arrêter d'envoyer de nouveaux messages et attendre que FCM accuse réception de certains des messages en attente existants, comme illustré dans la figure 1 :

Figure 1. Flux de messages/accusés de réception.

Inversement, pour éviter de surcharger le serveur d'applications, FCM arrête d'envoyer s'il y a trop de messages non acquittés. Par conséquent, le serveur d'applications doit « ACK » des messages en amont, reçus de l'application cliente 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'applications doit continuer à envoyer des accusés de réception pour les messages reçus de FCM afin d'éviter de bloquer la livraison 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'applications doit attendre que FCM renvoie le message en amont avant de l'accuser à 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.