Skip to content

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 votre envoi de messages avec Liquid, ou segmenter votre audience si un élément d’un objet correspond aux critères.

Types de données prises en charge

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

Restrictions

  • Les tableaux d’objets sont destinés aux attributs personnalisés envoyés par l’API. Les téléchargements de fichiers CSV ne sont pas pris en charge, car les virgules dans le fichier CSV sont interprétées comme des séparateurs de colonnes, et les virgules 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 Ko.
  • Tous les partenaires de Braze ne prennent pas en charge les tableaux d’objets. Consultez la documentation du partenaire pour savoir si l’intégration prend en charge cette fonctionnalité.

La mise à jour ou la suppression d’éléments d’un tableau nécessite l’identification de l’élément par sa clé et sa valeur ; pensez donc à inclure un identifiant unique pour chaque élément du tableau. L’unicité s’applique uniquement au tableau et est utile si vous souhaitez mettre à jour ou supprimer des objets spécifiques dans votre tableau. Braze n’impose pas l’utilisation de tels identifiants uniques.

Exemple d’API

Voici un exemple /users/track avec un tableau pets. Pour capturer les propriétés des animaux domestiques, envoyez une requête API qui répertorie pets en tant que tableau d’objets. Notez que chaque objet a reçu un id unique qui peut être utilisé plus tard lors des mises à jour.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald"
        }
      ]
    }
  ]
}

Ajoutez un autre élément au tableau en utilisant l’opérateur $add. L’exemple suivant montre l’ajout de trois objets animaux de compagnie supplémentaires dans le tableau pets de l’utilisateur.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": {
        "$add": [
          {
            "id": 3,
            "type": "dog",
            "breed": "corgi",
            "name": "Doug"
          },
          {
            "id": 4,
            "type": "fish",
            "breed": "salmon",
            "name": "Larry"
          },
           {
            "id": 5,
            "type": "bird",
            "breed": "parakeet",
            "name": "Mary"
          }
        ]
      }
    }
  ]
}

Mettez à jour les valeurs pour des objets spécifiques dans un tableau en utilisant le paramètre _merge_objects et l’opérateur $update. Cela effectue une fusion profonde (deep merge), comme pour les mises à jour d’objets d’attributs personnalisés imbriqués simples.

Notez que $update ne peut pas être utilisé pour supprimer une propriété imbriquée d’un objet à l’intérieur d’un tableau. Pour ce faire, vous devez supprimer l’élément entier du tableau, puis ajouter l’objet sans cette clé spécifique (en utilisant une combinaison de $remove et $add).

L’exemple suivant montre la mise à jour de la propriété breed sur goldfish pour l’objet avec un id de 4. Cet exemple de requête met également à jour l’objet avec id égal à 5 avec un nouveau name de Annette. Comme le paramètre _merge_objects est défini sur true, tous les autres champs de ces deux objets restent les mêmes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

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

Supprimez des objets d’un tableau en utilisant l’opérateur $remove en combinaison avec une clé ($identifier_key) et une valeur ($identifier_value) correspondantes.

L’exemple suivant montre la suppression de tout objet dans le tableau pets qui a un id avec une valeur de 1, un id avec une valeur de 2, et un type avec une valeur de dog. S’il y a plusieurs objets avec une valeur type égale à dog, tous les objets correspondants seront supprimés.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "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 seule requête /users/track inclut des opérations $add, $remove et $update pour le même attribut de tableau, Braze les traite dans cet ordre :

  1. $add
  2. $remove
  3. $update

Étant donné que $add s’exécute avant $remove, il n’est pas possible d’utiliser un $remove suivi d’un $add comme mécanisme d’upsert dans 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 tels que des horodatages dans un tableau d’objets, utilisez le format $time au lieu de chaînes de caractères simples ou d’entiers unix epoch.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "attributes": [
    {
      "external_id": "user123",
      "purchases": [
        {
          "item_name": "T-shirt",
          "price": 19.99,
          "purchase_time": {
            "$time": "2020-05-28"
          }
        }
      ]
    }
  ]
}

Exemple de SDK

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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", "Gerald")
    )

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

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", "Larry"))
        .put(JSONObject()
            .put("id", 5)
            .put("type", "bird")
            .put("breed", "parakeet")
            .put("name", "Mary")
        )
    )

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

let json: [[String: Any?]] = [
  [
    "id": 1,
    "type": "dog",
    "breed": "beagle",
    "name": "Gus"
  ],
  [
    "id": 2,
    "type": "cat",
    "breed": "calico",
    "name": "Gerald"
  ]
]

braze.user.setCustomAttribute(key: "pets", array: json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

let json: [String: Any?] = [
  "$add": [
    [
      "id": 3,
      "type": "dog",
      "breed": "corgi",
      "name": "Doug"
    ],
    [
      "id": 4,
      "type": "fish",
      "breed": "salmon",
      "name": "Larry"
    ],
    [
      "id": 5,
      "type": "bird",
      "breed": "parakeet",
      "name": "Mary"
    ]
  ]
]

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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)

1
2
3
4
5
6
7
8
9
10
11
12
13

import * as braze from "@braze/web-sdk";
const json = [{
  "id": 1,
  "type": "dog",
  "breed": "beagle",
  "name": "Gus"
}, {
  "id": 2,
  "type": "cat",
  "breed": "calico",
  "name": "Gerald"
}];
braze.getUser().setCustomUserAttribute("pets", json);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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":  "Larry",
  }, {
    "id":  5,
    "type":  "bird",
    "breed":  "parakeet",
    "name":  "Mary",
  }]
};
braze.getUser().setCustomUserAttribute("pets", json, true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

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);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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. Les exemples de templating Liquid suivants montrent comment référencer les propriétés d’objet d’attribut personnalisé enregistrées via la requête API précédente et les utiliser dans vos communications.

1
2
3
4
5

{% 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 de compagnie. Attribuez une variable à l’attribut personnalisé pets et utilisez la notation par points pour accéder aux propriétés d’un objet. Spécifiez le nom de l’objet, suivi d’un point ., suivi du nom de la propriété.

Segmentation

Lorsque vous segmentez des utilisateurs en fonction d’un tableau d’objets, un utilisateur sera admissible pour le segment si un objet du tableau correspond aux critères.

Créez un nouveau segment et sélectionnez Nested Custom Attribute comme filtre. Recherchez et sélectionnez le nom de votre tableau d’objets.

Filtre sur un tableau d'objets.

Utilisez la notation par points pour spécifier le champ du tableau d’objets que vous souhaitez utiliser. Commencez le champ de texte par deux crochets vides [] pour indiquer à Braze que vous recherchez dans un tableau d’objets. Ensuite, ajoutez un point ., suivi du nom du champ que vous souhaitez utiliser.

Par exemple, si vous souhaitez filtrer un tableau d’objets top_3_movies en fonction du champ type, entrez [].type et choisissez les films à filtrer, comme Fantasy Movie.

Niveaux d’imbrication

Vous pouvez créer un segment avec un tableau imbriqué dans un autre tableau (jusqu’à un niveau d’imbrication). Par exemple, compte tenu des attributs suivants, vous pouvez créer un segment pour lequel pets[].name contient Gus, mais vous ne pouvez pas créer un segment pour lequel pets[].nicknames[] contient Gugu.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus",
          "nicknames": [
            "Gugu",
            "Gusto"
          ]
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald",
          "nicknames": [
            "GeGe",
            "Gerry"
          ]
        }
      ]
    }
  ]
}

Points de données

Les points de données sont comptabilisé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 de compagnie possède quatre attributs et il y a deux objets.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

{
  "attributes": [
    {
      "external_id": "user_id",
      "pets": [
        {
          "id": 1,
          "type": "dog",
          "breed": "beagle",
          "name": "Gus"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald"
        }
      ]
    }
  ]
}

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 met uniquement à jour une propriété dans chacun des deux objets.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "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 d’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 vous pouvez supprimer plusieurs chiens avec cette requête.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{
  "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"
          }
        ]
      }
    }
  ]
}
Github   Modifier cette page sur GitHub
New Stuff!