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 les 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 être utilisé pour cibler les utilisateurs par auteur, filtrer par date de publication ou insérer le titre du livre directement dans un message :

1
2
3
4
5
"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

Types de données prises en charge

Les types de données suivants sont pris en charge :

Restrictions

• 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.
• Les noms de clé et les valeurs de chaîne de caractères ont une limite de taille de 255 caractères.
• Les noms de clé ne peuvent pas contenir d’espaces.
• Les points (.) et les signes de dollar ($) ne sont pas des caractères pris en charge dans un PAYLOAD API si vous tentez d’envoyer un attribut personnalisé imbriqué à un profil utilisateur.
• Tous les partenaires Braze ne prennent pas en charge les attributs personnalisés imbriqués. Reportez-vous à la documentation du partenaire pour savoir si les intégrations spécifiques du partenaire 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.

Exemple d’API

• create
• update
• delete

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "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
        }
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "most_played_song": {
          "year_released": 1960
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
{"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
  }
}}

1
2
3
4
5
6
7
8
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

Exemple de SDK

• android sdk
• swift sdk
• web sdk

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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)
}

1
2
3
4
5
6
val json = JSONObject()
    .put("year_released", 1960)

braze.getCurrentUser { user ->
    user.setCustomUserAttribute("most_played_song", json, true)
}

1
2
3
braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

1
2
3
4
5
6
7
8
9
10
11
12
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)

1
2
3
4
5
let json: [String: Any?] = [
  "year_released": 1960
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json, merge: true)

1
braze.user.unsetCustomAttribute(key: "most_played_song")

1
2
3
4
5
6
7
8
9
10
11
12
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);

1
2
3
4
5
6
import * as braze from "@braze/web-sdk";
const json = {
  "year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);

1
2
import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

Capturer des dates en tant que propriétés d’objet

Pour capturer des dates en tant que propriétés d’objet, vous devez utiliser la clé $time. Dans l’exemple suivant, un objet « Dates importantes » est utilisé pour 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.

1
2
3
4
5
6
7
8
9
10
11
{
  "attributes": [ 
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

Modèles Liquid

Les exemples de modèles Liquid suivants montrent comment référencer les propriétés d’objet d’attribut personnalisé enregistrées à partir de la requête API précédente et les utiliser dans vos messages.

Utilisez la balise de personnalisation custom_attribute et la notation par points pour accéder aux propriétés d’un objet. Spécifiez le nom de l’objet (et la position dans le tableau si vous référencez un tableau d’objets), suivi d’un point, suivi 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”

Segmentation

Vous pouvez créer des segments basés sur des attributs personnalisés imbriqués pour cibler encore plus précisément vos utilisateurs. Pour ce faire, filtrez votre segment en fonction de l’objet d’attribut personnalisé, puis spécifiez le chemin vers le nom de la propriété et la valeur associée sur lesquels vous souhaitez segmenter. Si vous ne savez pas à quoi ressemble ce chemin, vous pouvez générer un schéma et utiliser l’explorateur d’objets imbriqués pour que Braze remplisse ce chemin pour vous.

Après avoir ajouté un chemin vers votre propriété, sélectionnez Valider pour vérifier que la valeur du champ chemin est valide.

Pour segmenter avec des attributs personnalisés imbriqués, sélectionnez le filtre Attributs personnalisés imbriqués pour afficher une liste déroulante dans laquelle vous pouvez sélectionner un attribut personnalisé imbriqué spécifique.

Lorsque vous travaillez avec la segmentation d’attributs personnalisés imbriqués, vous avez accès à un nouveau comparateur regroupé par type de données. Par exemple, comme play_analytics.count est un nombre, vous pouvez sélectionner un comparateur dans la catégorie Nombre.

Filtrage des types de données temporelles

Lorsque vous filtrez un attribut personnalisé temporel imbriqué, vous pouvez choisir de filtrer avec des opérateurs dans les catégories Jour de l’année ou Heure lors de la comparaison de la valeur de la date.

Si vous sélectionnez un opérateur dans la catégorie Jour de l’année, seuls le mois et le jour seront vérifiés pour la comparaison, au lieu de l’horodatage complet de la valeur de l’attribut personnalisé imbriqué. La sélection d’un opérateur dans la catégorie Heure permet de comparer l’horodatage complet, y compris l’année.

Segmentation multicritères

Utilisez la segmentation multicritères pour créer un segment correspondant à plusieurs critères au sein d’un même objet. L’utilisateur est qualifié pour le segment s’il possède au moins un tableau d’objets correspondant à tous les critères définis. Par exemple, les utilisateurs ne correspondront à ce segment que si leur clé n’est pas vide et que leur nombre est supérieur à 0.

Vous pouvez également utiliser la fonctionnalité Copier le Liquid pour le segment pour générer du code Liquid pour ce segment et l’utiliser dans un message. Par exemple, supposons que vous ayez un tableau d’objets de comptes et un segment qui cible les clients avec des comptes imposables actifs. Pour inciter les clients à contribuer à l’objectif du compte associé à l’un de leurs comptes actifs et imposables, vous devrez créer un message pour les encourager.

Lorsque vous sélectionnez Copier le Liquid pour le segment, Braze génère automatiquement du code Liquid qui renvoie un tableau d’objets ne contenant que des comptes actifs et imposables.

1
2
3
4
5
6
7
{% assign segmented_nested_objects = '' | split: '' %}
{% assign obj_array = {{custom_attribute.${accounts}}} %}
{% for obj in obj_array %}
  {% if obj["account_type"] == 'taxable' and obj["active"] == true %}
    {% assign segmented_nested_objects = obj_array | slice: forloop.index0 | concat: segmented_nested_objects | reverse %}
  {% endif %}
{% endfor %}

À partir de là, vous pouvez utiliser segmented_nested_objects et personnaliser votre message. Dans cet exemple, nous voulons récupérer un objectif du premier compte imposable actif et le personnaliser :

1
Get to your {{segmented_nested_objects[0].goal}} goal faster, make a deposit using our new fast deposit feature!

Ceci renvoie le message suivant à votre client : « Atteignez votre objectif de retraite plus rapidement, effectuez un dépôt grâce à notre nouvelle fonctionnalité de dépôt rapide ! »

Générer un schéma à l’aide de l’explorateur d’objets imbriqués

Vous pouvez générer un schéma pour vos objets afin de créer des filtres de segment sans avoir besoin de mémoriser les chemins des objets imbriqués. Pour cela, suivez les étapes ci-dessous.

Étape 1 : Générer un schéma

Dans cet exemple, supposons que nous avons un tableau d’objets accounts que nous venons d’envoyer à Braze :

1
2
3
4
5
6
7
8
{"accounts": [
  {"type": "taxable",
  "balance": 22500,
  "active": true},
  {"type": "non-taxable",
  "balance": 0,
  "active": true}
]}

Dans le tableau de bord de Braze, accédez à Paramètres des données > Attributs personnalisés.

Recherchez votre objet ou votre tableau d’objets. Dans la colonne Nom de l’attribut, sélectionnez Générer un schéma.

Une fois le schéma généré, un nouveau bouton plus apparaît à la place du bouton Générer un schéma. Vous pouvez cliquer dessus pour voir ce que Braze sait sur cet attribut personnalisé imbriqué.

Pendant la génération du schéma, Braze examine les données envoyées précédemment et crée une représentation idéale de vos données pour cet attribut. Braze analyse également vos valeurs imbriquées et leur attribue un type de données, en échantillonnant les données précédemment envoyées pour l’attribut imbriqué donné.

Pour notre tableau d’objets accounts, vous pouvez voir que dans le tableau d’objets, un objet contient les éléments suivants :

• Une valeur booléenne avec une clé active (indépendamment du fait que le compte soit actif ou non)
• Un type nombre avec une clé balance (solde du compte)
• Un type chaîne de caractères avec une clé type (compte imposable ou non imposable)

Maintenant que nous avons analysé et créé une représentation des données, créons un segment.

Étape 2 : Créer un segment

Ciblons les clients qui ont un solde inférieur à 100 pour leur envoyer un message les encourageant à effectuer un dépôt.

Créez un segment et ajoutez le filtre Nested Custom Attribute, puis recherchez et sélectionnez votre objet ou votre tableau d’objets. Ici, nous avons ajouté le tableau d’objets accounts.

Sélectionnez le bouton plus dans le champ du chemin. Cela affichera une représentation de votre objet ou de votre tableau d’objets. Vous pouvez sélectionner n’importe lequel des éléments répertoriés et Braze les insérera dans le champ du chemin pour vous. Dans cet exemple, nous devons obtenir le solde. Sélectionnez le solde et le chemin (dans ce cas, [].balance) est automatiquement renseigné dans le champ du chemin.

Vous pouvez sélectionner Valider pour vérifier que le contenu du champ chemin est valide, puis créer le reste du filtre selon vos besoins. Ici, nous avons indiqué que le solde doit être inférieur à 100.

Et voilà ! Vous venez de créer un segment à l’aide d’un attribut personnalisé imbriqué, sans avoir besoin de connaître la structure des données. L’explorateur d’objets imbriqués de Braze a généré une représentation visuelle de vos données et vous a permis d’explorer et de sélectionner exactement ce dont vous aviez besoin pour créer un segment.

Déclencher des modifications d’attributs personnalisés imbriqués

Vous pouvez déclencher une action 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 vous ne voyez pas l’option pour afficher l’explorateur de chemin, vérifiez que vous avez généré un schéma.

Par exemple, dans la campagne par action suivante, vous pouvez ajouter une nouvelle action de déclenchement pour Modifier la valeur de l’attribut personnalisé afin de cibler les utilisateurs qui ont modifié leurs préférences de bureau de quartier.

Personnalisation

Grâce à la fenêtre modale Ajouter une personnalisation, vous pouvez également insérer des attributs personnalisés imbriqués dans vos messages. Sélectionnez Attributs personnalisés imbriqués comme type de personnalisation. Ensuite, sélectionnez l’attribut de niveau supérieur et la clé d’attribut.

Par exemple, dans la fenêtre modale de personnalisation ci-dessous, cela insère l’attribut personnalisé imbriqué d’un bureau de quartier local basé sur les préférences d’un utilisateur.

Régénérer un schéma

Après qu’un schéma a été généré, il peut être régénéré toutes les 24 heures. Cette section décrit comment régénérer votre schéma. Pour plus d’informations sur les schémas, reportez-vous à la section de cet article consacrée à la génération d’un schéma.

Pour régénérer le schéma de votre attribut personnalisé imbriqué :

1. Accédez à Paramètres des données > Attributs personnalisés.
2. Recherchez votre attribut personnalisé imbriqué.
3. Dans la colonne Nom de l’attribut, sélectionnez pour gérer le schéma.
4. Une fenêtre modale apparaît. Sélectionnez Régénérer le schéma.

L’option de régénération du schéma sera désactivée s’il s’est écoulé moins de 24 heures depuis la dernière régénération. La régénération du schéma ne détectera que les nouveaux objets et ne supprimera 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 se peut que l’attribut ne soit pas ingéré assez souvent. Les données utilisateur sont échantillonnées à partir des données précédemment envoyées à Braze pour l’attribut imbriqué donné. Si l’attribut n’est pas suffisamment ingéré, il ne sera pas pris en compte dans le schéma.

Comportement de la segmentation avec les tableaux d’objets

Lorsque vous utilisez plusieurs filtres Nested Custom Attribute avec une logique ET pour segmenter sur un tableau d’objets, chaque filtre est évalué indépendamment sur l’ensemble des éléments du tableau. Un utilisateur est qualifié pour 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 :

1
2
3
4
5
6
{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

Un segment avec les filtres ET suivants :

• orders[].price est supérieur à 50
• orders[].price est inférieur à 30

Cet utilisateur serait qualifié car le premier filtre correspond à l’élément « Shoes » (80 > 50) et le second filtre correspond à l’élément « Hat » (25 < 30). Même si aucun élément unique ne satisfait les deux conditions, l’utilisateur entre tout de même dans le segment.

Si vous avez besoin que toutes les conditions correspondent au même élément dans un tableau, utilisez la segmentation multicritères sur le même chemin, ou restructurez vos données pour éviter la correspondance inter-éléments.

Points de données

Toute clé envoyée consomme un point de donnée. Par exemple, cet objet initialisé dans le profil utilisateur consomme sept (7) points de données :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "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
        }
      }
    }
  ]
}