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 dans lequel la logique de votre serveur s'exécute, comme Cloud Functions pour 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 message 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 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 identifiants d'autorisation du serveur et les jetons d'enregistrement du client.
• Pour le protocole XMPP (s'il est utilisé), le serveur doit pouvoir 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 , soit les 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). Étant donné que les nouvelles fonctionnalités sont généralement ajoutées à l'API HTTP v1 uniquement, nous vous recommandons d'utiliser cette API dans la plupart des cas d'utilisation.
• L' ancien protocole HTTP . Il est fortement recommandé aux nouveaux projets d'adopter l'API HTTP FCM v1 au lieu de l'ancien protocole.
• L' ancien protocole de serveur XMPP . Il est fortement recommandé aux nouveaux projets d'adopter l'API HTTP FCM v1 au lieu de l'ancien protocole.

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 d'administration Firebase, 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.
• Abonnez-vous et désabonnez-vous des appareils à et à partir de 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 aux groupes d'appareils.

Pour configurer le SDK Firebase Admin, consultez Ajouter le SDK Firebase Admin à votre serveur . Si vous avez déjà un projet Firebase, commencez par Ajouter le SDK . Assurez-vous également d'activer l'API Cloud Messagin dans la page des paramètres de Cloud Messaging pour votre projet. Ensuite, une fois le SDK Firebase Admin installé, vous pouvez commencer à écrire une logique pour créer des requêtes d'envoi .

Le SDK Firebase Admin fournit une API permettant d'abonner et de désabonner des appareils aux rubriques FCM. Ces opérations peuvent souscrire ou désinscrire jusqu'à 1000 jetons d'enregistrement d'appareil à la fois. Pour plus d'informations, voir Gérer les rubriques à partir du serveur .

Protocoles du serveur FCM

Actuellement, FCM fournit ces protocoles de serveur brut :

• API HTTP v1 du FCM
• Protocole HTTP hérité
• Protocole XMPP hérité

Votre serveur d'applications peut utiliser ces protocoles séparément ou en tandem. Parce qu'il s'agit de la solution la plus récente 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 sur les points suivants :

• Messages amont/aval
  • HTTP : en aval uniquement, du cloud à l'appareil.
  • XMPP : en amont et en aval (device-to-cloud, cloud-to-device).
• 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 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 encodés ACK et NACK 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.
• Envoi multidiffusion en aval vers 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 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, à ces exceptions près :

• Il n'y a pas de support 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é par les serveurs d'application à FCM. Par conséquent, il est important que ce message_id soit 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 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 formats ci-dessous). Tout message FCM avec un message_type inconnu peut être ignoré par votre serveur.

Pour chaque message de périphérique 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 d'accusé de réception pour un message, FCM le renvoie la prochaine fois qu'une nouvelle connexion XMPP est établie, à moins que le message n'expire en premier.

FCM envoie également un ACK ou NACK pour chaque message serveur-appareil. Si vous ne recevez ni l'un ni l'autre, 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 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 'ack' normal. 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 NAC

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":"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é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>

Voir la référence du serveur pour une liste complète des codes d'erreur NACK. Sauf indication contraire, un message NACK 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 exemple:

<message id="3" type="error" to="[e-mail]/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 train d'être vidée 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 ACKing) — FCM gère la fermeture d'une connexion 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'application doit cesser d'envoyer de nouveaux messages et attendre que FCM accuse réception de certains des messages en attente existants, comme illustré à la figure 1 :

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

Inversement, pour éviter de surcharger le serveur d'application, FCM arrête d'envoyer s'il y a trop de messages non acquittés. Par conséquent, le serveur d'application doit "ACK" envoyer les 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'application doit continuer à envoyer des ACK 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 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'accuser à nouveau. De même, tous les messages en attente pour lesquels un ACK/NACK n'a pas été reçu du FCM avant la fermeture de la connexion doivent être renvoyés.