Skip to content

Conjunto de objetos

Esta página explica cómo utilizar una matriz 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. Estas matrices 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:

Consideraciones

  • Las matrices de objetos están pensadas 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.
  • Las matrices 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 la matriz 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 la matriz por debajo del límite y poder agregar nuevos elementos, usa $remove para eliminar elementos de la matriz primero.
  • No todos los socios de Braze admiten matrices de objetos. Consulta la documentación del socio para confirmar si la integración admite esta característica.

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

Ejemplo de API

El siguiente es un ejemplo de /users/track con una matriz pets. Para capturar las propiedades de las mascotas, envía una solicitud de API que liste pets como una matriz 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.

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

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

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

Actualiza valores para objetos específicos dentro de una matriz usando el parámetro _merge_objects y el operador $update. De manera similar a las actualizaciones de objetos simples 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 una matriz. Para hacer esto, necesitarás eliminar el elemento completo de la matriz y luego agregar el objeto sin esa clave específica (usando una combinación de $remove y $add).

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 una matriz usando el operador $remove en combinación con una clave coincidente ($identifier_key) y un valor ($identifier_value).

El siguiente ejemplo muestra cómo eliminar cualquier objeto en la matriz 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 matriz, Braze las procesa en este orden:

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

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 una matriz 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", "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);

Plantillas Liquid

Puedes usar esta matriz 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 la matriz 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 matrices de objetos, un usuario calificará para el segmento si algún objeto en la matriz coincide con los criterios.

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

Filtrar por matriz de objetos.

Usa la notación de punto para especificar qué campo en la matriz 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 una matriz de objetos. Después, agrega un punto ., seguido del nombre del campo que deseas usar.

Por ejemplo, si deseas filtrar una matriz 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 matriz (matriz dentro de otra matriz). Por ejemplo, dados los siguientes atributos, puedes crear un segmento para pets[].name contiene Gus, 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": "Gus",
          "nicknames": [
            "Gugu",
            "Gusto"
          ]
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald",
          "nicknames": [
            "GeGe",
            "Gerry"
          ]
        }
      ]
    }
  ]
}

Puntos de datos

Los puntos de datos se registran de manera diferente dependiendo de si creas, actualizas o eliminas una propiedad.

Crear una nueva matriz 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": "Gus"
        },
        {
          "id": 2,
          "type": "cat",
          "breed": "calico",
          "name": "Gerald"
        }
      ]
    }
  ]
}

Actualizar una matriz 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 una matriz 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!