Objeto de atributos del usuario

Una solicitud API con cualquier campo del objeto de atributos crea o actualiza un atributo con ese nombre y el valor indicado en el perfil de usuario especificado.

Utiliza los nombres de campo de perfil de usuario de Braze (enumerados a continuación o cualquiera de los enumerados en la sección de campos de perfil de usuario de Braze) para actualizar esos valores especiales en el perfil de usuario en el panel o añade tus propios datos de atributos personalizados al usuario.

Cuerpo del objeto

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
  // One of "external_id" or "user_alias" or "braze_id" or "email" or "phone" is required
  "external_id" : (optional, string) see external user ID,
  "user_alias" : (optional, User alias object),
  "braze_id" : (optional, string) Braze user identifier,
  "email": (optional, string) User email address,
  "phone": (optional, string) User phone number,
  // Setting this flag to true puts the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" defaults to true.
  "_update_existing_only" : (optional, boolean),
  // See note regarding anonymous push token imports
  "push_token_import" : (optional, boolean),
  // Braze User Profile Fields
  "first_name" : "Alex",
  "email" : "[email protected]",
  // Custom Attributes
  "my_custom_attribute" : value,
  "my_custom_attribute_2" : {"inc" : int_value},
  "my_array_custom_attribute":[ "Value1", "Value2" ],
  // Adding a new value to an array custom attribute
  "my_array_custom_attribute" : { "add" : ["Value3"] },
  // Removing a value from an array custom attribute
  "my_array_custom_attribute" : { "remove" : [ "Value1" ]},
  // Array of objects custom attribute
  "my_array_of_objects_attribute": [{"key": "value"}, {"key": "value"}],
  // Adding to an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$add": [{"key": "value"}] },
  // Removing from an array of objects (nested custom attribute syntax)
  "my_array_of_objects_attribute": { "$remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• ID externo de usuario
• Alias de usuario

Nota

Para los atributos personalizados de matriz regulares, usa add y remove (sin $).

Para las matrices de objetos (atributos personalizados anidados), usa $add, $remove y $update en las cargas útiles de solicitud de /users/track. Estos operadores aplican cambios a nivel de objeto haciendo coincidir identificadores ($identifier_key y $identifier_value) y admiten actualizaciones en el lugar con $new_object.

Usa este formato cuando necesites agregar, eliminar o actualizar objetos dentro de una matriz existente preservando el resto del estado de la matriz. Para ejemplos completos de solicitudes, consulta Ejemplo de API de matriz de objetos y Ejemplo de SDK de matriz de objetos.

Para eliminar un atributo de perfil, establécelo como null. Algunos campos, como external_id y user_alias, no pueden eliminarse después de haberse añadido a un perfil de usuario.

Resolución de identificadores

A menos que estés realizando una importación anónima de tokens de notificaciones push, cada objeto de atributos de usuario debe incluir al menos un identificador: external_id, user_alias, braze_id, email o phone. Cuando sea posible, incluye solo un identificador por objeto para evitar ambigüedades sobre qué perfil de usuario se está actualizando o creando.

Ten en cuenta lo siguiente al utilizar identificadores:

• external_id y user_alias son mutuamente excluyentes. Incluir ambos en el mismo objeto de atributos de usuario devuelve un error. Para añadir un alias a un usuario que ya tiene un external_id, usa el endpoint /users/alias/new.
• email tiene prioridad sobre phone. Si tanto email como phone se incluyen en el mismo objeto, Braze usa email como identificador. Esto significa que los atributos se aplican al perfil de usuario asociado con esa dirección de correo electrónico, incluso si el número de teléfono pertenece a un perfil diferente.

Importante

Para evitar comportamientos inesperados, usa un solo identificador por objeto de atributos de usuario. Proporcionar múltiples identificadores que hagan referencia a diferentes perfiles de usuario puede provocar que los atributos se apliquen al perfil incorrecto.

Actualizar solo perfiles existentes

Si deseas actualizar solo perfiles de usuario existentes en Braze, debes pasar la clave _update_existing_only con un valor de true dentro del cuerpo de tu solicitud. Si se omite este valor, Braze crea un nuevo perfil de usuario si el external_id aún no existe.

Nota

Si estás creando un perfil de usuario solo con alias a través del endpoint /users/track, debes establecer _update_existing_only en false. Si omites este valor, Braze no crea el perfil solo con alias.

Importación de tokens de notificaciones push

Antes de importar tokens de notificaciones push a Braze, verifica si realmente lo necesitas. Cuando los SDK de Braze están implementados, gestionan los tokens de notificaciones push de forma automática sin necesidad de cargarlos a través de la API.

Si necesitas cargarlos a través de la API, pueden cargarse para usuarios identificados o usuarios anónimos. Esto significa que se necesita un external_id presente, o los usuarios anónimos deben tener la marca push_token_import establecida en true.

Nota

Al importar tokens de notificaciones push desde otros sistemas, no siempre se dispone de un external_id. Para mantener la comunicación con estos usuarios durante tu transición a Braze, puedes importar los tokens heredados para usuarios anónimos sin proporcionar external_id especificando push_token_import como true.

Al especificar push_token_import como true:

• external_id y braze_id no deben especificarse
• El objeto de atributo debe contener un token de notificaciones push
• Si el token ya existe en Braze, la solicitud se ignora; de lo contrario, Braze crea un perfil de usuario temporal y anónimo para cada token que te permita seguir enviando mensajes a estos individuos

Después de la importación, a medida que cada usuario inicie la versión de tu aplicación habilitada con Braze, Braze mueve automáticamente su token de notificaciones push importado a su perfil de usuario de Braze y limpia el perfil temporal.

Braze comprueba una vez al mes si hay algún perfil anónimo con la marca push_token_import que no tenga un token de notificaciones push. Si el perfil anónimo ya no tiene un token de notificaciones push, Braze elimina el perfil. Sin embargo, si el perfil anónimo todavía tiene un token de notificaciones push, lo que sugiere que el usuario real aún no ha iniciado sesión en el dispositivo con dicho token de notificaciones push, Braze no realiza ninguna acción.

Para más información, consulta Migración de tokens de notificaciones push.

Tipos de datos de atributos personalizados

Los siguientes tipos de datos pueden almacenarse como un atributo personalizado:

Consejo

Para orientación sobre cuándo usar un evento personalizado frente a un atributo personalizado, consulta Eventos personalizados y Atributos personalizados.

Ejemplo de matriz de objetos

Esta matriz de objetos te permite crear Segments basados en criterios específicos dentro de las estadías y personalizar tus mensajes usando los datos de cada estadía con plantillas de Liquid.

1
2
3
4

{"hotel_stays": [
  { "hotel_name": "Ocean View Resort", "check_in_date": "2023-06-15", "nights_stayed": 5 },
  { "hotel_name": "Mountain Lodge", "check_in_date": "2023-09-10", "nights_stayed": 3 }
]}

Para ejemplos de matrices de objetos que usan $add, $remove y $update, consulta Ejemplo de API de matriz de objetos y Ejemplo de SDK de matriz de objetos.

Campos del perfil de usuario de Braze

Importante

Los siguientes campos del perfil de usuario distinguen entre mayúsculas y minúsculas, así que asegúrate de hacer referencia a estos campos en minúsculas.

Consejo

Para una referencia orientada al cliente sobre los atributos estándar, organizada por categoría e incluyendo orientación para SDK, API, CSV e ingesta de datos en la nube, consulta Atributos estándar.

Los valores de idioma que se establecen explícitamente a través de esta API tienen prioridad sobre la información de configuración regional que Braze recibe automáticamente del dispositivo.

Ejemplo de solicitud de atributos de usuario

Este ejemplo contiene cuatro objetos de atributos de usuario, de un total de 75 objetos de atributos permitidos por llamada a la API.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "attributes" : [
    {
      "external_id" : "user1",
      "first_name" : "Alex",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Lee",
      "has_profile_picture" : false,
      "push_tokens": [{"app_id": "Your App Identifier", "token": "abcd", "device_id": "optional_field_value"}]

    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "first_name" : "Yuri",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Migrar tokens de notificaciones push

Si enviabas notificaciones push antes de integrar Braze, ya sea por tu cuenta o a través de otro proveedor, la migración de tokens de notificaciones push te permite seguir enviando notificaciones push a tus usuarios con tokens de notificaciones push registrados.

Migración automática a través del SDK

Después de integrar el SDK de Braze, los tokens de notificaciones push de los usuarios que han dado su consentimiento se migran automáticamente la próxima vez que abran tu aplicación. Hasta entonces, no puedes enviar notificaciones push a esos usuarios a través de Braze.

Como alternativa, puedes migrar tus tokens de notificaciones push manualmente, lo que te permite volver a captar a tus usuarios de forma más rápida.

Consideraciones sobre tokens web

Debido a la naturaleza de los tokens de notificaciones push web, ten en cuenta lo siguiente al implementar push para web:

Migración manual a través de la API

La migración manual de tokens de notificaciones push es el proceso de importar estas claves previamente creadas a tu plataforma Braze a través de la API.

Migra de forma programática tokens de iOS (APNs) y Android (FCM) a tu plataforma utilizando el endpoint users/track. Puedes migrar tanto usuarios identificados (usuarios con un ID externo asociado) como usuarios anónimos (usuarios sin un ID externo).

Nota

Braze asume que los tokens de notificaciones push importados son tokens de notificaciones push en primer plano válidos para tu aplicación y entorno.

Cuando importas tokens de iOS, Braze no almacena una puerta de enlace del servicio de notificaciones push de Apple (APN) (development o production) para ellos. Braze envía a estos tokens a través de la puerta de enlace configurada de tu aplicación. Si un token se generó para el otro entorno, APN lo rechaza con BadDeviceToken y el envío rebota.

Braze almacena una puerta de enlace para el token solo si el SDK registra posteriormente el mismo token e informa de una puerta de enlace.

Especifica el app_id de tu aplicación durante la migración de tokens de notificaciones push para asociar el token de notificaciones push adecuado con la aplicación correspondiente. Cada aplicación (iOS, Android, etc.) tiene su propio app_id, que se puede encontrar en la sección Identification de la página Claves de API. Asegúrate de usar el app_id de la plataforma correcta.

Importante

No es posible migrar tokens de notificaciones push web a través de la API. Esto se debe a que los tokens de notificaciones push web no siguen el mismo esquema que otras plataformas.

Si intentas migrar tokens de notificaciones push web de forma programática, es posible que veas un error como el siguiente: Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

Como alternativa a la migración por API, te recomendamos integrar el SDK y permitir que tu base de tokens se vuelva a llenar de forma natural.

• id externo presente
• id externo ausente

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

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },

    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    }
  ]
}'

Importar tokens de notificaciones push de iOS

Al migrar tokens de notificaciones push de iOS con /users/track, el campo gateway no se establece en el token de notificaciones push. Braze asume que los tokens importados a través de la API son tokens push de primer plano válidos, pero no puede determinar a qué entorno de APNs pertenece el token.

Sin el campo gateway, Braze utiliza la configuración de entorno alternativo configurada en tu aplicación al enviar notificaciones push. Esto puede provocar errores BadDeviceToken si el entorno real del token difiere del entorno alternativo configurado. Por ejemplo, un token de desarrollo enviado a través de la pasarela de producción fallará.

Para evitar problemas de entrega:

• Asegúrate de que la configuración de entorno de tu aplicación en el panel de Braze coincida con los tokens que estás importando.
• Para aplicaciones en producción, importa solo tokens de producción.
• Para entornos de prueba, verifica que tanto la configuración de tu aplicación como los tokens importados utilicen el entorno de desarrollo.

Nota

Los tokens registrados a través del SDK de Braze incluyen el campo gateway automáticamente, ya que el SDK detecta el entorno a partir de los derechos de tu aplicación.

Importar tokens de notificaciones push de Android

Importante

La siguiente consideración aplica solo para aplicaciones Android. Las aplicaciones iOS no requieren estos pasos porque esa plataforma solo tiene un framework para mostrar push, y las notificaciones push se muestran inmediatamente siempre que Braze tenga los tokens de notificaciones push y certificados necesarios.

Si necesitas enviar notificaciones push de Android a tus usuarios antes de que la integración del SDK de Braze esté completa, utiliza pares clave-valor para validar las notificaciones push.

Debes tener un receptor para gestionar y mostrar las cargas útiles de push. Para notificar al receptor de la carga útil de push, añade los pares clave-valor necesarios a la Campaign de push. Los valores de estos pares dependen del partner de push específico que hayas utilizado antes de Braze.

Nota

Para algunos proveedores de notificaciones push, Braze necesita aplanar los pares clave-valor para que puedan interpretarse correctamente. Para aplanar los pares clave-valor de una aplicación Android específica, contacta con tu administrador de éxito de cliente.

Preguntas frecuentes

¿Cómo encuentro usuarios tratados como correo no deseado o bloqueados para la mensajería?

Braze no proporciona una lista de correo no deseado específica en el panel. Braze bloquea perfiles de usuario individuales (“usuarios ficticios”) con más de cinco millones de sesiones, más de 20 000 nombres de eventos personalizados distintos o más de 20 000 nombres de productos distintos en compras, y deja de ingerir todos los datos entrantes para ese perfil tanto de los SDK como de la REST API. Si un identificador está bloqueado, /users/track puede devolver el error "provided external_id is blacklisted and disallowed". Esta redacción se toma textualmente de la respuesta de la API. Para encontrar perfiles bloqueados por sesiones excesivas, crea un Segment con el filtro Session Count configurado en more than 5,000,000, exporta el Segment como CSV y comprueba los campos del perfil en Engagement > Search users o con el endpoint /users/export/ids. No existe un filtro equivalente para nombres de eventos personalizados o nombres de productos distintos, así que contacta a tu director de cuentas de Braze para identificar perfiles bloqueados por esas razones. Para obtener más información, consulta Bloqueo de correo no deseado.