Passer au contenu

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 :

  • Day of Year : ne vérifie que le mois et le jour à des fins de comparaison, par exemple 03-15.
  • Time : compare l'horodatage complet, y compris l'année, par exemple 2023-03-15T12:00:00Z.
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
  }
}}

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
    }
  ]
}

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.

{
  "attributes": [
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

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 :

  1. Accédez à une Campaign ou à un Canvas, puis ouvrez l’étape de message dans laquelle vous souhaitez ajouter la personnalisation.
  2. Dans le compositeur de messages, insérez l’extrait de code Liquid à l’endroit où la valeur doit apparaître.
  3. 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 :

  1. Accédez à une Campaign ou à un Canvas, puis ouvrez l’étape de message dans laquelle vous souhaitez ajouter la personnalisation.
  2. 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é :

  1. Dans Type de personnalisation, sélectionnez Attributs personnalisés imbriqués.
  2. 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.
  3. Facultatif : dans Valeur par défaut, saisissez une valeur de repli pour les utilisateurs qui n’ont pas leur propre valeur pour cet attribut.
  4. Vérifiez que l’extrait Liquid généré correspond bien au chemin attendu.
  5. 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.

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 :

  1. Accédez à Data Settings > Custom Attributes.
  2. Recherchez votre attribut personnalisé imbriqué.
  3. 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é :

  1. Accédez à Data Settings > Custom Attributes.
  2. Recherchez votre attribut personnalisé imbriqué.
  3. Dans la colonne Attribute Name correspondant à votre attribut, sélectionnez Manage schema pour gérer le schéma.
  4. 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.

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 :

  1. Créez ou modifiez une campagne, puis définissez le type de livraison sur Livraison par événement.
  2. Dans les paramètres de déclenchement, sélectionnez Modifier la valeur d’attribut personnalisé.
  3. Sélectionnez le chemin de l’attribut personnalisé imbriqué que vous souhaitez surveiller. Par exemple, sélectionnez preferences.neighborhood_office.
  4. Sélectionnez la condition de déclenchement souhaitée, par exemple toute nouvelle valeur.
  5. 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 :

  1. 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é.
  2. 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 ?
  3. 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.
  4. 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[].price est supérieur à 50
  • orders[].price est 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
        }
      }
    }
  ]
}
New Stuff!