Ce document fournit une référence sur la syntaxe XMPP utilisée pour transmettre 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 disponibles les options se répartissent dans les catégories suivantes:
- Syntaxe des messages en aval
- Codes de réponse d'erreur des messages en aval
- Syntaxe des messages en amont
- Messages de contrôle FCM
Syntaxe des messages en aval
Cette section décrit 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.
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, le jeton d'enregistrement
clé de notification ou un seul sujet (avec le préfixe
|
|
condition |
Facultatif, chaîne | Ce paramètre spécifie une expression logique de conditions qui détermine la cible du message. Condition acceptée: thème au format "'yourTopic" dans les sujets". Ce n'est pas sensible à la casse. Opérateurs compatibles: |
|
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
L'ordre dans lequel les messages seront 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 FCM peut stocker simultanément quatre types messages par application cliente. Si vous dépasse ce nombre, il n'est pas garanti que les quatre clés de réduction FCM que vous conserverez. |
|
priority |
Facultatif, chaîne | Définit la priorité du message. Les valeurs valides sont "normal" et "élevée". 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 l'expérience de la batterie et doivent être utilisés à moins qu'une livraison immédiate ne soit requise. Pour les messages dont la priorité est normale, l'application peut recevoir le message avec 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 |
|
mutable_content |
Facultatif, booléen JSON | Sur les plates-formes Apple, utilisez ce champ pour représenter
|
|
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. La valeur par défaut est de quatre semaines. Pour en savoir plus, consultez la section Définir la durée de vie d'un message. |
|
dry_run |
Facultatif, booléen | 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 plates-formes Apple, si le message est distribué via le service APNs, 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 Sur Android, cela génère un intent supplémentaire nommé 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.
( Les valeurs de type chaîne sont recommandées. Vous devez convertir les valeurs dans des objets ou dans d'autres types de données qui ne sont pas des chaînes (entiers ou booléens, par exemple) en chaîne. |
|
notification |
Facultatif, objet | Ce paramètre spécifie les paires clé-valeur prédéfinies, visibles par l'utilisateur, des propriétés
de notification. Pour en savoir plus, consultez "Prise en charge des charges utiles de notification". Pour en savoir plus,
sur les options relatives aux messages de notification et aux données, voir 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 opérateur Apple
appareil, le message est envoyé via le service APNs, sinon il est envoyé par
FCM
|
Compatibilité avec la charge utile de notification
Les tableaux suivants répertorient les rôles clés disponibles pour créer des messages de notification pour les plates-formes Apple et Android.
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 à émettre lorsque l'appareil reçoit la notification.
Chaîne spécifiant les fichiers audio dans le bundle principal de l'application cliente ou dans
Dossier |
badge |
Facultatif, chaîne |
Valeur du badge sur l'icône de l'application sur l'écran d'accueil. S'il n'est pas spécifié, le badge n'est pas modifié.
Si la valeur est |
click_action |
Facultatif, chaîne |
Action associée à un clic de l'utilisateur sur la notification.
Correspond à |
subtitle |
Facultatif, chaîne |
Sous-titre de la notification. |
body_loc_key |
Facultatif, chaîne |
Clé de la chaîne du 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 Documentation de référence sur la clé de charge utile et <ph type="x-smartling-placeholder"></ph> Localiser le contenu de vos notifications à distance des informations. |
body_loc_args |
Facultatif, tableau JSON sous forme de chaîne |
Valeurs de chaîne de variable à utiliser à la place des spécificateurs de format dans
Correspond à 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 selon la localisation actuelle de l'utilisateur.
Correspond à 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 de variable à utiliser à la place des spécificateurs de format dans
Correspond à 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. |
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 |
Le ID du canal de la notification (nouveau dans Android O). L'application doit créer une chaîne avec cet ID de chaîne avant que toute notification associée à cet ID ne soit reçues. Si vous n'envoyez pas cet ID de chaîne dans la demande 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 |
sound |
Facultatif, chaîne |
Son à émettre lorsque l'appareil reçoit la notification.
Accepte |
tag |
Facultatif, chaîne |
Identifiant utilisé pour remplacer les notifications existantes dans le panneau des notifications. S'il n'est pas spécifié, chaque requête crée une notification. Si spécifié et qu'une notification avec le même tag est déjà en cours affichée, la nouvelle notification remplace la notification existante panneau des notifications. |
color |
Facultatif, chaîne |
Couleur de l'icône de la notification, exprimée au format |
click_action |
Facultatif, chaîne |
Action associée à un clic d'un utilisateur sur la notification. Si spécifié, une activité avec un filtre d'intent correspondant est lancée lorsque lorsqu'un utilisateur clique sur la notification. |
body_loc_key |
Facultatif, chaîne |
Clé de la chaîne du 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îne. |
body_loc_args |
Facultatif, tableau JSON sous forme de chaîne |
Valeurs de chaîne de variable à utiliser à la place des spécificateurs de format dans
Voir Mise en forme 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 en fonction de la localisation actuelle de l'utilisateur. Voir Ressources de chaîne. |
title_loc_args |
Facultatif, tableau JSON sous forme de chaîne |
Valeurs de chaîne de variable à utiliser à la place des spécificateurs de format dans
Pour en savoir plus, consultez la section Mise en forme et style. |
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 d'un utilisateur sur la notification. HTTPS est obligatoire pour toutes les valeurs d'URL. |
Interpréter une réponse de message XMPP en aval
Le tableau suivant répertorie les champs qui apparaissent dans une réponse à un message XMPP en aval.
Paramètre | Utilisation | Description |
---|---|---|
from |
Obligatoire, chaîne | Ce paramètre indique 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 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
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 défini sur 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.
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 fichier
registration_id dans un message en texte brut ou dans la to
ou registration_ids en 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 ne plus être valide dans plusieurs cas, par exemple:
|
Expéditeur incohérent | SENDER_ID_MISMATCH |
Un jeton d'enregistrement est lié à un certain groupe d'expéditeurs. Lorsqu'une application cliente s'enregistre pour FCM, elle doit spécifier les expéditeurs autorisés à envoyer des messages. Vous devez en utiliser un de ces ID d'expéditeur lors de l'envoi de messages à l'application cliente. Si vous passez à un autre les jetons d'enregistrement existants ne fonctionneront pas. |
JSON non valide | INVALID_JSON |
Vérifier que le message JSON est correctement formaté et contient des champs valides (par exemple, en s'assurant que le type de données approprié est transmis). |
Message trop volumineux | INVALID_JSON |
Vérifier que la taille totale des données de charge utile incluses dans un message ne dépassent pas les limites de FCM: 4 096 octets pour la plupart des messages ou 2 048 octets pour le cas de messages aux 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 charge utile ne contiennent pas de clé (telle que from ,
gcm ou toute valeur
précédé par google ) qui est utilisé 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 un
en secondes, comprise entre 0 et 2 419 200 (4 semaines). |
Message ACK incorrect | BAD_ACK |
Vérifiez que le message ack est correctement formaté avant de réessayer. Voir
tableau 6 pour plus de détails. |
Délai avant expiration | SERVICE_UNAVAILABLE |
Le serveur n'a pas pu traiter la demande à temps. Réessayez la même requête, mais vous devez :
Remarque: Les expéditeurs problématiques risquent d'être mis sur liste noire. |
Erreur de serveur interne | 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 respectant les conditions mentionnées dans la section "Délai d'expiration" (voir ligne ci-dessus). |
Taux de messages de l'appareil dépassé | DEVICE_MESSAGE_RATE |
Le nombre de messages envoyés à un appareil donné est trop élevé. Réduisez le de messages envoyés à cet appareil, et ne tentez pas de réessayer immédiatement de l'envoyer à cet appareil. |
Taux de messages des sujets dépassé | TOPICS_MESSAGE_RATE |
Le taux de messages envoyés aux abonnés à un sujet particulier est trop élevé. Réduisez le de messages envoyés pour ce sujet, et ne relancez pas l'envoi immédiatement. |
Drainage de connexion | CONNECTION_DRAINING |
Le message n'a pas pu être traité, car la connexion est en cours de drainage. Cela se produit parce que, Périodiquement, FCM doit fermer une connexion pour effectuer l'équilibrage de charge. Renvoyer le message une autre connexion XMPP. |
Identifiants APN non valides | INVALID_APNS_CREDENTIAL |
Impossible d'envoyer un message ciblant un appareil iOS, car les APN requis La clé d'authentification 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 de 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 cliente envoie au serveur d'application. Actuellement, seul XMPP est compatible avec la messagerie en amont. Voir la documentation de votre plate-forme des 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 du bloc XMPP généré par FCM en réponse aux demandes de messages en amont provenant d'applications clientes.
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 ayant 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'applications est censé envoyer FCM en réponse à une message en amont reçu par le serveur d'applications.
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 envoyé par un serveur d'applications à CCS.
Pour les messages en amont, elle doit toujours être définie sur ack . |
FCM messages du serveur (XMPP)
Ceci est un message envoyé par FCM à un serveur d'applications. Voici les principaux types de messages que FCM envoie au serveur d'applications:
- Control (Contrôle) : ces messages générés par CCS indiquent que une action est requise de la part du serveur d'applications.
Le tableau suivant décrit les champs inclus dans les messages CCS envoie à un serveur d'applications.
Paramètre | Utilisation | Description |
---|---|---|
Champ commun | ||
message_type |
Obligatoire, chaîne | Ce paramètre spécifie le type du message: control. Lorsqu'il est défini sur |
control_type |
Facultatif, chaîne | Ce paramètre spécifie le type de message de contrôle envoyé par FCM. Pour le moment, seul le type |