Paires clé-valeur
Cette page explique comment utiliser les paires clé-valeur pour envoyer des payloads de données supplémentaires aux appareils des utilisateurs. Cette fonctionnalité est disponible pour les canaux de communication push, in-app, e-mail et Content Cards.
Utilisez les paires clé-valeur pour ajouter des métadonnées structurées à vos messages. Ces payloads de données supplémentaires peuvent enrichir les messages avec des informations contextuelles qui influencent la manière dont un message est affiché ou traité.
Comme les paires clé-valeur sont des métadonnées, ces données ne sont pas nécessairement visibles par le destinataire, mais vos systèmes ou processus connectés peuvent les utiliser pour personnaliser le traitement des messages.
Chaque paire se compose de :
- Clé : l’identifiant (exemple :
utm_source) - Valeur : la donnée associée (exemple :
newsletter)
Cas d’usage
Voici quelques exemples de cas d’usage pour l’ajout de métadonnées avec des paires clé-valeur :
- Paramètres de suivi : Ajouter des paramètres UTM à des fins d’analyse
- Clé :
utm_campaign - Valeur :
spring_sale
- Clé :
- Étiquettes personnalisées : Ajouter des étiquettes pour le routage interne ou la catégorisation
- Clé :
priority - Valeur :
high
- Clé :
- Déclencheurs de comportement : Métadonnées utilisées pour déclencher ou personnaliser des comportements in-app
- Clé :
deep_link - Valeur :
app://promo-page
- Clé :
Notifications push
Vous pouvez ajouter des paires clé-valeur aux notifications push Android, iOS et Web. Elles vous permettent par exemple de mettre à jour des indicateurs internes et le contenu de l’application, ou de personnaliser les propriétés des notifications push, comme la priorité des alertes, la localisation et les sons.
Dans le compositeur de messages, sélectionnez l’onglet Paramètres, cliquez sur Ajouter une nouvelle paire, puis indiquez vos paires clé-valeur.
Lorsque vous ajoutez des paires clé-valeur dans le compositeur de messages, les valeurs sont envoyées sous forme de chaînes de caractères. Pour les notifications push iOS, les clés d’alerte réservées du service de notification push d’Apple (APNs) que vous ajoutez via Options d’alerte (comme loc-args pour les arguments de localisation) sont formatées avec les types JSON appropriés dans le payload. Pour les clés personnalisées, votre application reçoit des valeurs de chaîne de caractères, sauf si vous les analysez dans votre intégration.
iOS
Le service de notification push d’Apple (APNs) permet de définir des préférences d’alerte et d’envoyer des données personnalisées à l’aide de paires clé-valeur. APNs utilise la bibliothèque aps réservée par Apple, qui contient des clés et des valeurs prédéfinies régissant les propriétés des alertes.
Bibliothèque APS
| Clé | Type de valeur | Description de la valeur |
|---|---|---|
| alert | chaîne de caractères ou objet dictionnaire | Pour une chaîne de caractères, affiche une alerte avec la chaîne comme message, accompagnée des boutons Fermer et Afficher ; pour les autres types d’entrée, affiche une alerte ou une bannière selon les propriétés enfants de l’entrée |
| badge | nombre | Détermine le nombre affiché comme badge sur l’icône de l’application |
| sound | chaîne de caractères | Nom du fichier son à lire comme alerte ; il doit se trouver dans le bundle de l’application ou dans le dossier Library/Sounds |
| content-available | nombre | Une valeur de 1 signale à l’application que de nouvelles informations sont disponibles au lancement ou à la reprise de la session |
Bibliothèque des propriétés d’alerte
| Clé | Type de valeur | Description de la valeur |
|---|---|---|
| title | chaîne de caractères | Courte chaîne de caractères que l’Apple Watch affiche brièvement dans le cadre d’une notification |
| body | chaîne de caractères | Contenu de la notification push |
| title-loc-key | chaîne de caractères ou null | Clé qui définit la chaîne du titre pour la localisation actuelle à partir du fichier Localizable.strings |
| title-loc-args | tableau de chaînes de caractères ou null | Valeurs de chaîne de caractères pouvant remplacer les spécificateurs de format de localisation du titre dans title-loc-key |
| action-loc-key | tableau de chaînes de caractères ou null | Si elle est présente, la chaîne spécifiée définit la localisation des boutons Fermer et Afficher |
| loc-key | chaîne de caractères ou null | Clé qui définit le message de la notification pour la localisation actuelle à partir du fichier Localizable.strings |
| loc-args | tableau de chaînes de caractères | Valeurs de chaîne de caractères pouvant remplacer les spécificateurs de format de localisation dans loc-key |
| launch-image | chaînes de caractères | Nom d’un fichier image du bundle de l’application à utiliser comme image de lancement lorsque l’utilisateur appuie sur le bouton d’action ou fait glisser le curseur d’action |
Le compositeur de messages de Braze gère automatiquement la création des clés suivantes : alert et ses propriétés, content-available, sound et category.
Vous pouvez saisir ces valeurs dans l’onglet Paramètres lors de la création d’un message push. Sélectionnez Options d’alerte, puis choisissez une clé du dictionnaire d’alerte : la clé est alors automatiquement renseignée dans une nouvelle entrée clé-valeur.

Lorsque Braze envoie une notification push à APNs, le payload est formaté en JSON.
Payload simple
{
"aps" : { "alert" : "Message received from Spencer" },
}
Payload complexe
{
"aps" : {
"alert" : {
"body" : "Hi, welcome to our app!",
"loc-key" : "France",
"loc-args" : ["Bonjour", "bienvenue"],
"action-loc-key" : "Button_Type_1",
"launch-image" : "Paris"
},
"content-available" : 1
},
}
Paires clé-valeur personnalisées
En plus des valeurs de payload de la bibliothèque aps, vous pouvez envoyer des paires clé-valeur personnalisées à l’appareil d’un utilisateur. Les valeurs de ces paires sont limitées aux types primitifs : dictionnaire (objet), tableau, chaîne de caractères, nombre et booléen.

Les paires clé-valeur personnalisées peuvent notamment servir à tenir des indicateurs internes ou à définir le contexte de l’interface utilisateur. Braze vous permet d’envoyer des paires clé-valeur supplémentaires avec une notification push, que votre application peut exploiter via la clé extras. Si vous préférez utiliser une autre clé, vérifiez que votre application est capable de gérer cette clé personnalisée.

Évitez de traiter une clé ou un dictionnaire de premier niveau nommé ab dans votre application.
Apple conseille d’éviter d’inclure des informations client ou des données sensibles dans les données de payload personnalisées. Apple recommande également qu’aucune action associée à un message d’alerte ne supprime de données sur un appareil.

Si vous utilisez l’API de fournisseur HTTP/2, chaque payload envoyé à APNs ne doit pas dépasser 4 096 octets. L’ancienne interface binaire, qui sera bientôt obsolète, ne prend en charge que des payloads de 2 048 octets.
Campagnes déclenchées par API
Braze vous permet d’envoyer des paires clé-valeur de chaînes de caractères personnalisées, appelées extras. Pour accéder à vos extras dans les campagnes déclenchées par API et les campagnes planifiées déclenchées par API, définissez dans le tableau de bord une clé « example_key » et une valeur "$json:{"foo": 1, "bar": 1}". Vous obtiendrez alors la sortie suivante dans la console de développement : "extras": { "test": { "foo": 1, "bar": 1 }
Android
Braze vous permet d’envoyer des payloads de données supplémentaires dans les notifications push à l’aide de paires clé-valeur.
Payload de données
Comme pour les notifications push iOS, vous pouvez envoyer des paires clé-valeur personnalisées à l’appareil d’un utilisateur.
Les paires clé-valeur personnalisées peuvent notamment servir à tenir des indicateurs internes ou à définir le contexte de l’interface utilisateur, mais vous pouvez les utiliser à toute autre fin.

Le backend de votre application doit pouvoir traiter les paires clé-valeur personnalisées pour que le payload de données fonctionne correctement.
Campagnes déclenchées par API
Braze vous permet d’envoyer des paires clé-valeur de chaînes de caractères personnalisées, appelées extras. Pour accéder à vos extras dans les campagnes déclenchées par API et les campagnes planifiées déclenchées par API, définissez dans le tableau de bord une clé « example_key » et une valeur "$json:{"foo": 1, "bar": 1}". Vous obtiendrez alors la sortie suivante dans la console de développement : "extras": { "test": { "foo": 1, "bar": 1 }.
Options de messagerie FCM
Vous pouvez personnaliser davantage les notifications push Android grâce aux options de message FCM. Celles-ci incluent la priorité de notification, le son, le délai, la durée de vie et la possibilité de regroupement. Vous pouvez définir ces valeurs dans l’onglet Paramètres lors de la création d’un message push. Consultez la section Paramètres avancés des notifications push pour savoir comment configurer ces options dans le compositeur de messages de Braze.

Notifications push silencieuses
Une notification push silencieuse est une notification push sans message d’alerte ni son, utilisée pour mettre à jour l’interface ou le contenu de votre application en arrière-plan. Ces notifications s’appuient sur des paires clé-valeur pour déclencher ces actions en arrière-plan. Les notifications push silencieuses alimentent également notre suivi des désinstallations.
Les marketeurs doivent vérifier que les notifications push silencieuses déclenchent le comportement attendu avant de les envoyer aux utilisateurs de leur application. Après avoir rédigé votre notification push silencieuse iOS ou Android, veillez à ne cibler qu’un utilisateur test en filtrant sur l’ID utilisateur externe ou l’adresse e-mail.
Après le lancement de la campagne, vérifiez que vous n’avez reçu aucune notification push visible sur votre appareil de test.

Le filtrage des notifications silencieuses par iOS peut entraîner les symptômes suivants :
- Des indicateurs de suivi des désinstallations inférieurs aux attentes pour les utilisateurs iOS
- Une réception irrégulière ou retardée des notifications push silencieuses
- Des Push Stories qui ne s’affichent pas
- Des Push Stories qui arrivent sans les images, vidéos ou pages attendues
Il s’agit d’une limitation de la plateforme Apple, et non d’un problème lié à Braze. iOS peut retarder ou abandonner les notifications en arrière-plan pour certaines fonctionnalités de Braze, notamment le suivi des désinstallations et les Push Stories. Pour en savoir plus sur ce que iOS filtre et dans quels cas, consultez la section Limitations iOS.
Messages in-app
Ajoutez des paires clé-valeur à n’importe quel message in-app que vous créez dans Braze.
- Dans votre Campaign ou votre Canvas, créez ou modifiez un message in-app.
- Dans l’éditeur de messages, sélectionnez l’onglet Paramètres.
- Sélectionnez Ajouter une nouvelle paire :
- Éditeur traditionnel : dans Paires clé-valeur, sélectionnez Ajouter une nouvelle paire.
- Éditeur par glisser-déposer : sélectionnez l’onglet Paires clé-valeur, puis Ajouter une nouvelle paire.
- Saisissez une clé et une valeur pour chaque paire. Pour ajouter une autre paire, sélectionnez à nouveau Ajouter une nouvelle paire.
Campaigns déclenchées par API
Braze vous permet d’envoyer des paires clé-valeur de type chaîne de caractères personnalisées, appelées extras. Pour accéder à vos extras dans les Campaigns déclenchées par API et les Campaigns planifiées déclenchées par API, définissez dans le tableau de bord une clé « example_key » et une valeur "$json:{"foo": 1, "bar": 1}". Vous obtiendrez alors la sortie suivante dans la console de développement : "extras": { "test": { "foo": 1, "bar": 1 }.
E-mails
SparkPost et SendGrid prennent tous deux en charge les paires clé-valeur dans les e-mails. Si vous utilisez SendGrid, les paires clé-valeur seront envoyées sous forme d’arguments uniques. SendGrid vous permet de joindre un nombre illimité de paires clé-valeur, dans la limite de 10 000 octets de données. Ces paires clé-valeur sont visibles dans les publications de l’Event Webhook de SendGrid.

Les e-mails ayant fait l’objet d’un rebond ne transmettront pas de paires clé-valeur à SparkPost ou SendGrid.

Content Cards
Pour ajouter une paire clé-valeur à une Content Card, accédez à l’onglet Settings dans le composeur de messages Braze et sélectionnez Add New Pair.


Les variantes de contrôle ne prennent pas en charge les paires clé-valeur. Si vous devez capturer des analyses pour les groupes de contrôle dans les tests A/B, créez une variante de message avec une paire clé-valeur telle que control=true et masquez-la dans le code de votre application tout en enregistrant les impressions.