Protocole HTTP de messagerie cloud Firebase

Ce document fournit une référence pour la syntaxe HTTP utilisée pour transmettre les messages de votre serveur d'applications aux applications clientes via Firebase Cloud Messaging.

Lorsque vous utilisez l'ancien protocole HTTP, votre serveur d'applications doit diriger toutes les requêtes HTTP vers ce point de terminaison :

https://fcm.googleapis.com/fcm/send

Les paramètres et options disponibles appartiennent aux grandes catégories suivantes :

Syntaxe des messages en aval

Cette section donne la syntaxe pour envoyer des messages en aval et interpréter les réponses HTTP de Firebase Cloud Messaging.

Messages HTTP en aval (JSON)

Le tableau suivant répertorie les cibles, les options et la charge utile des messages HTTP JSON.

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

Paramètre Usage Description
Cibles
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 vers plusieurs sujets, utilisez le paramètre condition .

registration_ids
Facultatif, tableau de chaînes

Ce paramètre spécifie le destinataire d'un message de multidiffusion, un message envoyé à plusieurs jetons d'enregistrement.

La valeur doit être un tableau de jetons d'enregistrement auxquels envoyer le message de multidiffusion. Le tableau doit contenir au moins 1 et au plus 1 000 jetons d’enregistrement. Pour envoyer un message à un seul appareil, utilisez le paramètre to .

Les messages multidiffusion ne sont autorisés qu'en utilisant le format HTTP JSON.

condition Facultatif, chaîne

Ce paramètre spécifie une expression logique des conditions qui déterminent 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 : && , || . Maximum de deux opérateurs par message thématique pris en charge.

notification_key
Obsolète
Facultatif, chaîne

Ce paramètre est obsolète. Utilisez plutôt to pour spécifier les destinataires des messages. Pour plus d'informations sur la façon d'envoyer des messages à plusieurs appareils, consultez la documentation de votre plateforme.

Possibilités
collapse_key Facultatif, chaîne

Ce paramètre identifie un groupe de messages (par exemple, avec collapse_key: "Updates Available" ) qui peuvent être réduits, de sorte que seul le dernier message soit envoyé lorsque la livraison peut reprendre. Ceci a pour but d'éviter d'envoyer trop de messages identiques lorsque l'appareil revient en ligne ou devient actif.

Notez qu'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 content-available dans la charge utile APN. Lorsqu'une notification ou un message est envoyé et que cette valeur est définie sur true , une application client inactive est réveillée et le message est envoyé via les APN sous forme de notification silencieuse et non via FCM. Notez que l'envoi des notifications silencieuses dans les APN n'est pas garanti et peut dépendre de facteurs tels que l'activation du mode faible consommation 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. Sur Chrome, actuellement non pris en charge.

mutable_content Facultatif, booléen JSON

Sur les plates-formes Apple, utilisez ce champ pour représenter mutable-content dans la charge utile APN. Lorsqu'une notification est envoyée et que cette valeur 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 web.

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 .

restricted_package_
name
(Android uniquement)
Facultatif, chaîne Ce paramètre spécifie le nom du package de l'application où les jetons d'enregistrement doivent correspondre pour recevoir le message.
dry_run Facultatif, booléen

Ce paramètre, lorsqu'il est défini sur true , permet aux développeurs de tester une requête sans réellement envoyer de message.

La valeur par défaut est false .

Charge utile
data Facultatif, objet

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

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

Sur les plateformes Apple, si le message est envoyé via des APN, il représente les champs de données personnalisés. S'il est envoyé via FCM, il sera représenté sous forme de dictionnaire de valeurs-clés dans AppDelegate application:didReceiveRemoteNotification: .

Sur Android, cela entraînerait une intention supplémentaire nommée 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 (tels que collapse_key ).

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 iOS et Android.

Tableau 2a. iOS — touches pour les messages de notification

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 Library/Sounds du conteneur de données de l'application. Consultez la bibliothèque des développeurs iOS pour plus d’informations.

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 0 , le badge est supprimé.

click_action Facultatif, chaîne

L'action associée à un utilisateur clique sur la notification.

Correspond à category dans la charge utile APN.

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 à loc-key dans la charge utile de l'APN.

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 body_loc_key à utiliser pour localiser le corps du texte selon la localisation actuelle de l'utilisateur.

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

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 à title-loc-key dans la charge utile APNs.

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 title_loc_key à utiliser pour localiser le texte du titre dans la localisation actuelle de l'utilisateur.

Correspond aux title-loc-args dans la charge utile APN.

Voir Référence de clé de charge utile et Localisation du contenu de vos notifications à distance pour plus d'informations.

Tableau 2b. Android — touches pour les messages de notification

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 myicon pour la ressource pouvant être dessinée myicon . Si vous n'envoyez pas cette clé dans la demande, FCM affiche l'icône du lanceur spécifiée dans le manifeste de votre application.

sound Facultatif, chaîne

Le son à jouer lorsque l'appareil reçoit la notification.

Prend en charge "default" ou le nom de fichier d'une ressource sonore fournie dans l'application. Les fichiers son doivent résider dans /res/raw/ .

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 #rrggbb .

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 body_loc_key à utiliser pour localiser le corps du texte selon la localisation actuelle de l'utilisateur.

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 title_loc_key à utiliser pour localiser le texte du titre dans la localisation actuelle de l'utilisateur.

Voir Formatage et style pour plus d’informations.

Tableau 2c. Web (JavaScript) — touches pour les messages de notification

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.

Messages HTTP en aval (texte brut)

Le tableau suivant répertorie la syntaxe des cibles, des options et de la charge utile dans les messages HTTP en aval en texte brut.

Tableau 3. Cibles, options et charge utile pour les messages HTTP en texte brut en aval.

Paramètre Usage Description
Cibles
registration_id Obligatoire, chaîne

Ce paramètre spécifie les applications clientes (jetons d'enregistrement) recevant le message.

La messagerie multidiffusion (envoi à plusieurs jetons d'enregistrement) est autorisée uniquement en utilisant le format HTTP JSON.

Possibilités
collapse_key Facultatif, chaîne Voir le tableau 1 pour plus de détails.
time_to_live Facultatif, numéro Voir le tableau 1 pour plus de détails.
restricted_package_name Facultatif, chaîne Voir le tableau 1 pour plus de détails.
dry_run Facultatif, booléen Voir le tableau 1 pour plus de détails.
Charge utile
data.<key> Facultatif, chaîne

Ce paramètre spécifie les paires clé-valeur de la charge utile du message. Il n'y a aucune limite sur le nombre de paramètres clé-valeur, mais il existe une limite de taille totale de message de 4 000 octets.

Par exemple, sous Android, "data.score"."3x1" entraînerait une intention supplémentaire nommée 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 (tels que collapse_key ).

Interprétation d'une réponse à un message en aval

Le serveur d'applications doit évaluer à la fois l'en-tête et le corps de la réponse au message pour interpréter la réponse au message envoyé par FCM. Le tableau suivant décrit les réponses possibles.

Tableau 4. En-tête de réponse du message HTTP en aval.

Réponse Description
200 Le message a été traité avec succès. Le corps de la réponse contiendra plus de détails sur l'état du message, mais son format dépendra du fait que la demande soit au format JSON ou en texte brut. Voir le tableau 5 pour plus de détails.
400 S'applique uniquement aux requêtes JSON. Indique que la requête n'a pas pu être analysée en tant que JSON ou qu'elle contenait des champs non valides (par exemple, en passant une chaîne là où un nombre était attendu). La raison exacte de l'échec est décrite dans la réponse et le problème doit être résolu avant que la demande puisse être réessayée.
401 Une erreur s'est produite lors de l'authentification du compte de l'expéditeur.
5xx Les erreurs comprises entre 500 et 599 (telles que 500 ou 503) indiquent qu'une erreur interne s'est produite dans le backend FCM lors de la tentative de traitement de la demande ou que le serveur est temporairement indisponible (par exemple, en raison de délais d'attente). L’expéditeur doit réessayer plus tard, en respectant tout en-tête Retry-After inclus dans la réponse. Les serveurs d'applications doivent implémenter un back-off exponentiel.

Le tableau suivant répertorie les champs d'un corps de réponse de message en aval (JSON).

Tableau 5. Corps de réponse du message HTTP en aval (JSON).

Paramètre Usage Description
multicast_id Obligatoire, numéro ID unique (numéro) identifiant le message multicast.
success Obligatoire, numéro Nombre de messages traités sans erreur.
failure Obligatoire, numéro Nombre de messages qui n'ont pas pu être traités.
results Obligatoire, tableau d'objets Tableau d'objets représentant l'état des messages traités. Les objets sont répertoriés dans le même ordre que la requête (c'est-à-dire que pour chaque ID d'enregistrement dans la requête, son résultat est répertorié dans le même index dans la réponse).
  • message_id : chaîne spécifiant un identifiant unique pour chaque message traité avec succès.
  • error : Chaîne spécifiant l'erreur survenue lors du traitement du message pour le destinataire. Les valeurs possibles se trouvent dans le tableau 9 .

Tableau 6. Corps de réponse HTTP (JSON) du message de sujet.

Paramètre Usage Description
message_id Facultatif, numéro ID du message de sujet lorsque FCM a reçu avec succès la demande et tentera de la transmettre à tous les appareils abonnés.
error Facultatif, chaîne Erreur survenue lors du traitement du message. Les valeurs possibles se trouvent dans le tableau 9 .

Tableau 7. Réponse réussie pour le corps de la réponse du message HTTP en aval (texte brut).

Paramètre Usage Description
id Obligatoire, chaîne Ce paramètre spécifie l'ID de message unique que FCM a traité avec succès.
registration_id Facultatif, chaîne Ce paramètre spécifie le jeton d'enregistrement de l'application client à laquelle le message a été traité et envoyé.

Tableau 8. Réponse d'erreur pour le corps de la réponse du message HTTP en aval (texte brut).

Paramètre Usage Description
Error Obligatoire, chaîne Ce paramètre spécifie la valeur d'erreur lors du traitement du message pour le destinataire. Voir le tableau 9 pour plus de détails.

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.

Tableau 9. Codes de réponse d'erreur du message en aval.

Erreur Code HTTP Action recommandée
Jeton d'enregistrement manquant 200 + erreur : inscription manquante 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).
Jeton d'enregistrement invalide 200 + erreur : InvalidRegistration 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 des notifications Firebase. Ne tronquez pas et n’ajoutez pas de caractères supplémentaires.
Appareil non enregistré 200 + erreur : non enregistré Un jeton d'enregistrement existant peut cesser d'être valide dans un certain nombre de scénarios, notamment :
  • Si l'application client se désinscrit auprès de FCM.
  • Si l'application client est automatiquement désenregistrée, ce qui peut se produire si l'utilisateur désinstalle l'application. Par exemple, sur iOS, si le service de commentaires 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 APNs a expiré pour les appareils iOS).
  • Si l'application client 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 d'applications et arrêtez de l'utiliser pour envoyer des messages.
Nom de package invalide 200 + erreur : InvalidPackageName Assurez-vous que le message a été adressé à un jeton d'enregistrement dont le nom du package correspond à la valeur transmise dans la demande.
Erreur d'authentification 401 Le compte de l'expéditeur utilisé pour envoyer un message n'a pas pu être authentifié. Les causes possibles sont :
  • En-tête d'autorisation manquant ou avec une syntaxe non valide dans la requête HTTP.
  • Le projet Firebase auquel appartient la clé de serveur spécifiée est incorrect.
  • Clés de serveur héritées uniquement : la demande provient d'un serveur qui ne figure pas sur la liste blanche dans les adresses IP des clés de serveur.
Vérifiez que le jeton que vous envoyez dans l'en-tête d'authentification est la bonne clé de serveur associée à votre projet. Voir Vérification de la validité d'une clé de serveur pour plus de détails. Si vous utilisez une ancienne clé de serveur, il est recommandé de passer à une nouvelle clé sans restriction IP. Voir Migrer les clés de serveur héritées .
Expéditeur incompatible 200 + erreur : MismatchSenderId 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 400 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).
Paramètres invalides 400 + erreur : Paramètres invalides Vérifiez que les paramètres fournis ont le bon nom et le bon type.
Message trop gros 200 + erreur : MessageTooBig 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 200 + erreur :
Clé de données invalide
Vérifiez que les données de charge utile ne contiennent pas de clé (telle que from , ou gcm , ou toute valeur préfixée par google ) utilisée en interne par FCM. Notez que certains mots (tels collapse_key ) sont également utilisés par FCM mais sont autorisés dans la charge utile, auquel cas la valeur de la charge utile sera remplacée par la valeur FCM.
Durée de vie invalide 200 + erreur : InvalidTtl 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).
Temps mort Erreur 5xx ou 200 + : indisponible

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

  • Respectez l'en-tête Retry-After s'il est inclus dans la réponse du serveur de connexion FCM.
  • Implémentez une interruption exponentielle dans votre mécanisme de nouvelle tentative. (par exemple, si vous avez attendu une seconde avant la première tentative, attendez au moins deux secondes avant la suivante, puis 4 secondes et ainsi de suite). Si vous envoyez plusieurs messages, retardez chacun indépendamment d'un montant aléatoire supplémentaire pour éviter d'émettre une nouvelle demande pour tous les messages en même temps.

Les expéditeurs qui posent problème risquent d’être mis sur liste noire.

Erreur interne du serveur 500 ou 200 + erreur : InternalServerError 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). Si l'erreur persiste, veuillez contacter l'assistance Firebase .
Débit de messages du périphérique dépassé 200 + erreur :
Taux de messages de périphérique
Dépassé

Le débit de messages vers un appareil particulier est trop élevé. Si une application Apple envoie des messages à une vitesse dépassant les limites des APN, elle peut recevoir ce message d'erreur.

Réduisez le nombre de messages envoyés à cet appareil et utilisez l'intervalle exponentiel pour réessayer l'envoi.

Sujets Débit de messages dépassé 200 + erreur :
SujetsMessageRate
Dépassé
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 utilisez l'intervalle exponentiel pour réessayer l'envoi.
Identifiants APN invalides 200 + erreur :
InvalidApnsCredential
Un message destiné à un appareil Apple 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.

Gestion des groupes d'appareils

Le tableau suivant répertorie les clés permettant de créer des groupes de périphériques et d'ajouter et de supprimer des membres. Pour plus d'informations, consultez le guide de votre plateforme, iOS+ ou Android .

Tableau 10. Clés de gestion des groupes de périphériques.

Paramètre Usage Description
operation Obligatoire, chaîne L'opération à exécuter. Les valeurs valides sont create , add et remove .
notification_key_name Obligatoire, chaîne Nom défini par l'utilisateur du groupe de périphériques à créer ou à modifier.
notification_key Obligatoire (sauf pour l'opération create , chaîne Identifiant unique du groupe de périphériques. Cette valeur est renvoyée dans la réponse pour une opération create réussie et est requise pour toutes les opérations ultérieures sur le groupe de périphériques.
registration_ids Obligatoire, tableau de chaînes Les jetons de périphérique à ajouter ou à supprimer. Si vous supprimez tous les jetons d'enregistrement existants d'un groupe de périphériques, FCM supprime le groupe de périphériques.