Ce document fournit une documentation de référence sur la syntaxe HTTP utilisée pour transmettre des 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 présente la syntaxe permettant d'envoyer des messages en aval et d'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.
Paramètres | Utilisation | 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 (avec le préfixe |
|
registration_ids | Facultatif, tableau de chaînes |
Ce paramètre spécifie le destinataire d'un message de multidiffusion, c'est-à-dire 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 entre 1 et 1 000 jetons d'enregistrement. Pour envoyer un message à un seul appareil, utilisez le paramètre Les messages de multidiffusion ne sont autorisés qu'avec 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 acceptée: thème, au format "'votreSujet' dans les sujets". Cette valeur n'est pas sensible à la casse. Opérateurs compatibles: |
|
notification_key Obsolète |
Facultatif, chaîne | Ce paramètre est obsolète. Utilisez plutôt |
|
Options | |||
collapse_key |
Facultatif, chaîne | Ce paramètre identifie un groupe de messages (par exemple, avec Notez que nous ne pouvons pas garantir l'ordre dans lequel les messages sont envoyés. Remarque: Un maximum de quatre clés de réduction différentes est autorisé à 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'y a aucune garantie que les quatre clés de réduction seront conservées par FCM. |
|
priority |
Facultatif, chaîne | Définit la priorité du message. Les valeurs valides sont "normal" et "high." Sur les plates-formes Apple, ils correspondent aux priorités 5 et 10 du service APNs. 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 l'utilisation de la batterie de l'application cliente. Elle doit être utilisée, sauf si une diffusion immédiate est requise. Pour les messages dont la priorité est normale, l'application peut les recevoir 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 |
|
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 4 semaines. Pour en savoir plus, consultez Définir la durée de vie d'un message. |
|
restricted_package_
(Android uniquement) |
Facultatif, chaîne | Ce paramètre spécifie le nom de package de l'application auquel les jetons d'enregistrement doivent correspondre pour recevoir le 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 personnalisées de la charge utile du message. Par exemple, avec Sur les plates-formes Apple, si le message est envoyé via APNs, il représente les champs de données personnalisés. Si elle est envoyée via FCM, elle est représentée sous la forme d'un dictionnaire clé-valeur dans Sur Android, cela se traduira par 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 (par exemple, Il est recommandé d'utiliser des valeurs de type chaîne. Vous devez convertir les valeurs d'objets ou d'autres types de données qui ne sont pas des chaînes (par exemple, des entiers ou des valeurs booléennes) en chaîne. |
|
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 "Prise en charge de la charge utile des notifications".
Pour en savoir plus sur les options des messages de notification et des messages 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 adressé à un appareil Apple, le message est envoyé via APNs. Sinon, il est envoyé via FCM.
|
Prise en charge de la charge utile des notifications
Les tableaux suivants répertorient les clés prédéfinies disponibles pour créer des messages de notification pour iOS et Android.
Paramètres | 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 le 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é.
S'il est défini sur |
click_action |
Facultatif, chaîne |
Action associée à un clic d'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 à Pour en savoir plus, consultez la documentation de référence sur la clé de charge utile et la localisation du contenu de vos notifications à distance. |
body_loc_args |
Tableau JSON facultatif sous forme de chaîne |
Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans
Correspond à Pour en savoir plus, consultez la documentation de référence sur la clé de charge utile et la localisation du 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 la documentation de référence sur la clé de charge utile et la localisation du contenu de vos notifications à distance. |
title_loc_args |
Tableau JSON facultatif 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 la documentation de référence sur la clé de charge utile et la localisation du contenu de vos notifications à distance. |
Paramètres | 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 (nouveau dans Android O). L'application doit créer une chaîne avec cet ID de chaîne avant de recevoir toute notification ayant cet ID. Si vous n'envoyez pas cet ID de chaîne dans la requête, ou si l'ID de canal 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. Si aucune valeur n'est spécifiée, chaque requête crée une notification. Si cette option est spécifiée et qu'une notification comportant le même tag est déjà affichée, la nouvelle notification remplace celle existante dans le 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'utilisateur sur la notification. Si cette option est spécifiée, 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 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. Pour en savoir plus, consultez la section Ressources de chaîne. |
body_loc_args |
Tableau JSON facultatif sous forme de chaîne |
Valeurs de chaîne variable à utiliser à la place des spécificateurs de format dans Pour en savoir plus, consultez 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 selon la localisation actuelle de l'utilisateur. Pour en savoir plus, consultez la section Ressources de chaîne. |
title_loc_args |
Tableau JSON facultatif 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 Mise en forme et style. |
Paramètres | 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'utilisateur sur la notification. Le protocole HTTPS est requis pour toutes les valeurs d'URL. |
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.
Paramètres | Utilisation | 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 au format HTTP JSON. |
Options | ||
collapse_key |
Facultatif, chaîne | Pour en savoir plus, consultez le tableau 1. |
time_to_live |
Facultatif, nombre | Pour en savoir plus, consultez le tableau 1. |
restricted_package_name |
Facultatif, chaîne | Pour en savoir plus, consultez le tableau 1. |
dry_run |
Facultatif, booléen | Pour en savoir plus, consultez le tableau 1. |
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 pas de limite au nombre de paramètres clé-valeur, mais la taille totale des messages est limitée à 4 096 octets. Par exemple, dans Android, 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 cette table (par exemple, |
Interpréter la réponse d'un message en aval
Le serveur d'applications doit évaluer à la fois l'en-tête et le corps de la réponse du message pour interpréter la réponse envoyée par FCM. Le tableau suivant décrit les réponses possibles.
Réponse | Description |
---|---|
200 | Le message a bien été traité. Le corps de la réponse contiendra plus de détails sur l'état du message, mais son format dépendra du format de la requête (au format JSON ou texte brut). Pour en savoir plus, consultez le tableau 5. |
400 | Ne s'applique qu'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, transmission d'une chaîne alors qu'un nombre était attendu). Le motif exact de l'échec est décrit dans la réponse. Le problème doit être résolu avant que la requête puisse être relancée. |
401 | Une erreur s'est produite lors de l'authentification du compte de l'expéditeur. |
5xx | Les erreurs de la plage 500 à 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 requête, ou que le serveur est temporairement indisponible (en raison de délais d'inactivité, par exemple). 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 mettre en œuvre un intervalle exponentiel entre les tentatives. |
Le tableau suivant répertorie les champs d'un corps de réponse aux messages en aval (JSON).
Paramètres | Utilisation | Description |
---|---|---|
multicast_id |
Obligatoire, nombre | Identifiant unique (numéro) identifiant le message de multidiffusion. |
success |
Obligatoire, nombre | Nombre de messages traités sans erreur. |
failure |
Obligatoire, nombre | 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 (par exemple, pour chaque ID d'enregistrement de la requête, le résultat est répertorié dans le même index dans la réponse).
|
Paramètres | Utilisation | Description |
---|---|---|
message_id |
Facultatif, nombre | ID du message du sujet lorsque FCM a bien reçu la requête et tente d'être distribué à tous les appareils abonnés. |
error |
Facultatif, chaîne | Erreur qui s'est produite lors du traitement du message. Les valeurs possibles figurent dans le tableau 9. |
Paramètres | Utilisation | Description |
---|---|---|
id |
Obligatoire, chaîne | Ce paramètre spécifie l'ID de message unique traité par FCM. |
registration_id |
Facultatif, chaîne | Ce paramètre spécifie le jeton d'enregistrement de l'application cliente à laquelle le message a été traité et envoyé. |
Paramètres | Utilisation | Description |
---|---|---|
Error |
Obligatoire, chaîne | Ce paramètre spécifie la valeur d'erreur lors du traitement du message destiné au destinataire. Pour en savoir plus, consultez le tableau 9. |
Codes de réponse d'erreur pour les messages en aval
Le tableau suivant répertorie les codes de réponse d'erreur pour les messages en aval.
Erreur | HTTP Code | Action recommandée |
---|---|---|
Jeton d'enregistrement manquant | 200 ou erreur:MissingRegistration | Vérifiez que la requête contient un jeton d'enregistrement (dans le champ registration_id d'un message en texte brut, ou dans le champ to ou registration_ids en JSON). |
Jeton d'enregistrement non valide | 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 cliente reçoit lors de l'inscription à Firebase Notifications. Ne tronquez pas et n'ajoutez pas de caractères supplémentaires. |
Appareil non enregistré | 200 + erreur:NotRegistered | Un jeton d'enregistrement existant peut ne plus être valide dans plusieurs cas, par exemple:
|
Nom de package non valide. | 200 + erreur:InvalidPackageName | Assurez-vous que le message a été adressé à un jeton d'enregistrement dont le nom de package correspond à la valeur transmise dans la requête. |
Erreur d'authentification. | 401 | Le compte de l'expéditeur utilisé pour envoyer un message n'a pas pu être authentifié. Causes possibles:
|
Expéditeur incohérent | 200 + erreur:MismatchSenderId | Un jeton d'enregistrement est lié à un certain groupe d'expéditeurs. Lorsqu'une application cliente s'enregistre dans 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 | 400 | Vérifiez que le message JSON est correctement formaté et contient des champs valides (par exemple, en veillant à transmettre le bon type de données). |
Paramètres non valides. | 400 + erreur:InvalidParameters | Vérifiez que le nom et le type des paramètres fournis sont corrects. |
Message trop volumineux | 200 + erreur:MessageTooBig | 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 pour les messages envoyés à des sujets. Cela inclut à la fois les clés et les valeurs. |
Clé de données non valide | 200 + erreur :
InvalidDataKey |
Vérifiez que les données de charge utile ne contiennent pas de clé (telle que from ou gcm , ou toute valeur précédée de 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 sera remplacée par la valeur FCM. |
Valeur TTL incorrecte | 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 (quatre semaines). |
Délai avant expiration | 5xx ou 200 + erreur:non disponible | Le serveur n'a pas pu traiter la demande à temps. Réessayez la même requête, mais vous devez:
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 du traitement de la demande. Vous pouvez relancer la même requête en respectant les exigences indiquées dans la section "Délai avant expiration" (voir la ligne ci-dessus). Si l'erreur persiste, veuillez contacter l'assistance Firebase. |
Taux de messages sur l'appareil dépassé | 200 + erreur :
DeviceMessageRate Dépassé |
Le nombre de messages envoyés sur un appareil spécifique est trop élevé. Si une application Apple envoie des messages à un débit supérieur aux limites du service APNs, elle peut recevoir ce message d'erreur Réduisez le nombre de messages envoyés à cet appareil et appliquez un intervalle exposant entre les tentatives pour relancer l'envoi. |
Taux de messages des sujets dépassé | 200 + erreur :
TopicsMessageRate Dépassé |
Le taux de messages envoyés aux abonnés à un sujet particulier est trop élevé. Réduisez le nombre de messages envoyés pour ce sujet et appliquez un intervalle exposant entre les tentatives pour relancer l'envoi. |
Identifiants APN non valides | 200 et erreur :
InvalidApnsCredential |
Un message ciblant un appareil Apple n'a pas pu être envoyé, car la clé d'authentification APNs requise n'a pas été importée ou a expiré. Vérifiez la validité de vos identifiants 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 d'appareils, et d'ajouter et de supprimer des membres. Pour en savoir plus, consultez le guide correspondant à votre plate-forme, iOS+ ou Android.
Paramètres | Utilisation | 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 d'appareils à créer ou à modifier. |
notification_key |
Obligatoire (sauf pour l'opération create et la chaîne) |
Identifiant unique du groupe d'appareils. Cette valeur est renvoyée dans la réponse si l'opération create aboutit. Elle est obligatoire pour toutes les opérations ultérieures sur le groupe d'appareils. |
registration_ids |
Obligatoire, tableau de chaînes | Jetons d'appareil à ajouter ou à supprimer. Si vous supprimez tous les jetons d'enregistrement existants d'un groupe d'appareils, FCM supprime le groupe d'appareils. |