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. Este objeto se puede utilizar para segmentar 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 diseñados para atributos personalizados enviados a través de Braze SDK o API.
• 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 se modifica.
• Los nombres de clave y los valores de cadena tienen un límite de tamaño 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 API si estás intentando enviar un atributo personalizado anidado a un perfil de usuario.
• No todos los partners de Braze son compatibles con los atributos personalizados anidados. Consulta la documentación de partners para confirmar si integraciones de partners específicas son compatibles con esta característica.
• Los atributos personalizados anidados no se pueden usar como filtro al realizar una llamada a la API de Connected Audience.
• De forma predeterminada, el filtro de Segment de 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 de esquema de propiedades incluye rutas de matriz (usando la notación []) para campos de matriz anidados. Para ocultar los atributos personalizados de matriz de nivel superior de ese filtro, ponte en contacto con soporte de Braze.
• Al previsualizar mensajes en el panel usando Vista previa como usuario personalizado, solo puedes introducir datos simulados como cadena o matriz de cadenas: los objetos anidados no son compatibles. Para previsualizar un mensaje que hace referencia a atributos personalizados anidados, selecciona un usuario existente que ya tenga el atributo anidado en su perfil. Para propiedades de eventos personalizados anidados, debes lanzar una campaña en vivo dirigida a un usuario de prueba para verificar la representación.

Ejemplo de API

• crear
• actualizar
• eliminar

El siguiente es 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 lista most_played_song como un 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 realizará una fusión profunda de tu actualización con los datos del objeto existente. La fusión profunda asegura 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 estamos añadiendo 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
      }
    }
  ]
}

Después de recibir 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 enfoque no se puede utilizar para eliminar una clave anidada dentro de una matriz de objetos.

Ejemplo del SDK

Los siguientes ejemplos muestran cómo crear, actualizar mediante combinació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");

Capturar 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 “Important Dates” para capturar el conjunto de propiedades de 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

Si no has capturado fechas como propiedades de objetos inicialmente, te recomendamos reenviar 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, el atributo personalizado anidado completo no se actualizará.

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

Para los atributos personalizados anidados, si el año es menor que 0 o mayor que 3000, Braze no almacena estos valores en el usuario.

Plantillas Liquid

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

Usa 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, seguido del 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 usar Liquid de atributos personalizados anidados en tu mensaje:

1. Ve a una Campaign o Canvas y abre el paso de mensaje donde quieras añadir personalización.
2. En el creador de mensajes, inserta el fragmento de código Liquid donde quieras que aparezca el valor.
3. Usa Preview & Test con un usuario existente que ya tenga el atributo personalizado anidado en su perfil para confirmar que el valor se muestra como se espera.

Personalización

Puedes usar Add Personalization para insertar un atributo personalizado anidado en tu mensaje.

Para abrir Add Personalization:

1. Ve a una Campaign o Canvas y abre el paso de mensaje donde quieras añadir personalización.
2. En el creador de mensajes, selecciona Personalization para abrir la barra lateral de Add Personalization, donde puedes elegir opciones de personalización.

Para configurar la personalización de atributos personalizados anidados:

1. En Personalization Type, selecciona Nested Custom Attributes.
2. En Top Level Attribute, selecciona la ruta del atributo personalizado anidado que quieras insertar. Por ejemplo, selecciona preferences.neighborhood_office.
3. Opcional: En Default value, introduce un valor alternativo para los usuarios que no tengan su propio valor para ese atributo.
4. Revisa el Liquid Snippet generado para confirmar que coincide con la ruta esperada.
5. Selecciona Insert.

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

Comprueba que se haya generado un esquema si no ves la opción de insertar atributos personalizados anidados.

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 cuando un objeto de atributo personalizado anidado cambia. Esta opción no está disponible para cambios en matrices de objetos. Si no ves una opción para ver el explorador de rutas, comprueba que hayas generado un esquema.

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

Para configurar este desencadenador en una campaña basada en acciones:

1. Crea o edita una campaña y luego establece el tipo de entrega en Entrega basada en acciones.
2. En la configuración del desencadenador, selecciona Cambiar valor de atributo personalizado.
3. Selecciona la ruta del atributo personalizado anidado que deseas monitorear. Por ejemplo, selecciona preferences.neighborhood_office.
4. Selecciona la condición de desencadenamiento que desees, como cualquier valor nuevo.
5. Termina de configurar el mensaje y la audiencia de tu campaña, y luego lanza la campaña.

Solución de problemas

Los valores de atributos personalizados anidados no se aplican de manera consistente

Si notas que los valores de atributos personalizados anidados no se están añadiendo a los perfiles de usuario de manera consistente, el problema suele estar relacionado con discrepancias en los tipos de datos.

Para diagnosticar y resolver este problema:

1. Compara ejemplos de usuarios: Obtén un ejemplo de usuario exitoso y uno no exitoso donde el atributo personalizado anidado debería haberse establecido.
2. Revisa la estructura de datos: Visualiza y compara los valores de atributos personalizados en ambos perfiles:
   • ¿Las propiedades están almacenadas dentro de un objeto?
   • ¿Las propiedades están almacenadas como una matriz de propiedades?
3. Verifica 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 deseas verificar.
   • Si la fila muestra Generate Schema, selecciónala para generar el esquema primero.
   • Después de que se genere el esquema, selecciona el icono de más en la columna Attribute Name para ese atributo.
   • En el modal Edit schema, revisa los atributos anidados y sus valores correspondientes en la columna Data type.

Si encuentras que el tipo de datos no coincide con el formato previsto en los perfiles de usuario, elimina el valor con formato incorrecto de los perfiles de usuario afectados y reenvía el atributo en el formato correcto utilizando la solicitud de API o el método de SDK apropiado.

Comportamiento de la segmentación con matrices de objetos

Cuando utilizas varios filtros de Nested Custom Attribute 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 califica para el Segment si cualquier elemento de la matriz satisface 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 calificaría 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 individual satisface ambas condiciones, el usuario aún entra en el Segment.

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

Puntos de datos

Cualquier clave que se envíe 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.