Objeto de atributos del usuario

Una solicitud a la API con cualquier campo en el 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 del perfil de usuario de Braze (enumerados a continuación o cualquiera de los que aparecen en la sección de campos del 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 de usuario externo
• Alias de usuario

Nota

Para los atributos personalizados de matriz normales, utiliza add y remove (sin $).

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

Utiliza este formato cuando necesites añadir, eliminar o actualizar objetos dentro de una matriz existente conservando 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 del perfil, establécelo en null. Algunos campos, como external_id y user_alias, no se pueden eliminar después de añadirse 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. Siempre que 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 se excluyen mutuamente. 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, utiliza el endpoint /users/alias/new.
• email tiene prioridad sobre phone. Si se incluyen tanto email como phone en el mismo objeto, Braze utiliza email como identificador. Esto significa que los atributos se aplican al perfil de usuario asociado a esa dirección de correo electrónico, aunque el número de teléfono pertenezca a otro perfil.

Importante

Para evitar comportamientos inesperados, utiliza un único identificador por objeto de atributos de usuario. Proporcionar varios identificadores que hagan referencia a perfiles de usuario diferentes puede hacer que los atributos se apliquen al perfil equivocado.

Actualizar solo perfiles existentes

Si quieres actualizar solo los perfiles de usuario existentes en Braze, debes pasar la clave _update_existing_only con un valor de true en el 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 vas a crear 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, comprueba si realmente necesitas hacerlo. Cuando los SDK de Braze están implementados, gestionan los tokens de notificaciones push automáticamente, sin necesidad de subirlos a través de la API.

Si necesitas subirlos a través de la API, puedes hacerlo para usuarios identificados o para usuarios anónimos. Esto significa que debe estar presente un external_id, o bien 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 hay un external_id disponible. Para mantener la comunicación con estos usuarios durante tu transición a Braze, puedes importar los tokens heredados de usuarios anónimos sin proporcionar external_id, especificando push_token_import como true.

Cuando especifiques 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 anónimo y temporal para cada token, de modo que puedas seguir enviando mensajes a estas personas

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

Braze realiza una comprobación una vez al mes para encontrar cualquier 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 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, Braze no hace nada.

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

Tipos de datos de atributos personalizados

Los siguientes tipos de datos pueden almacenarse como atributo personalizado:

Consejo

Para obtener orientación sobre cuándo utilizar 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 estancias y personalizar tus mensajes utilizando los datos de cada estancia 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 ver ejemplos de matrices de objetos que utilizan $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 ellos en minúsculas.

Consejo

Para consultar una referencia de los atributos estándar organizada por categorías, que incluye orientación para el SDK, la API, CSV y la ingesta de datos en la nube, consulta Atributos estándar.

Los valores de idioma establecidos 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 ya 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 mediante el 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 podrás 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 más rápidamente.

Consideraciones sobre los tokens web

Debido a la naturaleza de los tokens de notificaciones push web, asegúrate de tener en cuenta lo siguiente al implementar las notificaciones push para la Web:

Migración manual mediante la API

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

Migra mediante programación los tokens de iOS (APN) 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 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 adecuada. Cada aplicación (iOS, Android, etc.) tiene su propio app_id, que puedes encontrar en la sección Identificación de la página Claves de API. Asegúrate de utilizar 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 mediante programación, 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 mediante la API, te recomendamos que integres el SDK y permitas que tu base de tokens se vuelva a completar 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 APN pertenece el token.

Sin el campo gateway, Braze utiliza la configuración de 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 del gateway 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 vas a importar.
• Para las aplicaciones de producción, importa solo tokens de producción.
• Para los 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 entitlements de tu aplicación.

Importar tokens de notificaciones push de Android

Importante

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

Si debes enviar notificaciones push de Android a tus usuarios antes de completar la integración del SDK de Braze, utiliza pares clave-valor para validar las notificaciones push.

Debes tener un receptor que gestione y muestre las cargas útiles de las notificaciones push. Para notificar al receptor la carga útil de la notificación push, añade los pares clave-valor necesarios a la campaña push. Los valores de estos pares dependen del partner de notificaciones push específico que utilizabas 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, ponte en contacto con tu administrador de éxito de cliente.

Preguntas frecuentes

¿Cómo encuentro usuarios tratados como correo no deseado o bloqueados para recibir mensajes?

Braze no ofrece una lista específica de correo no deseado en el panel. Braze bloquea perfiles de usuario individuales (“usuarios ficticios”) que tienen más de cinco millones de sesiones, más de 20 000 nombres distintos de eventos personalizados o más de 20 000 nombres distintos de productos en compras, y deja de ingerir todos los datos entrantes de ese perfil, tanto desde los SDK como desde la REST API. Si un identificador está bloqueado, /users/track puede devolver el error "provided external_id is blacklisted and disallowed". Este texto se toma literalmente de la respuesta de la API. Para encontrar perfiles bloqueados por un exceso de sesiones, crea un Segment con el filtro Recuento de sesiones configurado en más de 5.000.000, exporta el Segment como CSV y verifica los campos del perfil en Participación > Buscar usuarios o con el endpoint /users/export/ids. No existe un filtro equivalente para los nombres distintos de eventos personalizados o de productos, así que ponte en contacto con tu director de cuentas de Braze para identificar los perfiles bloqueados por esos motivos. Para obtener más información, consulta Bloqueo de correo no deseado.