Protocole XMPP Firebase Cloud Messaging

Ce document fournit une référence de la syntaxe XMPP utilisée pour transmettre des messages entre votre serveur d'applications, les applications clientes et Firebase Cloud Messaging (FCM). Votre serveur d'application doit se connecter à ces points de terminaison:

// Production
fcm-xmpp.googleapis.com:5235

// Testing
fcm-xmpp.googleapis.com:5236

Les paramètres et options disponibles se répartissent en plusieurs catégories:

Syntaxe des messages en aval

Cette section indique la syntaxe à utiliser pour envoyer des messages en aval.

Messages XMPP en aval (JSON)

Le tableau suivant indique les cibles, les options et la charge utile des messages JSON XMPP.

Tableau 1 : Cibles, options et charge utile pour les messages XMPP en aval (JSON).

Paramètre Utilisation Description
Cible
to Facultatif, chaîne

Ce paramètre spécifie le destinataire d'un message.

La valeur peut être le jeton d'enregistrement d'un appareil, la clé de notification d'un groupe d'appareils ou un seul sujet (préfixé par /topics/). Pour envoyer des messages à plusieurs sujets, utilisez le paramètre condition.

condition Facultatif, chaîne

Ce paramètre spécifie une expression logique de conditions qui détermine la cible du message.

Condition acceptée : "Topic", au format "'yourTopic' in topics". Cette valeur n'est pas sensible à la casse.

Opérateurs acceptés: &&, ||. Deux opérateurs maximum par message de sujet sont acceptés.
Options
message_id Obligatoire, chaîne

Ce paramètre identifie de manière unique un message dans une connexion XMPP.
collapse_key Facultatif, chaîne

Ce paramètre identifie un groupe de messages (par exemple, avec collapse_key: "Updates Available") qui peut être réduit afin que seul le dernier message soit envoyé lorsque la diffusion est reprise. Cela permet d'éviter d'envoyer trop de messages identiques lorsque l'appareil revient en ligne ou sort de la mise en veille.

L'ordre dans lequel les messages sont envoyés n'est pas garanti.

Remarque: Vous ne pouvez utiliser qu'un maximum de quatre clés de réduction différentes à la fois. Cela signifie que FCM peut stocker simultanément quatre messages différents par application cliente. Si vous dépassez ce nombre, il n'est pas garanti que FCM conserve les quatre clés de réduction.

priority Facultatif, chaîne

Définit la priorité du message. Les valeurs valides sont "normal" (normal) et "high" (élevé). Sur les plates-formes Apple, elles correspondent aux priorités 5 et 10 des notifications APN.

Par défaut, les messages de notification sont envoyés avec une priorité élevée, et les messages de données sont envoyés avec une priorité normale. La priorité normale optimise la consommation de la batterie de l'application cliente et doit être utilisée, sauf si une diffusion immédiate est requise. Pour les messages de priorité normale, l'application peut recevoir le message avec un délai non spécifié.

Lorsqu'un message est envoyé avec une priorité élevée, il est envoyé immédiatement et l'application peut afficher une notification.

content_available Facultatif, booléen

Sur les plates-formes Apple, utilisez ce champ pour représenter content-available dans la charge utile des APN. Lorsqu'une notification ou un message est envoyé et que cette valeur est définie sur true, une application cliente inactive est activée et le message est envoyé via les APN en tant que notification silencieuse et non via FCM. Notez que la diffusion des notifications silencieuses dans les APN n'est pas garantie et peut dépendre de facteurs tels que l'activation du mode économie d'énergie par l'utilisateur, la fermeture forcée de l'application, etc. Sur Android, les messages de données réveillent l'application par défaut. Dans Chrome, cette fonctionnalité n'est pas disponible pour le moment.
mutable_content Facultatif, valeur booléenne JSON

Sur les plates-formes Apple, utilisez ce champ pour représenter mutable-content dans la charge utile des APN. Lorsqu'une notification est envoyée et qu'elle est définie sur true, le contenu de la notification peut être modifié avant son affichage à l'aide d'une extension d'application Notification Service. Ce paramètre sera ignoré pour Android et le Web.

time_to_live Facultatif, nombre

Ce paramètre spécifie la durée (en secondes) pendant laquelle le message doit être conservé dans l'espace de stockage FCM si l'appareil est hors connexion. La valeur TTL maximale acceptée est de quatre semaines, et la valeur par défaut est de quatre semaines. Pour en savoir plus, consultez Définir la durée de vie d'un message.

dry_run Facultatif, booléen

Lorsque ce paramètre est défini sur true, les développeurs peuvent tester une requête sans envoyer de message.

La valeur par défaut est false.
Charge utile
data Facultatif, objet

Ce paramètre spécifie les paires clé-valeur de la charge utile du message.

Par exemple, avec data:{"score":"3x1"}:

Sur les plates-formes Apple, si le message est envoyé par les APN, il représente les champs de données personnalisés. S'il est fourni par FCM, il est représenté sous la forme d'un dictionnaire de clés-valeurs dans AppDelegate application:didReceiveRemoteNotification:.

Sur Android, cela génère un intent supplémentaire nommé score avec la valeur de chaîne 3x1.

La clé ne doit pas être un mot réservé ("from", "message_type" ou tout mot commençant par "google" ou "gcm"). N'utilisez aucun des mots définis dans ce tableau (par exemple, collapse_key).

Nous vous recommandons d'utiliser des valeurs de type chaîne. Vous devez convertir les valeurs d'objets ou d'autres types de données autres que des chaînes (par exemple, des entiers ou des valeurs booléennes) en chaînes.
notification Facultatif, objet Ce paramètre spécifie les paires clé-valeur prédéfinies visibles par l'utilisateur de la charge utile de notification. Pour en savoir plus, consultez la section Compatibilité avec la charge utile de notification. Pour en savoir plus sur les options de message de notification et de message de données, consultez la section Types de messages. Si une charge utile de notification est fournie ou si l'option content_available est définie sur true pour un message envoyé à un appareil Apple, le message est envoyé via les APN, sinon il est envoyé via FCM.

Compatibilité avec la charge utile de notification

Les tableaux suivants répertorient les clés prédéfinies disponibles pour créer des messages de notification pour les plates-formes Apple et Android.

Tableau 2a. Apple : clés pour les messages de notification

Paramètre Utilisation Description
title Facultatif, chaîne

Titre de la notification.

Ce champ n'est pas visible sur les téléphones et les tablettes.

body Facultatif, chaîne

Corps du texte de la notification.

sound Facultatif, chaîne

Son à lire lorsque l'appareil reçoit la notification.

Chaîne spécifiant les fichiers audio dans le bundle principal de l'application cliente ou dans le dossier Library/Sounds du conteneur de données de l'application. Pour en savoir plus, consultez la bibliothèque des développeurs iOS.

badge Facultatif, chaîne

Valeur du badge sur l'icône de l'application de l'écran d'accueil.

Si cette option n'est pas spécifiée, le badge ne change pas.

Si la valeur est 0, le badge est supprimé.

click_action Facultatif, chaîne

Action associée à un clic de l'utilisateur sur la notification.

Correspond à category dans la charge utile des APN.

subtitle Facultatif, chaîne

Sous-titre de la notification.

body_loc_key Facultatif, chaîne

Clé de la chaîne de corps dans les ressources de chaîne de l'application à utiliser pour localiser le texte du corps en fonction de la localisation actuelle de l'utilisateur.

Correspond à loc-key dans la charge utile des APN.

Pour en savoir plus, consultez les sections Documentation de référence sur les clés de charge utile et Localiser le contenu de vos notifications à distance.

body_loc_args Facultatif : tableau JSON en tant que chaîne

Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans body_loc_key pour localiser le texte du corps en fonction de la localisation actuelle de l'utilisateur.

Correspond à loc-args dans la charge utile des APN.

Pour en savoir plus, consultez les sections Documentation de référence sur les clés de charge utile et Localiser le contenu de vos notifications à distance.

title_loc_key Facultatif, chaîne

Clé de la chaîne de titre dans les ressources de chaîne de l'application à utiliser pour localiser le texte du titre en fonction de la localisation actuelle de l'utilisateur.

Correspond à title-loc-key dans la charge utile des APN.

Pour en savoir plus, consultez les sections Documentation de référence sur les clés de charge utile et Localiser le contenu de vos notifications à distance.

title_loc_args Facultatif : tableau JSON en tant que chaîne

Valeurs de chaîne variables à utiliser à la place des spécificateurs de format dans title_loc_key pour localiser le texte du titre en fonction de la localisation actuelle de l'utilisateur.

Correspond à title-loc-args dans la charge utile des APN.

Pour en savoir plus, consultez les sections Documentation de référence sur les clés de charge utile et Localiser le contenu de vos notifications à distance.

Tableau 2b. Android : clés pour les messages de notification

Paramètre Utilisation Description
title Facultatif, chaîne

Titre de la notification.

body Facultatif, chaîne

Corps du texte de la notification.

android_channel_id Facultatif, chaîne

ID de canal de la notification (nouveauté d'Android O)

L'application doit créer un canal avec cet ID de canal avant de recevoir une notification avec cet ID de canal.

Si vous n'envoyez pas cet ID de chaîne dans la requête ou si l'ID de chaîne fourni n'a pas encore été créé par l'application, FCM utilise l'ID de chaîne spécifié dans le fichier manifeste de l'application.

icon Facultatif, chaîne

Icône de la notification.

Définit l'icône de notification sur myicon pour la ressource drawable myicon. Si vous n'envoyez pas cette clé dans la requête, FCM affiche l'icône du lanceur spécifiée dans le fichier manifeste de votre application.

sound Facultatif, chaîne

Son à lire lorsque l'appareil reçoit la notification.

Compatible avec "default" ou le nom de fichier d'une ressource audio groupée dans l'application. Les fichiers audio doivent se trouver dans /res/raw/.

tag Facultatif, chaîne

Identifiant utilisé pour remplacer les notifications existantes dans le panneau des notifications.

Si elle n'est pas spécifiée, chaque requête crée une notification.

Si vous spécifiez cette valeur et qu'une notification avec la même balise est déjà affichée, la nouvelle notification remplace l'ancienne dans le panneau des notifications.

color Facultatif, chaîne

Couleur de l'icône de la notification, exprimée au format #rrggbb.

click_action Facultatif, chaîne

Action associée à un clic de l'utilisateur sur la notification.

Si spécifié, une activité avec un filtre d'intent correspondant est lancée lorsqu'un utilisateur clique sur la notification.

body_loc_key Facultatif, chaîne

Clé de la chaîne de corps dans les ressources de chaîne de l'application à utiliser pour localiser le texte du corps en fonction de la localisation actuelle de l'utilisateur.

Pour en savoir plus, consultez la section Ressources de chaîne.

body_loc_args Facultatif : tableau JSON en tant que chaîne

Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans body_loc_key pour localiser le texte du corps en fonction de la localisation actuelle de l'utilisateur.

Pour en savoir plus, consultez la section Mise en forme et style.

title_loc_key Facultatif, chaîne

Clé de la chaîne de titre dans les ressources de chaîne de l'application à utiliser pour localiser le texte du titre en fonction de la localisation actuelle de l'utilisateur.

Pour en savoir plus, consultez la section Ressources de chaîne.

title_loc_args Facultatif : tableau JSON en tant que chaîne

Valeurs de chaîne variables à utiliser à la place des spécificateurs de format dans title_loc_key pour localiser le texte du titre en fonction de la localisation actuelle de l'utilisateur.

Pour en savoir plus, consultez la section Mise en forme et style.

Tableau 2c. Web (JavaScript) : clés pour les messages de notification

Paramètre Utilisation Description
title Facultatif, chaîne

Titre de la notification.

body Facultatif, chaîne

Corps du texte de la notification.

icon Facultatif, chaîne

URL à utiliser pour l'icône de la notification.

click_action Facultatif, chaîne

Action associée à un clic de l'utilisateur sur la notification.

Pour toutes les valeurs d'URL, HTTPS est obligatoire.

Interpréter une réponse de message XMPP en aval

Le tableau suivant liste les champs qui apparaissent dans une réponse de message XMPP en aval.

Tableau 3 : Corps de réponse XMPP du message en aval.

Paramètre Utilisation Description
from Obligatoire, chaîne

Ce paramètre spécifie qui a envoyé cette réponse.

La valeur correspond au jeton d'enregistrement de l'application cliente.
message_id Obligatoire, chaîne Ce paramètre identifie de manière unique un message dans une connexion XMPP. La valeur est une chaîne qui identifie de manière unique le message associé.
message_type Obligatoire, chaîne

Ce paramètre spécifie un message ack ou nack de FCM au serveur d'application.

Si la valeur est définie sur nack, le serveur d'application doit examiner error et error_description pour obtenir des informations sur l'échec.

error Facultatif, chaîne Ce paramètre spécifie une erreur liée au message en aval. Il est défini lorsque message_type est nack. Pour en savoir plus, consultez le tableau 4.
error_description Facultatif, chaîne Ce paramètre fournit des informations descriptives sur l'erreur. Il est défini lorsque message_type est nack.

Codes de réponse d'erreur des messages en aval

Le tableau suivant répertorie les codes de réponse d'erreur pour les messages en aval.

Tableau 4 : Codes de réponse d'erreur des messages en aval.

Erreur Code XMPP Action recommandée
Jeton d'enregistrement manquant INVALID_JSON Vérifiez que la requête contient un jeton d'enregistrement (dans registration_id dans un message en texte brut, ou dans le champ to ou registration_ids au format JSON).
Enregistrement APNs non valide INVALID_JSON Pour les enregistrements iOS, vérifiez que la requête d'enregistrement du client contient un jeton APN et un ID d'application valides.
Jeton d'enregistrement non valide BAD_REGISTRATION Vérifiez le format du jeton d'enregistrement que vous transmettez au serveur. Assurez-vous qu'il correspond au jeton d'enregistrement que l'application cliente reçoit lors de son enregistrement auprès de FCM. N'écourtez pas ni n'ajoutez pas de caractères supplémentaires.
Appareil non enregistré DEVICE_UNREGISTERED Un jeton d'enregistrement existant peut cesser d'être valide dans plusieurs cas, par exemple:
  • Si l'application cliente se désinscrit auprès de FCM.
  • Si l'application cliente est automatiquement désenregistrée, ce qui peut se produire si l'utilisateur désinstalle l'application. Par exemple, sur iOS, si APNs a signalé le jeton APNs comme non valide.
  • Si le jeton d'enregistrement expire (par exemple, Google peut décider d'actualiser les jetons d'enregistrement ou le jeton APN a expiré pour les appareils).
  • Si l'application cliente est mise à jour, mais que la nouvelle version n'est pas configurée pour recevoir des messages.
Dans tous ces cas, supprimez ce jeton d'enregistrement du serveur de l'application et cessez de l'utiliser pour envoyer des messages.
Expéditeur non concordant SENDER_ID_MISMATCH Un jeton d'enregistrement est associé à un certain groupe d'expéditeurs. Lorsqu'une application cliente s'inscrit pour FCM, elle doit spécifier les expéditeurs autorisés à envoyer des messages. Vous devez utiliser l'un de ces ID d'expéditeur lorsque vous envoyez des messages à l'application cliente. Si vous passez à un autre expéditeur, les jetons d'enregistrement existants ne fonctionneront pas.
JSON non valide INVALID_JSON Vérifiez que le message JSON est correctement formaté et qu'il contient des champs valides (par exemple, assurez-vous que le bon type de données est transmis).
Message trop volumineux INVALID_JSON Vérifiez que la taille totale des données de charge utile incluses dans un message ne dépasse pas les limites FCM: 4 096 octets pour la plupart des messages ou 2 048 octets dans le cas des messages destinés à des sujets. Cela inclut à la fois les clés et les valeurs.
Clé de données non valide INVALID_JSON Vérifiez que les données de la charge utile ne contiennent pas de clé (telle que from, gcm ou toute valeur précédée du préfixe google) utilisée en interne par FCM. Notez que certains mots (tels que collapse_key) sont également utilisés par FCM, mais sont autorisés dans la charge utile. Dans ce cas, la valeur de la charge utile est remplacée par la valeur FCM.
Valeur TTL non valide INVALID_JSON Vérifiez que la valeur utilisée dans time_to_live est un entier représentant une durée en secondes comprise entre 0 et 2 419 200 (4 semaines).
Mauvais message ACK BAD_ACK Vérifiez que le message ack est correctement formaté avant de réessayer. Pour en savoir plus, consultez le tableau 6.
Délai avant expiration SERVICE_UNAVAILABLE

Le serveur n'a pas pu traiter la requête à temps. Réessayez la même requête, mais vous devez:

  • Implémentez un intervalle exponentiel entre les tentatives dans votre mécanisme de nouvelle tentative. (par exemple, si vous avez attendu une seconde avant la première nouvelle tentative, attendez au moins deux secondes avant la suivante, puis quatre secondes, et ainsi de suite). Si vous envoyez plusieurs messages, retardez chacun d'eux indépendamment d'une valeur aléatoire supplémentaire pour éviter d'émettre une nouvelle requête pour tous les messages en même temps.
  • Le délai de nouvelle tentative initial doit être défini sur une seconde.

Remarque: Les expéditeurs qui posent problème risquent d'être ajoutés à la liste de blocage.
Erreur interne du serveur INTERNAL_SERVER_
ERROR		 Le serveur a rencontré une erreur lors du traitement de la requête. Vous pouvez réessayer la même requête en suivant les conditions requises indiquées sous "Délai avant expiration" (voir ligne ci-dessus).
Fréquence de messages pour les appareils dépassée DEVICE_MESSAGE_RATE
_EXCEEDED		 Le nombre de messages envoyés à un appareil spécifique est trop élevé. Réduisez le nombre de messages envoyés à cet appareil et n'essayez pas immédiatement de renvoyer un message à cet appareil.
Nombre maximal de messages par sujet dépassé TOPICS_MESSAGE_RATE
_EXCEEDED		 Le nombre de messages envoyés aux abonnés d'un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et ne réessayez pas immédiatement l'envoi.
Drainage de connexion CONNECTION_DRAINING Le message n'a pas pu être traité, car la connexion est en cours d'épuisement. Cela se produit parce que, de manière périodique, FCM doit fermer une connexion pour effectuer l'équilibrage de charge. Réessayez d'envoyer le message via une autre connexion XMPP.
Identifiants APNs incorrects INVALID_APNS_CREDENTIAL Impossible d'envoyer un message ciblé sur un appareil iOS, car la clé d'authentification APN requise n'a pas été importée ou a expiré. Vérifiez la validité de vos identifiants de développement et de production.
Échec de l'authentification AUTHENTICATION_FAILED Échec de l'authentification auprès des services push externes. Vérifiez que vous utilisez les bons certificats Web Push.

Syntaxe des messages en amont

Un message en amont est un message que l'application cliente envoie au serveur d'application. Actuellement, seul XMPP est compatible avec la messagerie en amont. Pour en savoir plus sur l'envoi de messages depuis des applications clientes, consultez la documentation de votre plate-forme.

Interpréter un message XMPP en amont

Le tableau suivant décrit les champs de la strophe XMPP générée par FCM en réponse aux requêtes de messages en amont des applications clientes.

Tableau 5 : Messages XMPP en amont.

Paramètre Utilisation Description
from Obligatoire, chaîne

Ce paramètre indique qui a envoyé le message.

La valeur correspond au jeton d'enregistrement de l'application cliente.
category Obligatoire, chaîne Ce paramètre spécifie le nom du package de l'application cliente qui a envoyé le message.
message_id Obligatoire, chaîne Ce paramètre spécifie l'identifiant unique du message.
data Facultatif, chaîne Ce paramètre spécifie les paires clé-valeur de la charge utile du message.

Envoyer un message ACK

Le tableau suivant décrit la réponse ACK que le serveur d'application doit envoyer à FCM en réponse à un message en amont que le serveur d'application a reçu.

Tableau 6 : Réponse du message XMPP en amont.

Paramètre Utilisation Description
to Obligatoire, chaîne

Ce paramètre spécifie le destinataire d'un message de réponse.

La valeur doit être un jeton d'enregistrement de l'application cliente qui a envoyé le message en amont.
message_id Obligatoire, chaîne Ce paramètre spécifie le message auquel la réponse est destinée. La valeur doit être la valeur message_id du message en amont correspondant.
message_type Obligatoire, chaîne Ce paramètre spécifie un message ack d'un serveur d'application vers CCS. Pour les messages en amont, il doit toujours être défini sur ack.

Messages du serveur FCM (XMPP)

Il s'agit d'un message envoyé depuis FCM à un serveur d'application. Voici les principaux types de messages que FCM envoie au serveur d'application:

  • Contrôle:ces messages générés par le CCS indiquent qu'une action est requise du serveur d'application.

Le tableau suivant décrit les champs inclus dans les messages que CCS envoie à un serveur d'application.

Tableau 7 : Messages de contrôle FCM (XMPP)

Paramètre Utilisation Description
Champ commun
message_type Obligatoire, chaîne

Ce paramètre spécifie le type de message: commande.

Lorsqu'il est défini sur control, le message inclut control_type pour indiquer le type de message de contrôle.
control_type Facultatif, chaîne

Ce paramètre spécifie le type de message de contrôle envoyé à partir de FCM.

Pour le moment, seul le type CONNECTION_DRAINING est compatible. FCM envoie ce message de contrôle avant de fermer une connexion pour effectuer l'équilibrage de charge. Lorsque la connexion est épuisée, aucun message ne peut plus être envoyé à la connexion, mais les messages existants dans le pipeline continuent d'être traités.