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 dirigirse 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 destinados a 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 permanece sin cambios.
• 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 compatibles en una carga útil de 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 del partner para confirmar si integraciones específicas del partner admiten 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 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, contacta con soporte de Braze.
• Al previsualizar mensajes en el panel usando Vista previa como usuario personalizado, solo puedes introducir datos simulados como una cadena o una 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 las 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 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 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 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 objeto

Para capturar fechas como propiedades de objeto, debes usar 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 objeto inicialmente, te recomendamos reenviar estos datos usando la clave $time para todos los usuarios. De lo contrario, esto puede resultar en Segments incompletos al usar 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 utilizarlas en tu mensajería.

Usa la etiqueta de personalización custom_attribute y la notación de punto 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 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 se espera.

Personalización

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

Para abrir Añadir personalización:

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 Personalización para abrir la barra lateral Añadir personalización, donde puedes elegir 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 quieras 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 Liquid generado para confirmar que coincide con la ruta esperada.
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

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 Campaign basada en acciones, puedes agregar una nueva acción desencadenante para Cambiar valor de atributo personalizado para dirigirte a los usuarios que han cambiado sus preferencias de oficina del vecindario.

Para configurar este desencadenador en una Campaign basada en acciones:

1. Crea o edita una Campaign, 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 Campaign, luego lanza la Campaign.

Solución de problemas

Valores de atributos personalizados anidados no aplicados de forma consistente

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

Para diagnosticar y resolver este problema:

1. Compara ejemplos de usuarios: Obtén un ejemplo de usuario exitoso y otro no exitoso en los que 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. 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 deseas verificar.
   • Si la fila muestra Generate Schema, selecciónalo para generar el esquema primero.
   • Una vez generado 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 cumple los requisitos del 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 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 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.