Ce document fournit une référence pour la syntaxe XMPP utilisée pour transmettre des messages entre votre serveur d'applications, vos applications clientes et Firebase Cloud Messaging (FCM). Votre serveur d'applications 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 appartiennent à ces catégories :
- Syntaxe des messages en aval
- Codes de réponse d'erreur de message en aval
- Syntaxe des messages en amont
- Messages de contrôle FCM
Syntaxe des messages en aval
Cette section donne la syntaxe d'envoi de messages en aval.
Messages XMPP en aval (JSON)
Le tableau suivant répertorie les cibles, les options et la charge utile des messages XMPP JSON.
Paramètre | Usage | 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 | |
condition | Facultatif, chaîne | Ce paramètre spécifie une expression logique de conditions qui détermine la cible du message. Condition prise en charge : sujet, formaté comme « votreTopic » dans les sujets ». Cette valeur n'est pas sensible à la casse. Opérateurs pris en charge : | |
Possibilités | |||
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 Il n'y a aucune garantie quant à l'ordre dans lequel les messages sont envoyés. Remarque : Un maximum de 4 clés de réduction différentes est autorisé à un moment donné. Cela signifie que FCM peut stocker simultanément 4 messages différents par application client. Si vous dépassez ce nombre, il n'y a aucune garantie quant aux 4 clés de réduction que FCM conservera. | |
priority | Facultatif, chaîne | Définit la priorité du message. Les valeurs valides sont « normal » et « élevé ». Sur les plateformes Apple, celles-ci correspondent aux priorités APN 5 et 10. Par défaut, les messages de notification sont envoyés avec une priorité élevée et les messages de données avec une priorité normale. La priorité normale optimise la consommation de la batterie de l'application client et doit être utilisée sauf si une livraison immédiate est requise. Pour les messages avec une priorité normale, l'application peut recevoir le message avec un délai indéterminé. 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 plateformes Apple, utilisez ce champ pour représenter | |
mutable_content | Facultatif, booléen JSON | Sur les plates-formes Apple, utilisez ce champ pour représenter | |
time_to_live | Facultatif, numéro | Ce paramètre spécifie combien de temps (en secondes) le message doit être conservé dans le stockage FCM si l'appareil est hors ligne. La durée maximale de vie prise en charge est de 4 semaines et la valeur par défaut est de 4 semaines. Pour plus d'informations, voir Définir la durée de vie d'un message . | |
dry_run | Facultatif, booléen | Ce paramètre, lorsqu'il est défini sur La valeur par défaut est | |
Charge utile | |||
data | Facultatif, objet | Ce paramètre spécifie les paires clé-valeur de la charge utile du message. Par exemple, avec Sur les plateformes Apple, si le message est délivré par des APN, il représente les champs de données personnalisés. S'il est fourni par FCM, il est représenté sous forme de dictionnaire de valeurs clés dans Sur Android, cela se traduit par une intention supplémentaire nommée 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 (tels que Les valeurs dans les types de chaîne sont recommandées. Vous devez convertir les valeurs des objets ou d'autres types de données autres que des chaînes (par exemple, des entiers ou des booléens) en chaîne. | |
notification | Facultatif, objet | Ce paramètre spécifie les paires clé-valeur prédéfinies et visibles par l'utilisateur de la charge utile de notification. Voir Prise en charge de la charge utile de notification pour plus de détails. Pour plus d'informations sur les options de message de notification et de message de données, voir 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 vers un appareil Apple, le message est envoyé via APNs , sinon il est envoyé via FCM. |
Prise en charge de 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 plateformes Apple et Android.
Paramètre | Usage | Description |
---|---|---|
title | Facultatif, chaîne | Le titre de la notification. Ce champ n'est pas visible sur les téléphones et les tablettes. |
body | Facultatif, chaîne | Le corps du texte de la notification. |
sound | Facultatif, chaîne | Le son à jouer 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 |
badge | Facultatif, chaîne | La valeur du badge sur l'icône de l'application de l'écran d'accueil. S’il n’est pas précisé, le badge n’est pas modifié. S'il est défini sur |
click_action | Facultatif, chaîne | L'action associée à un utilisateur clique sur la notification. Correspond à |
subtitle | Facultatif, chaîne | Le 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 corps du texte selon la localisation actuelle de l'utilisateur. Correspond à Voir Référence de clé de charge utile et Localisation du contenu de vos notifications à distance pour plus d'informations. |
body_loc_args | Facultatif, tableau JSON sous forme de chaîne | Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans Correspond aux Voir Référence de clé de charge utile et Localisation du contenu de vos notifications à distance pour plus d'informations. |
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 dans la localisation actuelle de l'utilisateur. Correspond à Voir Référence de clé de charge utile et Localisation du contenu de vos notifications à distance pour plus d'informations. |
title_loc_args | Facultatif, tableau JSON sous forme de chaîne | Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans Correspond aux Voir Référence de clé de charge utile et Localisation du contenu de vos notifications à distance pour plus d'informations. |
Paramètre | Usage | Description |
---|---|---|
title | Facultatif, chaîne | Le titre de la notification. |
body | Facultatif, chaîne | Le corps du texte de la notification. |
android_channel_id | Facultatif, chaîne | L' identifiant du canal de notification (nouveau dans Android O). L'application doit créer une chaîne avec cet ID de chaîne avant de recevoir toute notification avec cet ID de chaîne. Si vous n'envoyez pas cet ID de canal dans la demande, ou si l'ID de canal fourni n'a pas encore été créé par l'application, FCM utilise l'ID de canal spécifié dans le manifeste de l'application. |
icon | Facultatif, chaîne | L'icône de la notification. Définit l'icône de notification sur |
sound | Facultatif, chaîne | Le son à jouer lorsque l'appareil reçoit la notification. Prend en charge |
tag | Facultatif, chaîne | Identifiant utilisé pour remplacer les notifications existantes dans le tiroir de notifications. Si non spécifié, chaque demande crée une nouvelle notification. Si cela est spécifié et qu'une notification avec la même balise est déjà affichée, la nouvelle notification remplace celle existante dans le tiroir de notification. |
color | Facultatif, chaîne | La couleur de l'icône de la notification, exprimée au format |
click_action | Facultatif, chaîne | L'action associée à un utilisateur clique sur la notification. Si spécifié, une activité avec un filtre d'intention 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 corps du texte selon la localisation actuelle de l'utilisateur. Voir Ressources de chaînes pour plus d'informations. |
body_loc_args | Facultatif, tableau JSON sous forme de chaîne | Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans Voir Formatage et style pour plus d’informations. |
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 dans la localisation actuelle de l'utilisateur. Voir Ressources de chaînes pour plus d'informations. |
title_loc_args | Facultatif, tableau JSON sous forme de chaîne | Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans Voir Formatage et style pour plus d’informations. |
Paramètre | Usage | Description |
---|---|---|
title | Facultatif, chaîne | Le titre de la notification. |
body | Facultatif, chaîne | Le corps du texte de la notification. |
icon | Facultatif, chaîne | L'URL à utiliser pour l'icône de la notification. |
click_action | Facultatif, chaîne | L'action associée à un utilisateur clique sur la notification. Pour toutes les valeurs d'URL, HTTPS est requis. |
Interpréter une réponse à un message XMPP en aval
Le tableau suivant répertorie les champs qui apparaissent dans une réponse à un message XMPP en aval.
Paramètre | Usage | Description |
---|---|---|
from | Obligatoire, chaîne | Ce paramètre précise qui a envoyé cette réponse. La valeur est le jeton d'enregistrement de l'application client. |
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 Si la valeur est définie sur |
error | Facultatif, chaîne | Ce paramètre spécifie une erreur liée au message en aval. Il est défini lorsque le message_type est nack . Voir le tableau 4 pour plus de détails. |
error_description | Facultatif, chaîne | Ce paramètre fournit des informations descriptives sur l'erreur. Il est défini lorsque le message_type est nack . |
Codes de réponse d'erreur de message en aval
Le tableau suivant répertorie les codes de réponse d'erreur pour les 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 le registration_id dans un message en texte brut, ou dans le champ to ou registration_ids en JSON). |
Enregistrement APN invalide | INVALID_JSON | Pour les enregistrements iOS, vérifiez que la demande d'enregistrement du client contient un jeton APNs et un ID d'application valides. |
Jeton d'enregistrement invalide | 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 client reçoit lors de son inscription auprès de FCM. Ne tronquez pas et n’ajoutez pas de caractères supplémentaires. |
Appareil non enregistré | DEVICE_UNREGISTERED | Un jeton d'enregistrement existant peut cesser d'être valide dans un certain nombre de scénarios, notamment :
|
Expéditeur incompatible | SENDER_ID_MISMATCH | Un jeton d'enregistrement est lié à un certain groupe d'expéditeurs. Lorsqu'une application client s'inscrit à FCM, elle doit spécifier quels expéditeurs sont autorisés à envoyer des messages. Vous devez utiliser l'un de ces identifiants d'expéditeur lors de l'envoi de messages à l'application client. Si vous passez à un autre expéditeur, les jetons d'enregistrement existants ne fonctionneront pas. |
JSON invalide | INVALID_JSON | Vérifiez que le message JSON est correctement formaté et contient des champs valides (par exemple, en vous assurant que le bon type de données est transmis). |
Message trop gros | INVALID_JSON | Vérifiez que la taille totale des données utiles 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 vers des sujets. Cela inclut à la fois les clés et les valeurs. |
Clé de données invalide | INVALID_JSON | Vérifiez que les données de charge utile ne contiennent pas de clé (telle que from , gcm ou toute valeur préfixée par 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, auquel cas la valeur de la charge utile est remplacée par la valeur FCM. |
Durée de vie invalide | 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. Voir le tableau 6 pour plus de détails. |
Temps mort | SERVICE_UNAVAILABLE | Le serveur n'a pas pu traiter la demande à temps. Réessayez la même demande, mais vous devez :
Remarque : Les expéditeurs qui posent problème risquent d'être mis sur liste noire. |
Erreur interne du serveur | INTERNAL_SERVER_ | Le serveur a rencontré une erreur lors de la tentative de traitement de la demande. Vous pouvez réessayer la même demande en suivant les exigences répertoriées dans « Délai d'attente » (voir la ligne ci-dessus). |
Débit de messages du périphérique dépassé | DEVICE_MESSAGE_RATE | Le débit de messages vers un appareil particulier est trop élevé. Réduisez le nombre de messages envoyés à cet appareil et ne réessayez pas immédiatement de les envoyer à cet appareil. |
Sujets Débit de messages dépassé | TOPICS_MESSAGE_RATE | Le taux de messages aux abonnés sur un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et ne réessayez pas immédiatement de les envoyer. |
Vidange des connexions | CONNECTION_DRAINING | Le message n'a pas pu être traité car la connexion est en train de s'épuiser. Cela se produit car, périodiquement, FCM doit fermer une connexion pour effectuer l'équilibrage de charge. Réessayez le message via une autre connexion XMPP. |
Identifiants APN invalides | INVALID_APNS_CREDENTIAL | Un message destiné à un appareil iOS n'a pas pu être envoyé car la clé d'authentification APN requise n'a pas été téléchargée ou a expiré. Vérifiez la validité de vos références de développement et de production. |
Authentification échouée | AUTHENTICATION_FAILED | Échec de l'authentification auprès des services push externes. Vérifiez si vous utilisez les bons certificats Web Push. |
Syntaxe des messages en amont
Un message en amont est un message que l'application client envoie au serveur d'application. Actuellement, seul XMPP prend en charge la messagerie en amont. Consultez la documentation de votre plateforme pour plus d’informations sur l’envoi de messages à partir d’applications clientes.
Interprétation d'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 demandes de messages en amont des applications clientes.
Paramètre | Usage | Description |
---|---|---|
from | Obligatoire, chaîne | Ce paramètre précise qui a envoyé le message. La valeur est le jeton d'enregistrement de l'application client. |
category | Obligatoire, chaîne | Ce paramètre spécifie le nom du package d'application de l'application client qui a envoyé le message. |
message_id | Obligatoire, chaîne | Ce paramètre spécifie l'ID unique du message. |
data | Facultatif, chaîne | Ce paramètre spécifie les paires clé-valeur de la charge utile du message. |
Envoi d'un message ACK
Le tableau suivant décrit la réponse ACK que le serveur d'applications est censé envoyer à FCM en réponse à un message en amont reçu par le serveur d'applications.
Paramètre | Usage | 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 à quel message 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'applications 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é de FCM à un serveur d'applications. Voici les principaux types de messages que FCM envoie au serveur d'applications :
- Contrôle : ces messages générés par CCS indiquent qu'une action est requise de la part du serveur d'applications.
Le tableau suivant décrit les champs inclus dans les messages que CCS envoie à un serveur d'applications.
Paramètre | Usage | Description |
---|---|---|
Champ commun | ||
message_type | Obligatoire, chaîne | Ce paramètre précise le type du message : contrôle. Lorsqu'il est défini sur |
control_type | Facultatif, chaîne | Ce paramètre spécifie le type de message de contrôle envoyé depuis FCM. Actuellement, seul |