Ir al contenido

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:

  • Día del año: comprueba solo el mes y el día para comparar, por ejemplo 03-15.
  • Tiempo: 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

  • 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 $add o $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 $remove para 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.

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

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:

  1. $add
  2. $remove
  3. $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)
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.

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