Conjunto de objetos
Esta página explica cómo utilizar un conjunto de objetos para agrupar atributos relacionados. Por ejemplo, puedes tener un grupo de objetos mascota, objetos canción y objetos cuenta que pertenezcan todos a un usuario. Estos conjuntos de objetos pueden utilizarse para personalizar tus mensajes con Liquid, o crear segmentos de audiencia si algún elemento de un objeto coincide con los criterios.
Tipos de datos admitidos
Se admiten los siguientes tipos de datos:
| Tipo de datos | Descripción |
|---|---|
| Número | Un valor numérico, como 1 o 5.5. |
| Cadena | Un valor de texto, como "Hello" o "The Hobbit". |
| Booleano | Un valor que se evalúa como true o false. |
| Matriz | Una lista de valores, como ["red", "blue", "green"]. |
| Tiempo |
Un valor de marca de tiempo utilizado para comparaciones de fecha y hora. Al filtrar un atributo personalizado anidado de tiempo, puedes elegir:
|
| Objeto | Un valor estructurado con pares clave-valor, como {"author": "Tolkien"}. |
| Matriz de objetos |
Una lista de objetos, como [{"title": "The Hobbit"}, {"title": "Dune"}].
Para más información, consulta
Matrices de objetos.
|
Consideraciones
- Las matrices de objetos están pensadas para atributos personalizados enviados a través de la API. No se admiten cargas de archivos CSV. Esto se debe a que las comas del archivo CSV se interpretarán como separadores de columnas, y las comas en los valores provocarán errores de análisis.
- Las matrices de objetos no tienen límite en el número de elementos, pero sí tienen un tamaño máximo de 100 KB. Si una actualización (como
$addo$update) hace que la matriz supere este límite, Braze descarta la actualización y el atributo no cambia. La solicitud a la API sigue devolviendo una respuesta correcta. Para mantener la matriz por debajo del límite y poder añadir nuevos elementos, usa primero$removepara eliminar elementos de la matriz. - No todos los partners de Braze admiten matrices de objetos. Consulta la documentación de partners para confirmar si la integración admite esta característica.
Para actualizar o eliminar elementos de una matriz, es necesario identificar el elemento por clave y valor, así que considera incluir un identificador único para cada elemento de la matriz. La unicidad se limita solo a la matriz y resulta útil si quieres actualizar y eliminar objetos específicos de tu matriz. Braze no aplica esta restricción.

Cuando un atributo personalizado anidado de tu solicitud contiene algún valor no válido (como formatos de hora no válidos o valores null), Braze descarta del procesamiento todas las actualizaciones de atributos personalizados anidados de la solicitud. Esto se aplica a todas las estructuras anidadas dentro de ese atributo concreto. Comprueba que todos los valores de los atributos personalizados anidados sean válidos antes de enviarlos. Para más información, consulta Crear y actualizar usuarios.

Para más información sobre el uso de matrices de objetos en los objetos de atributos de usuario, consulta Objeto de atributos de usuario.
Ejemplo de API
Usa estos ejemplos cuando envíes solicitudes a /users/track que creen o actualicen atributos personalizados anidados almacenados como matrices de objetos. La carga útil utiliza los operadores $add, $remove y $update para que puedas cambiar objetos concretos sin tener que reconstruir la matriz completa en cada solicitud.
A continuación se muestra un ejemplo de /users/track con una matriz pets. Para capturar las propiedades de las mascotas, envía una solicitud a la API que incluya pets como una matriz de objetos. Ten en cuenta que a cada objeto se le ha asignado un id único al que se puede hacer referencia más adelante al realizar actualizaciones.
Usa este formato cuando quieras crear el atributo por primera vez o sustituir toda la matriz por un nuevo conjunto base de objetos.
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
Añade otro elemento a la matriz con el operador $add. El siguiente ejemplo muestra cómo añadir tres objetos de mascota más a la matriz pets del usuario.
Usa $add cuando necesites añadir uno o varios objetos nuevos y mantener sin cambios los objetos existentes.
{
"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"
}
]
}
}
]
}
Actualiza los valores de objetos concretos dentro de una matriz con el parámetro _merge_objects y el operador $update. Al igual que ocurre con las actualizaciones de otros objetos de atributos personalizados anidados, se realiza una fusión profunda.
Ten en cuenta que $update no se puede utilizar para eliminar una propiedad anidada de un objeto dentro de una matriz. Para ello, tendrás que eliminar todo el elemento de la matriz y luego añadir el objeto sin esa clave concreta (combinando $remove y $add).
Usa $update cuando el objeto ya exista y quieras cambiar uno o varios campos buscando coincidencias por $identifier_key y $identifier_value.
El siguiente ejemplo muestra cómo actualizar la propiedad breed a goldfish en el objeto con un id de 4. Esta solicitud de ejemplo también actualiza el objeto con id igual a 5 con un nuevo name de Annette. Como el parámetro _merge_objects está configurado en true, todos los demás campos de estos dos objetos permanecen igual.
{
"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"
}
}
]
}
}
]
}

Debes configurar _merge_objects en true o tus objetos se sobrescribirán. _merge_objects es false de forma predeterminada.
Elimina objetos de una matriz con el operador $remove en combinación con una clave ($identifier_key) y un valor ($identifier_value) coincidentes.
Usa $remove cuando quieras eliminar todos los objetos que coincidan con un par de identificadores conocido, como id = 2 o type = dog.
El siguiente ejemplo muestra cómo eliminar de la matriz pets cualquier objeto que tenga un id con valor 1, un id con valor 2 y un type con valor dog. Si hay varios objetos con el valor dog en type, se eliminarán todos los objetos coincidentes.
{
"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"
}
]
}
}
]
}
Orden de procesamiento
Cuando una misma solicitud a /users/track incluye operaciones $add, $remove y $update para el mismo atributo de matriz, Braze las procesa en este orden:
$add$remove$update
Este orden se aplica dentro de un mismo objeto de actualización de atributos en una solicitud y determina el estado final de la matriz después de evaluar todas las operaciones.
Como $add se ejecuta antes que $remove, no puedes usar un $remove seguido de un $add como mecanismo de upsert dentro de una misma solicitud. Primero se procesa $add y después $remove elimina el elemento. Para hacer un upsert, envía el $remove en una solicitud independiente antes del $add.
Marcas de tiempo
Cuando incluyas campos como marcas de tiempo en una matriz de objetos, usa el formato $time en lugar de cadenas simples o enteros de época Unix.
{
"attributes": [
{
"external_id": "user123",
"purchases": [
{
"item_name": "T-shirt",
"price": 19.99,
"purchase_time": {
"$time": "2020-05-28"
}
}
]
}
]
}

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

Los atributos personalizados anidados no son compatibles con 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);
Plantillas de Liquid
Puedes usar esta matriz pets para personalizar un mensaje. El siguiente ejemplo de plantilla de Liquid muestra cómo hacer referencia a las propiedades del objeto de atributo personalizado guardadas en la solicitud a la API anterior y cómo usarlas en tu mensajería.
{% assign pets = {{custom_attribute.${pets}}} %}
{% for pet in pets %}
I have a {{pet.type}} named {{pet.name}}! They are a {{pet.breed}}.
{% endfor %}
En este caso, puedes usar Liquid para recorrer la matriz pets e imprimir una frase para cada mascota. Asigna una variable al atributo personalizado pets y usa la notación de puntos para acceder a las propiedades de un objeto. Especifica el nombre del objeto, seguido de un punto . y, a continuación, el nombre de la propiedad.
Segmentación
Al segmentar usuarios basándote en matrices de objetos, un usuario cumplirá los requisitos para el Segment si algún objeto de la matriz coincide con los criterios.
Crea un nuevo Segment y selecciona Atributo personalizado anidado como filtro. A continuación, busca y selecciona el nombre de tu matriz de objetos.

Utiliza la notación de puntos para especificar qué campo de la matriz de objetos quieres utilizar. Empieza el campo de texto con un par de corchetes vacíos [] para indicar a Braze que estás buscando dentro de una matriz de objetos. Después, añade un punto ., seguido del nombre del campo que quieres utilizar.
Por ejemplo, si quieres filtrar una matriz de objetos top_3_movies en función del campo type, introduce [].type y elige las películas por las que filtrar, como Fantasy Movie.
Niveles de anidamiento
Puedes crear un Segment con hasta un nivel de anidamiento de matrices (una matriz dentro de otra matriz). Por ejemplo, con los siguientes atributos, puedes crear un Segment para pets[].name contiene Mochi, pero no puedes crear un Segment para pets[].nicknames[] contiene 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"
]
}
]
}
]
}
Puntos de datos
Los puntos de datos se registran de forma diferente según si creas, actualizas o eliminas una propiedad.
Al crear una nueva matriz, se registra un punto de datos por cada atributo de un objeto. Este ejemplo cuesta ocho puntos de datos: cada objeto de mascota tiene cuatro atributos y hay dos objetos.
{
"attributes": [
{
"external_id": "user_id",
"pets": [
{
"id": 1,
"type": "dog",
"breed": "beagle",
"name": "Mochi"
},
{
"id": 2,
"type": "cat",
"breed": "calico",
"name": "Pixel"
}
]
}
]
}
Al actualizar una matriz existente, se registra un punto de datos por cada propiedad añadida. Este ejemplo cuesta dos puntos de datos, ya que solo actualiza una propiedad en cada uno de los dos objetos.
{
"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"
}
}
]
}
}
]
}
Al eliminar un objeto de una matriz, se registra un punto de datos por cada criterio de eliminación que envíes. Este ejemplo cuesta tres puntos de datos, aunque con esta instrucción puedas estar eliminando varios perros.
{
"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"
}
]
}
}
]
}