Catch up on everthing we announced at this year's Firebase Summit. Learn more

Votre environnement serveur et FCM

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

  • Le back - end de la FCM fourni par Google.
  • Votre serveur d'applications ou tout autre environnement de serveur sécurisé où vos pistes logiques de serveur, tels que fonctions Cloud pour Firebase ou d' autres environnements de cloud computing 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 traiter les demandes et de renvoyer les utiliser back-off exponentielle.
  • 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 aurez besoin de décider d'un moyen d'interagir avec les serveurs FCM: soit en utilisant le Firebase admin SDK ou 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 Firebase Administrateur SDK, qui a un support pour Node , Java , Python , C # et Go .
  • La FCM HTTP v1 API , qui est le plus à jour des options de protocole, avec plus d' autorisation sécurisée et flexible des capacités de messagerie multi-plateforme (le Firebase Administrateur SDK est basé sur ce protocole et fournit tous ses avantages intrinsèques).
  • L'héritage HTTP protocole.
  • Le XMPP protocole du serveur. 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 Firebase Administrateur SDK, voir Ajouter le Firebase Administrateur SDK à votre serveur . Si vous avez déjà un projet Firebase, commencez par Ajouter le SDK . Puis, une fois que le Firebase Administrateur SDK est installé, vous pouvez commencer à la logique d'écriture pour les demandes de construction 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 le corps, voir Construire App serveur Envoyez vos demandes

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 nécessaire. Cet ID identifie de manière unique le message dans une connexion XMPP. L'ACK ou NACK de la FCM utilise le message_id pour identifier un message envoyé à partir de serveurs d'applications à la FCM. Par conséquent, il est important que cette message_id soit non seulement unique (par ID de l' expéditeur ), mais toujours présent.
  • XMPP utilise la clé du serveur pour autoriser une connexion persistante à FCM. Voir Autorisez Envoyez vos demandes pour plus d' informations.

En plus des messages réguliers de la FCM, les messages de commande sont envoyés, indiqué par le message_type champ 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 le protocole de référence pour une liste de tous les paramètres du 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 régulier XMPP dans lequel le message_type message d'état 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 le serveur de référence pour obtenir une liste complète des codes d'erreur NACK. Sauf indication contraire, un message NACKed ne doit pas être réessayé. Unexpected codes d'erreur NACK doivent être traités comme 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

Périodiquement, FCM doit fermer une connexion pour effectuer l'équilibrage de charge. Avant de fermer la connexion, la FCM envoie un CONNECTION_DRAINING message indiquant que la connexion est drainée et sera bientôt fermé. « 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 CONNECTION_DRAINING message, vous devez commencer immédiatement envoyer un message à une autre connexion de la FCM, l' ouverture d' 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 CONNECTION_DRAINING un message 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 :

Diagramme détaillé du flux de contrôle entre FCM et le serveur d'applications

Figure 1. Message / flux ack.

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.