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 e $identifier_value) y admiten actualizaciones in situ con $new_object.

Usa este formato cuando necesites añadir, eliminar o actualizar objetos dentro de una matriz existente preservando el resto del estado de la matriz. Para ver 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 se pueden eliminar una vez que se han 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 usar 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 automáticamente sin necesidad de cargarlos a través de la API.

Si determinas que necesitas cargarlos a través de la API, se pueden cargar para usuarios identificados o usuarios anónimos. Esto significa que debe estar presente un external_id, o los usuarios anónimos deben tener el indicador push_token_import establecido 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 atributos 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, lo que te permite seguir enviando mensajes a estas personas

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

Braze verifica una vez al mes si hay algún perfil anónimo con el indicador 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 aún 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, 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 se pueden almacenar como un atributo personalizado:

Consejo

Para obtener orientación sobre cuándo usar un evento personalizado en lugar de 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 estancias, y personalizar tus mensajes usando los datos de cada estancia con plantillas 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 ver 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 de 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 tus 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.

Alternativamente, 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, asegúrate de tener 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 creadas previamente a tu plataforma Braze a través de la API.

Migra programáticamente 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).

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 se ajustan al 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 que integres el SDK y permitas que tu base de tokens se repueble 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 de notificaciones push en 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 del entorno alternativo de 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 puerta de enlace de producción fallará.

Para evitar problemas de entrega:

• Asegúrate de que la configuración del 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 permisos 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 tiene un solo framework para mostrar push, y las notificaciones push se renderizan inmediatamente siempre que Braze tenga los tokens de notificaciones push y certificados necesarios.

Si debes 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 utilizaste antes de Braze.

Nota

Para algunos proveedores de notificaciones push, Braze necesita aplanar los pares clave-valor para que puedan interpretarse correctamente. Para aplanar pares clave-valor para una aplicación Android específica, ponte en contacto 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 dedicada 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 verifica 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 distintos o nombres de productos, 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.