Tableau d’objets
Cette page explique comment utiliser un tableau d’objets pour regrouper des attributs connexes. Vous pouvez, par exemple, avoir un groupe d’objets « animaux de compagnie », un groupe d’objets « chansons » et un groupe d’objets « compte » pour le même utilisateur. Ces tableaux d’objets peuvent être utilisés pour personnaliser vos messages avec Liquid, ou segmenter votre audience si un élément d’un objet correspond aux critères.
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 tableaux d’objets sont conçus pour les attributs personnalisés envoyés via l’API. Les téléchargements CSV ne sont pas pris en charge, car les virgules du fichier CSV sont interprétées comme des séparateurs de colonnes, et les virgules présentes dans les valeurs provoquent des erreurs d’analyse.
- Les tableaux d’objets n’ont pas de limite quant au nombre d’éléments, mais leur taille maximale est de 100 KB. Si une mise à jour (telle que
$addou$update) fait dépasser cette limite au tableau, Braze ignore la mise à jour et l’attribut reste inchangé. La requête API renvoie tout de même une réponse de succès. Pour que le tableau reste sous la limite et que vous puissiez y ajouter de nouveaux éléments, utilisez d’abord$removepour supprimer des éléments du tableau. - Les partenaires de Braze ne prennent pas tous en charge les tableaux d’objets. Consultez la documentation des partenaires pour vérifier si l’intégration prend en charge cette fonctionnalité.
Pour mettre à jour ou supprimer des éléments d’un tableau, vous devez identifier l’élément par sa clé et sa valeur. Pensez donc à inclure un identifiant unique pour chaque élément du tableau. Cette unicité ne s’applique qu’au tableau et s’avère utile si vous souhaitez mettre à jour ou supprimer des objets spécifiques de votre tableau. Braze ne l’impose pas.

Lorsqu’un attribut personnalisé imbriqué de votre requête contient des valeurs non valides (comme des formats d’heure non valides ou des valeurs null), Braze exclut du traitement toutes les mises à jour d’attributs personnalisés imbriqués de la requête. Cela s’applique à toutes les structures imbriquées de cet attribut spécifique. Vérifiez que toutes les valeurs des attributs personnalisés imbriqués sont valides avant l’envoi. Pour plus d’informations, consultez Créer et mettre à jour des utilisateurs.

Pour plus d’informations sur l’utilisation des tableaux d’objets dans les objets d’attributs utilisateur, consultez Objet d’attributs utilisateur.
Exemple d’API
Utilisez ces exemples lorsque vous envoyez des requêtes /users/track qui créent ou mettent à jour des attributs personnalisés imbriqués stockés sous forme de tableaux d’objets. Le payload utilise les opérateurs $add, $remove et $update pour modifier des objets précis sans reconstruire le tableau complet à chaque requête.
Voici un exemple de requête /users/track avec un tableau pets. Pour enregistrer les propriétés des animaux de compagnie, envoyez une requête API qui définit pets comme un tableau d’objets. Chaque objet reçoit un id unique, que vous pourrez référencer plus tard lors des mises à jour.
Utilisez ce format pour créer l’attribut pour la première fois ou pour remplacer l’ensemble du tableau par un nouveau jeu d’objets de référence.
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
Ajoutez un autre élément au tableau à l’aide de l’opérateur $add. L’exemple suivant ajoute trois nouveaux objets animaux au tableau pets de l’utilisateur.
Utilisez $add lorsque vous devez ajouter un ou plusieurs nouveaux objets en conservant les objets existants tels quels.
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$add": [
{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Biscuit"
},
{
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper"
},
{
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle"
}
]
}
}
]
}
Mettez à jour les valeurs d’objets précis au sein d’un tableau à l’aide du paramètre _merge_objects et de l’opérateur $update. Comme pour les mises à jour d’autres objets d’attributs personnalisés imbriqués, cette opération effectue une fusion profonde.
Notez que $update ne permet pas de supprimer une propriété imbriquée d’un objet situé dans un tableau. Pour cela, vous devez supprimer l’élément entier du tableau, puis ajouter à nouveau l’objet sans cette clé (en combinant $remove et $add).
Utilisez $update lorsque l’objet existe déjà et que vous souhaitez modifier un ou plusieurs champs en effectuant la correspondance sur $identifier_key et $identifier_value.
L’exemple suivant met à jour la propriété breed avec la valeur goldfish pour l’objet dont l’id est 4. Cette requête met également à jour l’objet dont l’id est égal à 5 avec un nouveau name, Annette. Comme le paramètre _merge_objects est défini sur true, tous les autres champs de ces deux objets restent inchangés.
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}

Vous devez définir _merge_objects sur true, sinon vos objets seront écrasés. Par défaut, _merge_objects est défini sur false.
Supprimez des objets d’un tableau à l’aide de l’opérateur $remove, associé à une clé ($identifier_key) et à une valeur ($identifier_value) de correspondance.
Utilisez $remove lorsque vous souhaitez supprimer tous les objets correspondant à une paire d’identifiants connue, comme id = 2 ou type = dog.
L’exemple suivant supprime du tableau pets tout objet dont l’id a la valeur 1, dont l’id a la valeur 2, ou dont le type a la valeur dog. Si plusieurs objets ont la valeur dog pour type, tous les objets correspondants sont supprimés.
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}
Ordre de traitement
Lorsqu’une même requête /users/track contient des opérations $add, $remove et $update portant sur le même attribut de type tableau, Braze les traite dans l’ordre suivant :
$add$remove$update
Cet ordre s’applique au sein d’un même objet de mise à jour d’attribut dans une requête, et détermine l’état final du tableau une fois toutes les opérations évaluées.
Comme $add est exécuté avant $remove, vous ne pouvez pas utiliser un $remove suivi d’un $add comme mécanisme d’upsert au sein d’une seule requête : le $add est traité en premier, puis le $remove supprime l’élément. Pour effectuer un upsert, envoyez le $remove dans une requête distincte, avant le $add.
Horodatages
Lorsque vous incluez des champs comme des horodatages dans un tableau d’objets, utilisez le format $time plutôt que de simples chaînes de caractères ou des entiers d’époque Unix.
{
"attributes": [
{
"external_id": "user123",
"purchases": [
{
"item_name": "T-shirt",
"price": 19.99,
"purchase_time": {
"$time": "2020-05-28"
}
}
]
}
]
}

Exemple de SDK
val json = JSONArray()
.put(JSONObject()
.put("id", 1)
.put("type", "dog")
.put("breed", "beagle")
.put("name", "Gus"))
.put(JSONObject()
.put("id", 2)
.put("type", "cat")
.put("breed", "calico")
.put("name", "Pixel")
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json)
}
val json = JSONObject()
.put("\$add", JSONArray()
.put(JSONObject()
.put("id", 3)
.put("type", "dog")
.put("breed", "corgi")
.put("name", "Doug"))
.put(JSONObject()
.put("id", 4)
.put("type", "fish")
.put("breed", "salmon")
.put("name", "Pepper"))
.put(JSONObject()
.put("id", 5)
.put("type", "bird")
.put("breed", "parakeet")
.put("name", "Noodle")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
val json = JSONObject()
.put("\$update", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 4)
.put("\$new_object", JSONObject()
.put("breed", "goldfish")
)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 5)
.put("\$new_object", JSONObject()
.put("name", "Annette")
)
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
val json = JSONObject()
.put("\$remove", JSONArray()
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 1)
)
.put(JSONObject()
.put("\$identifier_key", "id")
.put("\$identifier_value", 2)
)
.put(JSONObject()
.put("\$identifier_key", "type")
.put("\$identifier_value", "dog")
)
)
braze.getCurrentUser { user ->
user.setCustomUserAttribute("pets", json, true)
}
let json: [[String: Any?]] = [
[
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
],
[
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
]
]
braze.user.setCustomAttribute(key: "pets", array: json)
let json: [String: Any?] = [
"$add": [
[
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Biscuit"
],
[
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper"
],
[
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle"
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
let json: [String: Any?] = [
"$update": [
[
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": [
"breed": "goldfish"
]
],
[
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": [
"name": "Annette"
]
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)
let json: [String: Any?] = [
"$remove": [
[
"$identifier_key": "id",
"$identifier_value": 1,
],
[
"$identifier_key": "id",
"$identifier_value": 2,
],
[
"$identifier_key": "type",
"$identifier_value": "dog",
]
]
]
braze.user.setCustomAttribute(key: "pets", dictionary: json, merge: true)

Les attributs personnalisés imbriqués ne sont pas pris en charge par AppboyKit.
import * as braze from "@braze/web-sdk";
const json = [{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
}, {
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}];
braze.getUser().setCustomUserAttribute("pets", json);
import * as braze from "@braze/web-sdk";
const json = {
"$add": [{
"id": 3,
"type": "dog",
"breed": "corgi",
"name": "Doug",
}, {
"id": 4,
"type": "fish",
"breed": "salmon",
"name": "Pepper",
}, {
"id": 5,
"type": "bird",
"breed": "parakeet",
"name": "Noodle",
}]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
import * as braze from "@braze/web-sdk";
const json = {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
import * as braze from "@braze/web-sdk";
const json = {
"$remove": [
{
"$identifier_key": "id",
"$identifier_value": 1,
},
{
"$identifier_key": "id",
"$identifier_value": 2,
},
{
"$identifier_key": "type",
"$identifier_value": "dog",
}
]
};
braze.getUser().setCustomUserAttribute("pets", json, true);
Modèles Liquid
Vous pouvez utiliser ce tableau pets pour personnaliser un message. L’exemple de modèle Liquid suivant montre comment référencer les propriétés de l’objet d’attribut personnalisé enregistrées lors de la requête API précédente et les utiliser dans vos messages.
{% assign pets = {{custom_attribute.${pets}}} %}
{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}
Dans ce scénario, vous pouvez utiliser Liquid pour parcourir le tableau pets et afficher une phrase pour chaque animal. Attribuez une variable à l’attribut personnalisé pets et utilisez la notation par points pour accéder aux propriétés d’un objet. Indiquez le nom de l’objet, suivi d’un point ., puis du nom de la propriété.
Segmentation
Lorsque vous segmentez des utilisateurs en fonction de tableaux d’objets, un utilisateur est éligible pour le Segment si au moins un objet du tableau correspond aux critères.
Créez un nouveau Segment et sélectionnez Attribut personnalisé imbriqué comme filtre. Recherchez ensuite le nom de votre tableau d’objets, puis sélectionnez-le.

Utilisez la notation par points pour indiquer le champ du tableau d’objets que vous souhaitez utiliser. Commencez le champ de texte par une paire de crochets vides [] pour indiquer à Braze que vous recherchez à l’intérieur d’un tableau d’objets. Ajoutez ensuite un point ., suivi du nom du champ à utiliser.
Par exemple, pour filtrer un tableau d’objets top_3_movies en fonction du champ type, saisissez [].type et choisissez les films à filtrer, comme Fantasy Movie.
Niveaux d’imbrication
Vous pouvez créer un Segment comportant jusqu’à un niveau d’imbrication de tableaux (un tableau dans un autre tableau). Par exemple, avec les attributs suivants, vous pouvez créer un Segment pour pets[].name contient Mochi, mais pas pour pets[].nicknames[] contient Gugu.
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi",
"nicknames": [
"MoMo",
"Mochi"
]
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel",
"nicknames": [
"PiPi",
"Pixel"
]
}
]
}
]
}
Points de données
Les points de données sont enregistrés différemment selon que vous créez, mettez à jour ou supprimez une propriété.
La création d’un nouveau tableau enregistre un point de donnée pour chaque attribut d’un objet. Cet exemple coûte huit points de données : chaque objet animal possède quatre attributs et il y a deux objets.
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
La mise à jour d’un tableau existant enregistre un point de donnée pour chaque propriété ajoutée. Cet exemple coûte deux points de données, car il ne met à jour qu’une seule propriété dans chacun des deux objets.
{
"attributes": [
{
"external_id": "user_id",
"_merge_objects": true,
"pets": {
"$update": [
{
"$identifier_key": "id",
"$identifier_value": 4,
"$new_object": {
"breed": "goldfish"
}
},
{
"$identifier_key": "id",
"$identifier_value": 5,
"$new_object": {
"name": "Annette"
}
}
]
}
}
]
}
La suppression d’un objet dans un tableau enregistre un point de donnée pour chaque critère de suppression que vous envoyez. Cet exemple coûte trois points de données, même si cette instruction peut supprimer plusieurs chiens.
{
"attributes": [
{
"external_id": "user_id",
"pets": {
"$remove": [
// Remove by ID
{
"$identifier_key": "id",
"$identifier_value": 1
},
{
"$identifier_key": "id",
"$identifier_value": 2
},
// Remove any dog
{
"$identifier_key": "type",
"$identifier_value": "dog"
}
]
}
}
]
}