Attributs personnalisés imbriqués
Cette page traite des attributs personnalisés imbriqués, qui vous permettent de définir un ensemble d’attributs en tant que propriété d’un autre attribut. En d’autres termes, lorsque vous définissez un objet d’attribut personnalisé, vous pouvez définir un ensemble d’attributs supplémentaires pour cet objet.
À propos des attributs imbriqués
Les attributs imbriqués vous permettent de créer des segments plus riches et de personnaliser vos messages à l’aide des données d’un seul objet d’attribut personnalisé.
Dans l’exemple suivant, l’attribut personnalisé favorite_book contient les attributs imbriqués title, author et publishing_date. Cet objet peut servir à cibler les utilisateurs par auteur, à filtrer par date de publication ou à insérer directement le titre du livre dans un message :
"favorite_book": {
"title": "The Hobbit",
"author": "J.R.R. Tolkien",
"publishing_date": "1937"
}
Types de données pris en charge
Les types de données suivants sont pris en charge :
| Type de donnée | Description |
|---|---|
| Number | Une valeur numérique, telle que 1 ou 5.5. |
| String | Une valeur textuelle, telle que "Hello" ou "The Hobbit". |
| Boolean | Une valeur qui s'évalue à true ou false. |
| Array | Une liste de valeurs, telle que ["red", "blue", "green"]. |
| Time |
Une valeur d'horodatage utilisée pour les comparaisons de date et d'heure. Lors du filtrage d'un attribut personnalisé de type temps imbriqué, vous pouvez choisir :
|
| Object | Une valeur structurée avec des paires clé–valeur, telle que {"author": "Tolkien"}. |
| Array of objects |
Une liste d'objets, telle que [{"title": "The Hobbit"}, {"title": "Dune"}].
Pour plus d'informations, consultez la section
Tableaux d'objets.
|
Considérations
- Les attributs personnalisés imbriqués sont destinés aux attributs personnalisés envoyés via le SDK ou l’API de Braze.
- Les objets ont une taille maximale de 100 Ko. Si une mise à jour fait dépasser cette limite de 100 Ko à l’objet, Braze ignore la mise à jour et l’attribut reste inchangé.
- Les noms de clés et les valeurs de chaîne de caractères sont limités à 255 caractères.
- Les noms de clés ne peuvent pas contenir d’espaces.
- Les points (
.) et les signes dollar ($) ne sont pas des caractères pris en charge dans un payload d’API si vous essayez d’envoyer un attribut personnalisé imbriqué vers un profil utilisateur. - Tous les partenaires de Braze ne prennent pas en charge les attributs personnalisés imbriqués. Consultez la documentation des partenaires pour vérifier si certaines intégrations de partenaires prennent en charge cette fonctionnalité.
- Les attributs personnalisés imbriqués ne peuvent pas être utilisés comme filtre lors d’un appel à l’API Connected Audience.
- Par défaut, le filtre de segmentation Attributs personnalisés imbriqués inclut les attributs personnalisés de type objet, les attributs de type tableau d’objets et les attributs personnalisés de type tableau. Lorsque vous sélectionnez un attribut, le sélecteur de schéma de propriété inclut les chemins de tableau (avec la notation
[]) pour les champs de tableau imbriqués. Pour masquer de ce filtre les attributs personnalisés de type tableau de premier niveau, contactez le support de Braze. - Lorsque vous prévisualisez des messages dans le tableau de bord à l’aide de l’option Prévisualiser en tant qu’utilisateur personnalisé, vous pouvez saisir des données fictives uniquement sous forme de chaîne de caractères ou de tableau de chaînes de caractères : les objets imbriqués ne sont pas pris en charge. Pour prévisualiser un message qui fait référence à des attributs personnalisés imbriqués, sélectionnez un utilisateur existant dont le profil contient déjà l’attribut imbriqué. Pour les propriétés d’événements personnalisés imbriquées, vous devez lancer une campagne en direct ciblant un utilisateur test afin de vérifier le rendu.
Exemple d’API
Voici un exemple /users/track avec un objet « Most Played Song ». Pour capturer les propriétés de la chanson, nous allons envoyer une requête API qui répertorie most_played_song en tant qu’objet, accompagné d’un ensemble de propriétés d’objet.
{
"attributes": [
{
"external_id": "user_id",
"most_played_song": {
"song_name": "Solea",
"artist_name": "Miles Davis",
"album_name": "Sketches of Spain",
"genre": "Jazz",
"play_analytics": {
"count": 1000,
"top_10_listeners": true
}
}
}
]
}
Pour mettre à jour un objet existant, envoyez une requête POST à users/track avec le paramètre _merge_objects dans la requête. Votre mise à jour sera alors fusionnée en profondeur avec les données existantes de l’objet. La fusion en profondeur garantit que tous les niveaux d’un objet sont fusionnés dans un autre objet, et pas seulement le premier niveau. Dans cet exemple, nous avons déjà un objet most_played_song dans Braze, et nous ajoutons maintenant un nouveau champ, year_released, à l’objet most_played_song.
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"most_played_song": {
"year_released": 1960
}
}
]
}
Une fois cette requête reçue, l’objet d’attribut personnalisé se présentera comme suit :
{"most_played_song": {
"song_name": "Solea",
"artist_name" : "Miles Davis",
"album_name": "Sketches of Spain",
"year_released": 1960,
"genre": "Jazz",
"play_analytics": {
"count": 1000,
"top_10_listeners": true
}
}}

Vous devez définir _merge_objects sur true, sinon vos objets seront écrasés. _merge_objects est défini sur false par défaut.
Pour supprimer un objet d’attribut personnalisé, envoyez une requête POST à users/track en définissant l’objet d’attribut personnalisé sur null.
{
"attributes": [
{
"external_id": "user_id",
"most_played_song": null
}
]
}

Cette approche ne peut pas être utilisée pour supprimer une clé imbriquée dans un tableau d’objets.
Exemple de SDK
Les exemples suivants montrent comment créer, mettre à jour par fusion et supprimer le même objet d’attribut personnalisé imbriqué (most_played_song) dans chaque SDK.
Créer
val json = JSONObject()
.put("song_name", "Solea")
.put("artist_name", "Miles Davis")
.put("album_name", "Sketches of Spain")
.put("genre", "Jazz")
.put(
"play_analytics",
JSONObject()
.put("count", 1000)
.put("top_10_listeners", true)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("most_played_song", json)
}
Mettre à jour
val json = JSONObject()
.put("year_released", 1960)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("most_played_song", json, true)
}
Supprimer
braze.getCurrentUser { user ->
user.unsetCustomUserAttribute("most_played_song")
}
Créer
let json: [String: Any?] = [
"song_name": "Solea",
"artist_name": "Miles Davis",
"album_name": "Sketches of Spain",
"genre": "Jazz",
"play_analytics": [
"count": 1000,
"top_10_listeners": true,
],
]
braze.user.setCustomAttribute(key: "most_played_song", dictionary: json)
Mettre à jour
let json: [String: Any?] = [
"year_released": 1960
]
braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)
Supprimer
braze.user.unsetCustomAttribute(key: "most_played_song")
Créer
import * as braze from "@braze/web-sdk";
const json = {
"song_name": "Solea",
"artist_name": "Miles Davis",
"album_name": "Sketches of Spain",
"genre": "Jazz",
"play_analytics": {
"count": 1000,
"top_10_listeners": true
}
};
braze.getUser().setCustomUserAttribute("most_played_song", json);
Mettre à jour
import * as braze from "@braze/web-sdk";
const json = {
"year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);
Supprimer
import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);
Créer
Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("song_name", "Solea");
attributes.Add("artist_name", "Miles Davis");
attributes.Add("album_name", "Sketches of Spain");
attributes.Add("genre", "Jazz");
Dictionary<string, object> playAnalytics = new Dictionary<string, object>();
playAnalytics.Add("count", 1000);
playAnalytics.Add("top_10_listeners", true);
attributes.Add("play_analytics", playAnalytics);
AppboyBinding.SetCustomUserAttribute("most_played_song", attributes);
Mettre à jour
Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("year_released", 1960);
AppboyBinding.SetCustomUserAttribute("most_played_song", attributes, true);
Supprimer
AppboyBinding.UnsetCustomUserAttribute("most_played_song");
Capturer des dates comme propriétés d’objet
Pour capturer des dates comme propriétés d’objet, vous devez utiliser la clé $time. Dans l’exemple suivant, un objet « Dates importantes » sert à capturer l’ensemble des propriétés d’objet birthday et wedding_anniversary. La valeur de ces dates est un objet avec une clé $time, qui ne peut pas être une valeur nulle.

Lorsque _merge_objects vaut true, une valeur null sans $time supprime un champ de date imbriqué existant de l’objet. Si le champ n’existe pas encore, Braze ignore la valeur null et ne crée pas le champ. Dans les deux cas, Braze ne renvoie aucune erreur.
Si vous n’avez pas capturé les dates comme propriétés d’objet dès le départ, nous vous recommandons de renvoyer ces données avec la clé $time pour tous les utilisateurs. Sinon, vous risquez d’obtenir des Segments incomplets lorsque vous utilisez l’attribut $time. Toutefois, si la valeur de $time dans un attribut personnalisé imbriqué n’est pas correctement formatée, l’ensemble de l’attribut personnalisé imbriqué ne sera pas mis à jour.
{
"attributes": [
{
"external_id": "time_with_nca_test",
"important_dates": {
"birthday": {"$time" : "1980-01-01"},
"wedding_anniversary": {"$time" : "2020-05-28"}
}
}
]
}

Pour les attributs personnalisés imbriqués, si l’année est inférieure à 0 ou supérieure à 3000, Braze ne stocke pas ces valeurs dans le profil de l’utilisateur.
Modèles Liquid
L’exemple de modèle Liquid suivant montre comment référencer les propriétés d’objet d’attribut personnalisé enregistrées lors de la requête API précédente et les utiliser dans vos messages.
Utilisez l’étiquette de personnalisation custom_attribute et la notation par points pour accéder aux propriétés d’un objet. Indiquez le nom de l’objet (et sa position dans le tableau si vous faites référence à un tableau d’objets), suivi d’un point, puis du nom de la propriété.
{{custom_attribute.${most_played_song}[0].artist_name}} — « Miles Davis »
{{custom_attribute.${most_played_song}[0].song_name}} — « Solea »
{{custom_attribute.${most_played_song}[0].play_analytics.count}} — « 1000 »
Pour utiliser du Liquid d’attribut personnalisé imbriqué dans votre message :
- Accédez à une Campaign ou à un Canvas, puis ouvrez l’étape de message dans laquelle vous souhaitez ajouter la personnalisation.
- Dans le compositeur de messages, insérez l’extrait de code Liquid à l’endroit où la valeur doit apparaître.
- Utilisez Aperçu et test avec un utilisateur existant dont le profil contient déjà l’attribut personnalisé imbriqué, pour vérifier que la valeur s’affiche comme prévu.
Personnalisation
Vous pouvez utiliser Ajouter une personnalisation pour insérer un attribut personnalisé imbriqué dans votre message.
Pour ouvrir Ajouter une personnalisation :
- Accédez à une Campaign ou à un Canvas, puis ouvrez l’étape de message dans laquelle vous souhaitez ajouter la personnalisation.
- Dans le compositeur de messages, sélectionnez Personnalisation pour ouvrir le panneau latéral Ajouter une personnalisation, dans lequel vous pouvez choisir les options de personnalisation.
Pour configurer la personnalisation d’un attribut personnalisé imbriqué :
- Dans Type de personnalisation, sélectionnez Attributs personnalisés imbriqués.
- Dans Attribut de niveau supérieur, sélectionnez le chemin de l’attribut personnalisé imbriqué que vous souhaitez insérer.
Par exemple, sélectionnez
preferences.neighborhood_office. - Facultatif : dans Valeur par défaut, saisissez une valeur de repli pour les utilisateurs qui n’ont pas leur propre valeur pour cet attribut.
- Vérifiez que l’extrait Liquid généré correspond bien au chemin attendu.
- Sélectionnez Insérer.
Dans cet exemple, Braze insère la valeur imbriquée de preferences.neighborhood_office dans votre message. Les valeurs par défaut sont des valeurs de repli que votre message inclut pour les utilisateurs qui n’ont pas leur propre valeur pour un attribut.

Si l’option permettant d’insérer des attributs personnalisés imbriqués n’apparaît pas, vérifiez qu’un schéma a bien été généré.
Générer et régénérer les schémas
Pour utiliser les attributs personnalisés imbriqués dans la segmentation et la personnalisation, vous devez générer un schéma pour l’attribut. Une fois qu’un schéma a été généré, vous pouvez le régénérer selon vos besoins. Pour des informations plus détaillées sur les schémas, consultez Générer un schéma à l’aide de l’explorateur d’objets imbriqués.
Générer un schéma
Après avoir créé un attribut personnalisé imbriqué et envoyé des données à Braze, vous pouvez générer le schéma :
- Accédez à Data Settings > Custom Attributes.
- Recherchez votre attribut personnalisé imbriqué.
- Dans la colonne Attribute Name correspondant à votre attribut, sélectionnez Generate Schema.
Une fois le schéma généré, l’icône se transforme en une icône plus que vous pouvez sélectionner pour afficher et gérer le schéma.
Régénérer un schéma
Pour régénérer le schéma de votre attribut personnalisé imbriqué :
- Accédez à Data Settings > Custom Attributes.
- Recherchez votre attribut personnalisé imbriqué.
- Dans la colonne Attribute Name correspondant à votre attribut, sélectionnez Manage schema pour gérer le schéma.
- Une fenêtre modale apparaîtra. Sélectionnez Regenerate Schema.
Vous ne pouvez pas lancer une autre régénération tant qu’une tâche de schéma est déjà en cours (l’option est indisponible tant que le statut est Generating). Une seule tâche de génération de schéma peut s’exécuter à la fois par entreprise. La régénération du schéma ne détecte que les nouveaux objets et ne supprime pas les objets qui existent déjà dans le schéma.

Pour réinitialiser le schéma d’un tableau d’objets avec un objet existant, vous devez créer un nouvel attribut personnalisé. La régénération du schéma ne supprime pas les objets existants.
Si les données n’apparaissent pas comme prévu après la régénération du schéma, il est possible que l’attribut ne soit pas ingéré assez fréquemment. Les données utilisateur sont échantillonnées à partir des données précédemment envoyées à Braze pour l’attribut imbriqué concerné. Si l’attribut n’est pas ingéré suffisamment, il ne sera pas pris en compte pour le schéma.
Déclencher des modifications d’attributs personnalisés imbriqués
Vous pouvez déclencher un message lorsqu’un objet d’attribut personnalisé imbriqué est modifié. Cette option n’est pas disponible pour les modifications apportées aux tableaux d’objets. Si l’option permettant d’afficher l’explorateur de chemins n’apparaît pas, vérifiez que vous avez bien généré un schéma.
Par exemple, dans une campagne par événement, vous pouvez ajouter une nouvelle action de déclenchement Modifier la valeur d’attribut personnalisé pour cibler les utilisateurs qui ont modifié leurs préférences de bureau de quartier.
Pour configurer ce déclencheur dans une campagne par événement :
- Créez ou modifiez une campagne, puis définissez le type de livraison sur Livraison par événement.
- Dans les paramètres de déclenchement, sélectionnez Modifier la valeur d’attribut personnalisé.
- Sélectionnez le chemin de l’attribut personnalisé imbriqué que vous souhaitez surveiller.
Par exemple, sélectionnez
preferences.neighborhood_office. - Sélectionnez la condition de déclenchement souhaitée, par exemple toute nouvelle valeur.
- Terminez la configuration du message et de l’audience de votre campagne, puis lancez la campagne.
Résolution des problèmes
Les valeurs d’attributs personnalisés imbriqués ne sont pas appliquées de façon cohérente
Si vous constatez que les valeurs d’attributs personnalisés imbriqués ne sont pas ajoutées de façon cohérente aux profils utilisateurs, le problème vient souvent d’une incohérence de type de données.
Pour diagnostiquer et résoudre ce problème :
- Comparez des exemples d’utilisateurs : Trouvez un profil utilisateur pour lequel l’attribut personnalisé imbriqué a bien été défini, et un autre pour lequel il aurait dû l’être mais ne l’a pas été.
- Examinez la structure des données : Consultez et comparez les valeurs d’attributs personnalisés des deux profils :
- Les propriétés sont-elles stockées dans un objet ?
- Les propriétés sont-elles stockées sous forme de tableau de propriétés ?
- Vérifiez le filtre de segmentation : Comparez la structure des données stockées avec la façon dont l’attribut personnalisé imbriqué est référencé dans vos filtres de segmentation.
- Vérifiez le type de données : Pour identifier le type de données d’un attribut personnalisé :
- Accédez à Paramètres des données > Attributs personnalisés.
- Recherchez l’attribut personnalisé de premier niveau qui contient l’attribut imbriqué à vérifier.
- Si la ligne affiche Générer un schéma, sélectionnez cette option pour générer d’abord le schéma.
- Une fois le schéma généré, sélectionnez l’icône plus dans la colonne Nom de l’attribut pour cet attribut.
- Dans la fenêtre modale Modifier le schéma, examinez les attributs imbriqués et leurs valeurs correspondantes dans la colonne Type de données.
Si le type de données ne correspond pas au format attendu d’un profil utilisateur à l’autre, supprimez la valeur mal formatée des profils utilisateurs concernés, puis renvoyez l’attribut au bon format à l’aide de la requête API ou de la méthode SDK appropriée.
Comportement de segmentation avec des tableaux d’objets
Lorsque vous utilisez plusieurs filtres Attribut personnalisé imbriqué combinés avec la logique AND pour segmenter sur un tableau d’objets, chaque filtre est évalué indépendamment sur l’ensemble des éléments du tableau. Un utilisateur entre dans le Segment si n’importe quel élément du tableau satisfait chaque filtre individuel. Les filtres n’ont pas besoin de correspondre au même élément.
Par exemple, supposons qu’un utilisateur possède le tableau suivant :
{
"orders": [
{"product": "Shoes", "price": 80},
{"product": "Hat", "price": 25}
]
}
Prenons un Segment avec les filtres AND suivants :
orders[].priceest supérieur à 50orders[].priceest inférieur à 30
Cet utilisateur serait éligible, car le premier filtre correspond à l’élément « Shoes » (80 > 50) et le second à l’élément « Hat » (25 < 30). Même si aucun élément ne satisfait à lui seul les deux conditions, l’utilisateur entre tout de même dans le Segment.
Si toutes les conditions doivent correspondre au même élément d’un tableau, utilisez la segmentation multicritères sur le même chemin, ou restructurez vos données pour éviter les correspondances entre éléments différents.
Points de données
Chaque clé envoyée consomme un point de donnée. Par exemple, cet objet initialisé dans le profil utilisateur compte pour sept (7) points de données :
{
"attributes": [
{
"external_id": "user_id",
"most_played_song": {
"song_name": "Solea",
"artist_name": "Miles Davis",
"album_name": "Sketches of Spain",
"year_released": 1960,
"genre": "Jazz",
"play_analytics": {
"count": 1000,
"top_10_listeners": true
}
}
}
]
}

La mise à jour d’un objet d’attribut personnalisé avec la valeur null consomme également un point de donnée.