Skip to content

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:

  • Day of Year: comprueba solo el mes y el día para comparar, por ejemplo 03-15.
  • Time: compara la marca de tiempo completa, incluido el año, por ejemplo 2023-03-15T12:00:00Z.
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

  • Los conjuntos de objetos están pensados para atributos personalizados enviados a través de la API. No es posible cargar archivos CSV. Esto se debe a que las comas en el archivo CSV se interpretarán como un separador de columna, y las comas en los valores causarán errores de análisis.
  • Los conjuntos de objetos no tienen límite en el número de elementos, pero sí un tamaño máximo de 100 KB. Si una actualización (como $add o $update) hace que el conjunto supere este límite, Braze descarta la actualización y el atributo permanece sin cambios. La solicitud de API aún devuelve una respuesta de éxito. Para mantener el conjunto por debajo del límite y poder agregar nuevos elementos, usa $remove para eliminar elementos del conjunto primero.
  • No todos los socios de Braze admiten conjuntos de objetos. Consulta la documentación del socio para confirmar si la integración admite esta característica.

Actualizar o eliminar elementos de un conjunto requiere identificar el elemento por clave y valor, así que considera incluir un identificador único para cada elemento del conjunto. La unicidad se aplica solo al conjunto y es útil si deseas actualizar y eliminar objetos específicos de tu conjunto. Esto no es aplicado por Braze.

Ejemplo de API

Usa estos ejemplos cuando envíes solicitudes /users/track que creen o actualicen atributos personalizados anidados almacenados como conjuntos de objetos. La carga útil usa los operadores $add, $remove y $update para que puedas cambiar objetos específicos sin reconstruir el conjunto completo en cada solicitud.

El siguiente es un ejemplo de /users/track con un conjunto pets. Para capturar las propiedades de las mascotas, envía una solicitud de API que liste pets como un conjunto de objetos. Ten en cuenta que a cada objeto se le ha asignado un id único que puede referenciarse más tarde al realizar actualizaciones.

Usa este formato cuando quieras crear el atributo por primera vez o reemplazar el conjunto completo con un nuevo conjunto base de objetos.

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": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

Agrega otro elemento al conjunto usando el operador $add. El siguiente ejemplo muestra cómo agregar tres objetos de mascotas más al conjunto pets del usuario.

Usa $add cuando necesites añadir uno o más objetos nuevos y mantener los objetos existentes sin cambios.

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": "Biscuit"
          },
          {
            "id": 4,
            "type": "fish",
            "breed": "salmon",
            "name": "Pepper"
          },
           {
            "id": 5,
            "type": "bird",
            "breed": "parakeet",
            "name": "Noodle"
          }
        ]
      }
    }
  ]
}

Actualiza valores para objetos específicos dentro de un conjunto usando el parámetro _merge_objects y el operador $update. De manera similar a las actualizaciones de otros objetos de atributos personalizados anidados, esto realiza una fusión profunda.

Ten en cuenta que $update no se puede usar para eliminar una propiedad anidada de un objeto dentro de un conjunto. Para hacer esto, necesitarás eliminar el elemento completo del conjunto y luego agregar el objeto sin esa clave específica (usando una combinación de $remove y $add).

Usa $update cuando el objeto ya exista y quieras cambiar uno o más campos haciendo coincidir $identifier_key y $identifier_value.

El siguiente ejemplo muestra cómo actualizar la propiedad breed a goldfish para el objeto con un id de 4. Este ejemplo de solicitud también actualiza el objeto con id igual a 5 con un nuevo name de Annette. Dado que el parámetro _merge_objects está configurado como true, todos los demás campos de estos dos objetos permanecen iguales.

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

Elimina objetos de un conjunto usando el operador $remove en combinación con una clave coincidente ($identifier_key) y un valor ($identifier_value).

Usa $remove cuando quieras eliminar todos los objetos coincidentes para un par de identificador conocido, como id = 2 o type = dog.

El siguiente ejemplo muestra cómo eliminar cualquier objeto en el conjunto pets que tenga un id con valor 1, un id con valor 2 y un type con valor dog. Si hay múltiples objetos con el valor de type dog, todos los objetos coincidentes serán eliminados.

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

Orden de procesamiento

Cuando una sola solicitud /users/track incluye operaciones $add, $remove y $update para el mismo atributo de conjunto, Braze las procesa en este orden:

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

Este orden se aplica dentro de un solo objeto de actualización de atributo en una solicitud y determina el estado final del conjunto después de que se evalúan todas las operaciones.

Dado que $add se ejecuta antes que $remove, no puedes usar un $remove seguido de $add como mecanismo de upsert dentro de una sola solicitud. El $add se procesa primero, luego el $remove elimina el elemento. Para hacer un upsert, envía el $remove en una solicitud separada antes del $add.

Marcas de tiempo

Al incluir campos como marcas de tiempo en un conjunto de objetos, usa el formato $time en lugar de cadenas simples o enteros de época Unix.

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

Ejemplo 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", "Pixel")
    )

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

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": "Mochi"
  ],
  [
    "id": 2,
    "type": "cat",
    "breed": "calico",
    "name": "Pixel"
  ]
]

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": "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)

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": "Mochi"
}, {
  "id": 2,
  "type": "cat",
  "breed": "calico",
  "name": "Pixel"
}];
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":  "Pepper",
  }, {
    "id":  5,
    "type":  "bird",
    "breed":  "parakeet",
    "name":  "Noodle",
  }]
};
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);

Plantillas Liquid

Puedes usar este conjunto pets para personalizar un mensaje. El siguiente ejemplo de plantilla Liquid muestra cómo hacer referencia a las propiedades del objeto de atributo personalizado guardadas de la solicitud de API anterior y usarlas en tu mensajería.

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

En este escenario, puedes usar Liquid para recorrer el conjunto pets e imprimir una declaración para cada mascota. Asigna una variable al atributo personalizado pets y usa la notación de punto para acceder a las propiedades de un objeto. Especifica el nombre del objeto, seguido de un punto ., seguido del nombre de la propiedad.

Segmentación

Al segmentar usuarios basándote en conjuntos de objetos, un usuario calificará para el segmento si algún objeto en el conjunto coincide con los criterios.

Crea un nuevo segmento y selecciona Atributo personalizado anidado como tu filtro. Luego busca y selecciona el nombre de tu conjunto de objetos.

Filtrar por conjunto de objetos.

Usa la notación de punto para especificar qué campo en el conjunto de objetos deseas usar. Comienza el campo de texto con un conjunto vacío de corchetes [] para indicarle a Braze que estás buscando dentro de un conjunto de objetos. Después, agrega un punto ., seguido del nombre del campo que deseas usar.

Por ejemplo, si deseas filtrar un conjunto de objetos top_3_movies basándote en el campo type, ingresa [].type y elige las películas por las que filtrar, como Fantasy Movie.

Niveles de anidamiento

Puedes crear un segmento con hasta un nivel de anidamiento de conjunto (conjunto dentro de otro conjunto). Por ejemplo, dados los siguientes atributos, puedes crear un segmento para pets[].name contiene Mochi, pero no puedes crear un segmento para pets[].nicknames[] contiene 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": "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 manera diferente dependiendo de si creas, actualizas o eliminas una propiedad.

Crear un nuevo conjunto registra un punto de datos por cada atributo en un objeto. Este ejemplo cuesta ocho puntos de datos: cada objeto de mascota tiene cuatro atributos y hay dos objetos.

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": "Mochi"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Pixel"
        }
      ]
    }
  ]
}

Actualizar un conjunto existente registra un punto de datos por cada propiedad agregada. Este ejemplo cuesta dos puntos de datos, ya que solo actualiza una propiedad en cada uno de los dos objetos.

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

Eliminar un objeto de un conjunto registra un punto de datos por cada criterio de eliminación que envíes. Este ejemplo cuesta tres puntos de datos, aunque puedas estar eliminando múltiples perros con esta declaración.

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"
          }
        ]
      }
    }
  ]
}
New Stuff!