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 ajouter des métadonnées à l’aide de 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, puis Ajouter une nouvelle paire, et indiquez vos paires clé-valeur.
Les valeurs des paires clé-valeur ajoutées dans le compositeur de messages 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 Apple Push Notification (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 type chaîne de caractères, sauf si vous les analysez dans votre intégration.
iOS
Le service Apple Push Notification (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 comprend 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 et des boutons Fermer et Afficher ; pour les autres types, affiche une alerte ou une bannière selon les propriétés enfants de l’entrée |
| badge | nombre | Définit le nombre affiché en tant que 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 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 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 indiqué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 notification pour la localisation actuelle à partir du fichier Localizable.strings |
| loc-args | tableau de chaînes de caractères | Valeurs de chaîne 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 crée automatiquement les 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 une clé du dictionnaire d’alerte pour que la clé soit 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 cas d’usage des paires clé-valeur personnalisées incluent notamment le suivi d’indicateurs internes et la définition du 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 traiter cette clé personnalisée.

Évitez de traiter une clé ou un dictionnaire de premier niveau nommé ab dans votre application.
Apple conseille de ne pas inclure d’informations client ni de 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 l’appareil.

Si vous utilisez l’API de fournisseur HTTP/2, chaque payload envoyé à APNs ne peut pas dépasser 4 096 octets. L’ancienne interface binaire, bientôt obsolète, ne prend en charge que des payloads de 2 048 octets.
Campaigns 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 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 dans la console de développement la sortie suivante : "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 au suivi d’indicateurs internes et à la définition du contexte de l’interface utilisateur, mais vous pouvez les utiliser à toutes les fins de votre choix.

Le backend de votre application doit pouvoir traiter les paires clé-valeur personnalisées pour que le payload de données fonctionne correctement.
Campaigns 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 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 dans la console de développement la sortie suivante : "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 la 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 permettent également le 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 à cibler uniquement un utilisateur test en filtrant sur l’ID utilisateur externe ou l’adresse e-mail.
Au lancement de la Campaign, 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 distribution 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 de certaines fonctionnalités de Braze, notamment le suivi des désinstallations et les Push Stories. Pour savoir ce qu’iOS filtre et dans quelles conditions, consultez la section Limites d’iOS.
Messages in-app
Ajoutez des paires clé-valeur à n’importe quel message in-app que vous créez dans le compositeur.
- Dans votre campagne ou votre Canvas, créez ou modifiez un message in-app.
- Dans le compositeur de messages, sélectionnez l’onglet Paramètres.
- Dans Paires clé-valeur, sélectionnez 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.
Campagnes déclenchées par API
Braze vous permet d’envoyer des paires clé-valeur personnalisées de type chaîne de caractères, 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 }.
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 en tant qu’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 du webhook d’événement de SendGrid.

Les e-mails rejetés 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.