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 construir segmentos más ricos y personalizar mensajes con datos de un único objeto personalizado de atributo.

En el siguiente ejemplo, el atributo personalizado favorite_book contiene los atributos anidados title, author y publishing_date. Este objeto puede utilizarse para dirigirse a los 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:

Limitaciones

• 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.
• Los nombres de las claves y los valores de cadena tienen un límite de tamaño de 255 caracteres.
• Los nombres de las claves 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 socios de Braze admiten atributos personalizados anidados. Consulta la documentación del socio para confirmar si determinadas integraciones del socio admiten esta característica.
• Los atributos personalizados anidados no se pueden utilizar como filtro al realizar una llamada a la API de Connected Audience.

Ejemplo de API

• create
• update
• delete

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

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

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

1
2
3
4
5
6
7
8
{
  "attributes": [
    {
      "external_id": "user_id",
      "most_played_song": null
    }
  ]
}

Ejemplo de SDK

• android sdk
• swift sdk
• web 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);

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.

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

Plantillas Liquid

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 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, 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”

Segmentación

Puedes crear segmentos basados en atributos personalizados anidados para segmentar aún más a tus usuarios. Para ello, filtra tu segmento basándote en el objeto de atributo personalizado y, a continuación, especifica la ruta al nombre de la propiedad y el valor asociado sobre el que deseas segmentar. Si no tienes claro cómo es esa ruta, puedes generar un esquema y utilizar el explorador de objetos anidados para que Braze rellene esa ruta por ti.

Tras añadir una ruta a tu propiedad, selecciona Validar para comprobar que el valor del campo de la ruta es válido.

Para segmentar con atributos personalizados anidados, selecciona el filtro Atributos personalizados anidados para mostrar un desplegable en el que puedes seleccionar un atributo personalizado anidado específico.

Cuando trabajes con la segmentación de atributos personalizados anidados, tendrás acceso a un nuevo comparador agrupado por tipo de datos. Por ejemplo, como play_analytics.count es un número, puedes seleccionar un comparador en la categoría Número.

Filtrado de tipos de datos temporales

Al filtrar un atributo personalizado anidado de tipo temporal, puedes elegir filtrar con operadores en las categorías Día del año u Hora al comparar el valor de la fecha.

Si seleccionas un operador en la categoría Día del año, solo se comprobarán el mes y el día para la comparación, en lugar de la marca de tiempo completa del valor del atributo personalizado anidado. Al seleccionar un operador en la categoría Hora, se comparará la marca de tiempo completa, incluido el año.

Segmentación multicriterios

Utiliza Segmentación multicriterios para crear un segmento que coincida con varios criterios dentro de un mismo objeto. Esto califica al usuario en el segmento si tiene al menos una matriz de objetos que coincida con todos los criterios especificados. Por ejemplo, los usuarios solo coincidirán con este segmento si su clave no está en blanco y si su número es superior a 0.

También puedes utilizar la función Copiar Liquid para segmento para generar código Liquid para este segmento y utilizarlo en un mensaje. Por ejemplo, supongamos que tienes una matriz de objetos de cuenta y un segmento dirigido a clientes con cuentas imponibles activas. Para conseguir que los clientes contribuyan al objetivo de cuenta asociado a una de sus cuentas activas y sujetas a impuestos, deberás crear un mensaje para darles un empujón.

Al seleccionar Copiar Liquid para segmento, Braze generará automáticamente código Liquid que devuelva una matriz de objetos que solo contenga cuentas activas y sujetas a impuestos.

1
2
3
4
5
6
7
{% assign segmented_nested_objects = '' | split: '' %}
{% assign obj_array = {{custom_attribute.${accounts}}} %}
{% for obj in obj_array %}
  {% if obj["account_type"] == 'taxable' and obj["active"] == true %}
    {% assign segmented_nested_objects = obj_array | slice: forloop.index0 | concat: segmented_nested_objects | reverse %}
  {% endif %}
{% endfor %}

Desde aquí, puedes utilizar segmented_nested_objects y personalizar tu mensaje. En este ejemplo, queremos tomar un objetivo de la primera cuenta fiscal activa y personalizarlo:

1
Get to your {{segmented_nested_objects[0].goal}} goal faster, make a deposit using our new fast deposit feature!

Esto devuelve el siguiente mensaje a tu cliente: “Get to your retirement goal faster, make a deposit using our new fast deposit feature!”

Generar un esquema utilizando el explorador de objetos anidados

Puedes generar un esquema para tus objetos y así construir filtros de segmentos sin necesidad de memorizar rutas de objetos anidados. Para ello, sigue estos pasos.

Paso 1: Genera un esquema

Para este ejemplo, supongamos que tenemos una matriz de objetos accounts que acabamos de enviar a Braze:

1
2
3
4
5
6
7
8
{"accounts": [
  {"type": "taxable",
  "balance": 22500,
  "active": true},
  {"type": "non-taxable",
  "balance": 0,
  "active": true}
]}

En el dashboard de Braze, ve a Configuración de datos > Atributos personalizados.

Busca tu objeto o matriz de objetos. En la columna Nombre del atributo, selecciona Generar esquema.

Una vez generado el esquema, aparece un nuevo botón en lugar del botón Generar esquema. Puedes hacer clic en él para ver lo que Braze sabe sobre este atributo personalizado anidado.

Durante la generación del esquema, Braze examina los datos enviados anteriormente y construye una representación ideal de tus datos para este atributo. Braze también analiza y añade un tipo de datos para tus valores anidados. Esto se hace muestreando los datos anteriores enviados a Braze para el atributo anidado dado.

Para nuestra matriz de objetos accounts, puedes ver que dentro de la matriz de objetos hay un objeto que contiene lo siguiente:

• Un tipo booleano con una clave de active (independientemente de si la cuenta está activa o no)
• Un tipo de número con una clave de balance (importe del saldo en la cuenta)
• Un tipo de cadena con una clave de type (cuenta no imponible o imponible)

Ahora que hemos analizado y construido una representación de los datos, vamos a crear un segmento.

Paso 2: Crea un segmento

Dirijámonos a los clientes con un saldo inferior a 100 para enviarles un mensaje que les anime a realizar un ingreso.

Crea un segmento y añade el filtro Nested Custom Attribute, después busca y selecciona tu objeto o matriz de objetos. Aquí hemos añadido la matriz de objetos accounts.

Selecciona el botón en el campo de la ruta. Esto mostrará una representación de tu objeto o matriz de objetos. Puedes seleccionar cualquiera de los elementos de la lista y Braze los insertará en el campo de ruta por ti. En este ejemplo, necesitamos obtener el saldo. Selecciona el saldo y la ruta (en este caso, [].balance) se rellenará automáticamente en el campo de ruta.

Puedes seleccionar Validar para comprobar que el contenido del campo de la ruta es válido y, a continuación, construir el resto del filtro según sea necesario. Aquí hemos especificado que el saldo debe ser inferior a 100.

¡Eso es todo! Acabas de crear un segmento utilizando un atributo personalizado anidado, todo ello sin necesidad de saber cómo están estructurados los datos. El explorador de objetos anidados de Braze generó una representación visual de tus datos y te permitió explorar y seleccionar exactamente lo que necesitabas para crear un segmento.

Desencadenar cambios de 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 una opción para ver el explorador de rutas, comprueba que hayas generado un esquema.

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

Personalización

Mediante el modal Añadir personalización, también puedes insertar atributos personalizados anidados en tu mensajería. Selecciona Atributos personalizados anidados como tipo de personalización. A continuación, selecciona el atributo de nivel superior y la clave de atributo.

Por ejemplo, en el modal de personalización que aparece a continuación, se inserta el atributo personalizado anidado de una oficina de barrio local basada en las preferencias de un usuario.

Regenerar esquemas

Una vez generado un esquema, puede regenerarse una vez cada 24 horas. Esta sección describe cómo regenerar tu esquema. Para obtener información más detallada sobre los esquemas, consulta la sección de este artículo sobre la generación de un esquema.

Para regenerar el esquema de tu atributo personalizado anidado:

1. Ve a Configuración de datos > Atributos personalizados.
2. Busca tu atributo personalizado anidado.
3. En la columna Nombre del atributo de tu atributo, selecciona para administrar el esquema.
4. Aparecerá un modal. Selecciona Regenerar esquema.

La opción de regenerar el esquema se desactivará si han transcurrido menos de 24 horas desde la última regeneración del esquema. La regeneración del esquema solo detectará los objetos nuevos y no eliminará los objetos que ya existen en el esquema.

Si los datos no aparecen como se esperaba tras regenerar el esquema, puede que el atributo no se ingiera con la frecuencia suficiente. Los datos de usuario se muestrean a partir de los datos anteriores enviados a Braze para el atributo anidado dado. Si el atributo no se ingiere lo suficiente, no se recogerá para el esquema.

Comportamiento de segmentación con matrices de objetos

Cuando utilizas múltiples filtros 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 segmento 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 segmento 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 segmento.

Si necesitas que todas las condiciones coincidan con el mismo elemento dentro de una matriz, utiliza la segmentación multicriterios 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
        }
      }
    }
  ]
}