Atributos personalizados anidados

Esta página trata de los atributos personalizados anidados, que te permiten definir un conjunto de atributos como propiedad de otro atributo. En otras palabras, cuando defines un objeto de atributo personalizado, puedes definir un conjunto de atributos adicionales para ese objeto.

Acerca de los atributos anidados

Los atributos anidados te permiten crear segmentos más completos y personalizar mensajes con datos de un único objeto de atributo personalizado.

En el siguiente ejemplo, el atributo personalizado favorite_book contiene los atributos anidados title, author y publishing_date. Puedes usar este objeto para dirigirte a usuarios por autor, filtrar por fecha de publicación o insertar el título del libro directamente en un mensaje:

1
2
3
4
5

"favorite_book": {
  "title": "The Hobbit",
  "author": "J.R.R. Tolkien",
  "publishing_date": "1937"
}

Tipos de datos admitidos

Se admiten los siguientes tipos de datos:

Consideraciones

• Los atributos personalizados anidados están pensados para atributos personalizados enviados a través del SDK o la API de Braze.
• Los objetos tienen un tamaño máximo de 100 KB. Si una actualización hace que el objeto supere los 100 KB, Braze descarta la actualización y el atributo no cambia.
• Los nombres de clave y los valores de cadena tienen un límite de 255 caracteres.
• Los nombres de clave no pueden contener espacios.
• Los puntos (.) y los signos de dólar ($) no son caracteres admitidos en una carga útil de la API si intentas enviar un atributo personalizado anidado a un perfil de usuario.
• No todos los partners de Braze admiten atributos personalizados anidados. Consulta la documentación de partners para confirmar si determinadas integraciones de partners admiten esta característica.
• Los atributos personalizados anidados no pueden utilizarse como filtro al hacer una llamada a la API de Connected Audience.
• De forma predeterminada, el filtro de segmento Atributos personalizados anidados incluye atributos personalizados de tipo objeto, atributos de matriz de objetos y atributos personalizados de tipo matriz. Cuando seleccionas un atributo, el selector del esquema de propiedades incluye rutas de matriz (con la notación []) para los campos de matriz anidados. Para ocultar de ese filtro los atributos personalizados de matriz de nivel superior, ponte en contacto con el soporte de Braze.
• Al obtener la vista previa de mensajes en el panel con Vista previa como usuario personalizado, solo puedes introducir datos de prueba como una cadena o una matriz de cadenas; no se admiten objetos anidados. Para obtener la vista previa de un mensaje que hace referencia a atributos personalizados anidados, selecciona un usuario existente que ya tenga el atributo anidado en su perfil. Para las propiedades anidadas de eventos personalizados, debes lanzar una campaña en vivo dirigida a un usuario de prueba para verificar cómo se muestra.

Ejemplo de API

• crear
• actualizar
• eliminar

A continuación, se muestra un ejemplo de /users/track con un objeto “Most Played Song”. Para capturar las propiedades de la canción, enviaremos una solicitud de API que incluya most_played_song como objeto, junto con un conjunto de propiedades del objeto.

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "genre": "Jazz",
        "play_analytics": {
            "count": 1000,
            "top_10_listeners": true
        }
      }
    }
  ]
}

Para actualizar un objeto existente, envía un POST a users/track con el parámetro _merge_objects en la solicitud. Esto fusionará en profundidad tu actualización con los datos del objeto existente. La fusión profunda garantiza que todos los niveles de un objeto se fusionen con otro objeto, en lugar de solo el primer nivel. En este ejemplo, ya tenemos un objeto most_played_song en Braze y ahora vamos a añadir un nuevo campo, year_released, al objeto most_played_song.

1
2
3
4
5
6
7
8
9
10
11

{
  "attributes": [
    {
      "external_id": "user_id",
      "_merge_objects": true,
      "most_played_song": {
          "year_released": 1960
      }
    }
  ]
}

Una vez recibida esta solicitud, el objeto de atributo personalizado tendrá el siguiente aspecto:

1
2
3
4
5
6
7
8
9
10
11

{"most_played_song": {
  "song_name": "Solea",
  "artist_name" : "Miles Davis",
  "album_name": "Sketches of Spain",
  "year_released": 1960,
  "genre": "Jazz",
  "play_analytics": {
     "count": 1000,
     "top_10_listeners": true
  }
}}

Advertencia

Debes establecer _merge_objects en true, o tus objetos se sobrescribirán. _merge_objects es false de forma predeterminada.

Para eliminar un objeto de atributo personalizado, envía un POST a users/track con el objeto de atributo personalizado establecido en null.

1
2
3
4
5
6
7
8

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

Nota

Este método no se puede utilizar para eliminar una clave anidada dentro de una matriz de objetos.

Ejemplo de SDK

Los siguientes ejemplos muestran cómo crear, actualizar mediante fusión y eliminar el mismo objeto de atributo personalizado anidado (most_played_song) en cada SDK.

• android sdk
• swift sdk
• web sdk
• unity sdk

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

val json = JSONObject()
    .put("song_name", "Solea")
    .put("artist_name", "Miles Davis")
    .put("album_name", "Sketches of Spain")
    .put("genre", "Jazz")
    .put(
        "play_analytics",
        JSONObject()
            .put("count", 1000)
            .put("top_10_listeners", true)
    )

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

1
2
3
4
5
6

val json = JSONObject()
    .put("year_released", 1960)

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

1
2
3

braze.getCurrentUser { user ->
    user.unsetCustomUserAttribute("most_played_song")
}

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

let json: [String: Any?] = [
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": [
    "count": 1000,
    "top_10_listeners": true,
  ],
]

braze.user.setCustomAttribute(key: "most_played_song", dictionary: json)

1
2
3
4
5

let json: [String: Any?] = [
  "year_released": 1960
]

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

1

braze.user.unsetCustomAttribute(key: "most_played_song")

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

import * as braze from "@braze/web-sdk";
const json = {
  "song_name": "Solea",
  "artist_name": "Miles Davis",
  "album_name": "Sketches of Spain",
  "genre": "Jazz",
  "play_analytics": {
    "count": 1000,
    "top_10_listeners": true
  }
};
braze.getUser().setCustomUserAttribute("most_played_song", json);

1
2
3
4
5
6

import * as braze from "@braze/web-sdk";
const json = {
  "year_released": 1960
};
braze.getUser().setCustomUserAttribute("most_played_song", json, true);

1
2

import * as braze from "@braze/web-sdk";
braze.getUser().setCustomUserAttribute("most_played_song", null);

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

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("song_name", "Solea");
attributes.Add("artist_name", "Miles Davis");
attributes.Add("album_name", "Sketches of Spain");
attributes.Add("genre", "Jazz");

Dictionary<string, object> playAnalytics = new Dictionary<string, object>();
playAnalytics.Add("count", 1000);
playAnalytics.Add("top_10_listeners", true);
attributes.Add("play_analytics", playAnalytics);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes);

1
2
3
4

Dictionary<string, object> attributes = new Dictionary<string, object>();
attributes.Add("year_released", 1960);

AppboyBinding.SetCustomUserAttribute("most_played_song", attributes, true);

1

AppboyBinding.UnsetCustomUserAttribute("most_played_song");

Captura de fechas como propiedades de objetos

Para capturar fechas como propiedades de objetos, debes utilizar la clave $time. En el siguiente ejemplo, se utiliza un objeto “Fechas importantes” para capturar el conjunto de propiedades del objeto, birthday y wedding_anniversary. El valor de estas fechas es un objeto con una clave $time, que no puede ser un valor nulo.

Nota

Cuando _merge_objects es true, un valor null sin $time elimina un campo de fecha anidado existente del objeto. Si el campo no existe todavía, Braze ignora el valor null y no crea el campo. Braze no devuelve un error en ninguno de los dos casos.

Si no capturaste inicialmente las fechas como propiedades de objetos, te recomendamos que vuelvas a enviar estos datos utilizando la clave $time para todos los usuarios. De lo contrario, esto puede dar lugar a Segments incompletos al utilizar el atributo $time. Sin embargo, si el valor de $time en un atributo personalizado anidado no tiene el formato correcto, no se actualizará todo el atributo personalizado anidado.

1
2
3
4
5
6
7
8
9
10
11

{
  "attributes": [
    {
      "external_id": "time_with_nca_test",
      "important_dates": {
        "birthday": {"$time" : "1980-01-01"},
        "wedding_anniversary": {"$time" : "2020-05-28"}
      }
    }
  ]
}

Nota

En el caso de los atributos personalizados anidados, si el año es inferior a 0 o superior a 3000, Braze no almacena estos valores en el usuario.

Plantillas de Liquid

El siguiente ejemplo de plantillas de Liquid muestra cómo hacer referencia a las propiedades del objeto de atributo personalizado guardadas en la solicitud de API anterior y utilizarlas en tu mensajería.

Utiliza la etiqueta de personalización custom_attribute y la notación de puntos para acceder a las propiedades de un objeto. Especifica el nombre del objeto (y la posición en la matriz si haces referencia a una matriz de objetos), seguido de un punto y, a continuación, el nombre de la propiedad.

{{custom_attribute.${most_played_song}[0].artist_name}} — “Miles Davis”
{{custom_attribute.${most_played_song}[0].song_name}} — “Solea”
{{custom_attribute.${most_played_song}[0].play_analytics.count}} — “1000”

Para utilizar Liquid de atributos personalizados anidados en tu mensaje:

1. Ve a una campaña o a un Canvas y abre el paso de mensaje en el que quieres añadir personalización.
2. En el creador de mensajes, inserta el fragmento de código de Liquid donde quieres que aparezca el valor.
3. Utiliza Vista previa y prueba con un usuario existente que ya tenga el atributo personalizado anidado en su perfil para confirmar que el valor se muestra como esperas.

Personalización

Puedes utilizar Añadir personalización para insertar un atributo personalizado anidado en tu mensaje.

Para abrir Añadir personalización:

1. Ve a una campaña o a un Canvas y abre el paso de mensaje en el que quieres añadir personalización.
2. En el creador de mensajes, selecciona Personalización para abrir la barra lateral Añadir personalización, donde puedes elegir las opciones de personalización.

Para configurar la personalización de atributos personalizados anidados:

1. En Tipo de personalización, selecciona Atributos personalizados anidados.
2. En Atributo de nivel superior, selecciona la ruta del atributo personalizado anidado que quieres insertar. Por ejemplo, selecciona preferences.neighborhood_office.
3. Opcional: En Valor predeterminado, introduce un valor alternativo para los usuarios que no tengan su propio valor para ese atributo.
4. Revisa el Fragmento de código de Liquid generado para confirmar que coincide con la ruta que esperas.
5. Selecciona Insertar.

En este ejemplo, Braze inserta el valor anidado de preferences.neighborhood_office en tu mensaje. Los valores predeterminados son alternativas que tu mensaje incluye para los usuarios que no tienen su propio valor para un atributo.

Consejo

Si no ves la opción de insertar atributos personalizados anidados, comprueba que se haya generado un esquema.

Generar y regenerar esquemas

Para usar atributos personalizados anidados en la segmentación y la personalización, debes generar un esquema para el atributo. Después de que se haya generado un esquema, puedes regenerarlo según sea necesario. Para información más detallada sobre esquemas, consulta Generar un esquema usando el explorador de objetos anidados.

Generar un esquema

Después de crear un atributo personalizado anidado y enviar datos a Braze, puedes generar el esquema:

1. Ve a Data Settings > Custom Attributes.
2. Busca tu atributo personalizado anidado.
3. En la columna Attribute Name de tu atributo, selecciona Generate Schema.

Después de que se genere el esquema, el icono cambia a un icono de signo más que puedes seleccionar para ver y administrar el esquema.

Regenerar un esquema

Para regenerar el esquema de tu atributo personalizado anidado:

1. Ve a Data Settings > Custom Attributes.
2. Busca tu atributo personalizado anidado.
3. En la columna Attribute Name de tu atributo, selecciona Manage schema para administrar el esquema.
4. Aparecerá un modal. Selecciona Regenerate Schema.

No puedes iniciar otra regeneración mientras un trabajo de esquema ya está en progreso (la opción no está disponible mientras el estado es Generating). Solo se puede ejecutar un trabajo de generación de esquema a la vez por empresa. Regenerar el esquema solo detecta nuevos objetos y no elimina objetos que actualmente existen en el esquema.

Importante

Para restablecer el esquema de una matriz de objetos con un objeto existente, necesitas crear un nuevo atributo personalizado. La regeneración del esquema no elimina objetos existentes.

Si los datos no aparecen como se esperaba después de regenerar el esquema, es posible que el atributo no se ingiera con suficiente frecuencia. Los datos de usuario se muestrean a partir de datos anteriores enviados a Braze para el atributo anidado dado. Si el atributo no se ingiere lo suficiente, no será recogido para el esquema.

Desencadenar cambios en atributos personalizados anidados

Puedes desencadenar una acción cuando cambia un objeto de atributo personalizado anidado. Esta opción no está disponible para cambios en matrices de objetos. Si no ves la opción para ver el explorador de rutas, comprueba que hayas generado un esquema.

Por ejemplo, en una Campaign basada en acciones, puedes añadir una nueva acción desencadenante para Cambiar el valor del atributo personalizado y dirigirte a los usuarios que hayan cambiado sus preferencias de oficina de barrio.

Para configurar este desencadenante en una Campaign basada en acciones:

1. Crea o edita una Campaign y, a continuación, establece el tipo de entrega en Entrega basada en acciones.
2. En la configuración del desencadenante, selecciona Cambiar el valor del atributo personalizado.
3. Selecciona la ruta del atributo personalizado anidado que quieres supervisar. Por ejemplo, selecciona preferences.neighborhood_office.
4. Selecciona la condición desencadenante que quieras, como cualquier valor nuevo.
5. Termina de configurar el mensaje y la audiencia de tu Campaign y, a continuación, lánzala.

Solución de problemas

Los valores de los atributos personalizados anidados no se aplican de forma coherente

Si notas que los valores de los atributos personalizados anidados no se añaden de forma coherente a los perfiles de usuario, el problema suele estar relacionado con discrepancias en el tipo de datos.

Para diagnosticar y resolver este problema:

1. Compara ejemplos de usuarios: Consigue un ejemplo de usuario correcto y otro incorrecto en los que debería haberse establecido el atributo personalizado anidado.
2. Revisa la estructura de datos: Visualiza y compara los valores del atributo personalizado en ambos perfiles:
   • ¿Las propiedades se almacenan dentro de un objeto?
   • ¿Las propiedades se almacenan como una matriz de propiedades?
3. Comprueba el filtro de segmentación: Compara la estructura de datos almacenada con la forma en que se hace referencia al atributo personalizado anidado en tus filtros de segmentación.
4. Verifica el tipo de datos: Para identificar el tipo de datos de un atributo personalizado:
   • Ve a Configuración de datos > Atributos personalizados.
   • Busca el atributo personalizado de nivel superior que contiene el atributo anidado que quieres verificar.
   • Si la fila muestra Generar esquema, selecciónalo para generar primero el esquema.
   • Una vez generado el esquema, selecciona el icono más en la columna Nombre del atributo de ese atributo.
   • En el modal Editar esquema, revisa los atributos anidados y sus valores correspondientes en la columna Tipo de datos.

Si descubres que el tipo de datos no coincide con el formato previsto en todos los perfiles de usuario, elimina el valor con formato incorrecto de los perfiles de usuario afectados y vuelve a enviar el atributo en el formato correcto mediante la solicitud de API o el método del SDK adecuados.

Comportamiento de segmentación con matrices de objetos

Cuando usas varios filtros de Atributo personalizado anidado con lógica AND para segmentar en una matriz de objetos, cada filtro se evalúa de forma independiente en todos los elementos de la matriz. Un usuario cumple los requisitos para el Segment si cualquier elemento de la matriz cumple cada filtro individual; los filtros no tienen que coincidir con el mismo elemento.

Por ejemplo, supongamos que un usuario tiene la siguiente matriz:

1
2
3
4
5
6

{
  "orders": [
    {"product": "Shoes", "price": 80},
    {"product": "Hat", "price": 25}
  ]
}

Un Segment con los siguientes filtros AND:

• orders[].price es mayor que 50
• orders[].price es menor que 30

Este usuario cumpliría los requisitos porque el primer filtro coincide con el elemento “Shoes” (80 > 50) y el segundo filtro coincide con el elemento “Hat” (25 < 30). Aunque ningún elemento por sí solo cumple ambas condiciones, el usuario igualmente entra en el Segment.

Si necesitas que todas las condiciones coincidan con el mismo elemento dentro de una matriz, usa la segmentación multicriterio en la misma ruta, o reestructura tus datos para evitar coincidencias entre elementos.

Puntos de datos

Cada clave que se envía consume un punto de datos. Por ejemplo, este objeto inicializado en el perfil de usuario cuenta como siete (7) puntos de datos:

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

{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": {
        "song_name": "Solea",
        "artist_name": "Miles Davis",
        "album_name": "Sketches of Spain",
        "year_released": 1960,
        "genre": "Jazz",
        "play_analytics": {
          "count": 1000,
          "top_10_listeners": true
        }
      }
    }
  ]
}

Nota

Actualizar un objeto de atributo personalizado a null también consume un punto de datos.