Rastrear usuarios

Utiliza este punto final para registrar eventos personalizados y compras, y actualizar los atributos del perfil de usuario.

Requisitos previos

Para utilizar este punto final, necesitarás una clave de API con el permiso users.track.

Es posible que los clientes que utilicen la API para llamadas de servidor a servidor tengan que permitir la lista rest.iad-01.braze.com si están detrás de un cortafuegos.

Límite de velocidad

A partir del 28 de octubre de 2024, aplicamos un límite de velocidad base de 3.000 solicitudes cada tres segundos a este punto final para todos los clientes. Cada solicitud /users/track puede contener hasta 75 objetos de evento, 75 objetos de atributo y 75 objetos de compra. Cada objeto (evento, atributo y matrices de compra) puede actualizar un usuario cada uno. En total, esto significa que se puede actualizar un máximo de 225 usuarios en una sola llamada. Además, el mismo perfil de usuario puede ser actualizado por varios objetos.

Se aplican límites diferentes a los clientes que han comprado Usuarios activos al mes - CY 24-25. Para más detalles sobre estos límites, consulta Usuarios activos al mes - Límites CY 24-25.

Consulta nuestra página sobre los límites de velocidad de la API para obtener más detalles, y ponte en contacto con tu responsable de satisfacción de los clientes si necesitas aumentar tu límite.

Cuerpo de la solicitud

1
2
Content-Type: application/json
Authorization: Bearer YOUR_REST_API_KEY

1
2
3
4
5
{
  "attributes": (optional, array of attributes object),
  "events": (optional, array of event object),
  "purchases": (optional, array of purchase object),
}

Parámetros de la solicitud

Ejemplos de solicitudes

Actualizar un perfil de usuario por correo electrónico

Puedes actualizar el perfil de un usuario por correo electrónico utilizando el punto final /users/track.

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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "email": "[email protected]",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2022-12-06T19:20:45+01:00",
            "properties": {
                "release": {
                    "studio": "FilmStudio",
                    "year": "2022"
                },
                "cast": [
                    {
                        "name": "Actor1"
                    },
                    {
                        "name": "Actor2"
                    }
                ]
            }
        },
        {
            "user_alias": {
                "alias_name": "device123",
                "alias_label": "my_device_identifier"
            },
            "app_id": "your_app_identifier",
            "name": "rented_movie",
            "time": "2013-07-16T19:20:50+01:00"
        }
    ],
    "purchases": [
        {
            "email": "[email protected]",
            "app_id": "your_app_identifier",
            "product_id": "product_name",
            "currency": "USD",
            "price": 12.12,
            "quantity": 6,
            "time": "2017-05-12T18:47:12Z",
            "properties": {
                "color": "red",
                "monogram": "ABC",
                "checkout_duration": 180,
                "size": "Large",
                "brand": "Backpack Locker"
            }
        }
    ]
}'

Actualizar un perfil de usuario por número de teléfono

Puedes actualizar un perfil de usuario por número de teléfono utilizando el punto final /users/track. Este punto final sólo funciona si incluyes un número de teléfono válido.

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_REST_API_KEY' \
--data-raw '{
    "attributes": [
        {
            "phone": "+15043277269",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 25,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
}'

Configurar grupos de suscripción

Este ejemplo muestra cómo crear un usuario y establecer su grupo de suscripción dentro del objeto de atributos de usuario.

La actualización del estado de suscripción con este punto final actualizará al usuario especificado por su external_id (como Usuario1) y actualizará el estado de suscripción de cualquier usuario con el mismo correo electrónico que ese usuario (Usuario1).

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
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "attributes": [
  {
    "external_id": "user_identifier",
    "email": "[email protected]",
    "email_subscribe": "subscribed",
    "subscription_groups": [{
      "subscription_group_id": "subscription_group_identifier_1",
      "subscription_state": "unsubscribed"
      },
      {
        "subscription_group_id": "subscription_group_identifier_2",
        "subscription_state": "subscribed"
        },
        {
          "subscription_group_id": "subscription_group_identifier_3",
          "subscription_state": "subscribed"
        }
      ]
    }
  ]
}'

Ejemplo de solicitud para crear un usuario sólo con alias

Puedes utilizar el punto final /users/track para crear un nuevo usuario de sólo alias estableciendo la clave _update_existing_only con un valor de false en el cuerpo de la solicitud. Si se omite este valor, no se creará el perfil de usuario de sólo alias. Utilizar un usuario de sólo alias garantiza que existirá un perfil con ese alias. Esto es especialmente útil cuando se crea una nueva integración, ya que evita la creación de perfiles de usuario duplicados.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
{
    "attributes": [
        {
            "_update_existing_only": false,
            "user_alias": {
                "alias_name": "example_name",
                "alias_label": "example_label"
            },
            "email": "[email protected]"
        }
    ],
}'

Respuestas

Al utilizar cualquiera de las solicitudes de API mencionadas, deberías recibir una de las tres respuestas generales siguientes: un mensaje correcto, un mensaje correcto con errores no fatales o un mensaje con errores fatales.

Mensaje correcto

Los mensajes correctos recibirán la siguiente respuesta:

1
2
3
4
5
6
{
  "message": "success",
  "attributes_processed": (optional, integer), if attributes are included in the request, this will return an integer of the number of external_ids with attributes that were queued to be processed,
  "events_processed": (optional, integer), if events are included in the request, this will return an integer of the number of events that were queued to be processed,
  "purchases_processed": (optional, integer), if purchases are included in the request, this will return an integer of the number of purchases that were queued to be processed,
}

Mensaje correcto con errores no fatales

Si tu mensaje tiene éxito pero tiene errores no fatales, como un objeto de evento no válido de una larga lista de eventos, recibirás la siguiente respuesta:

1
2
3
4
5
6
7
8
{
  "message": "success",
  "errors": [
    {
      <minor error message>
    }
  ]
}

En el caso de mensajes con éxito, se seguirán procesando los datos no afectados por un error en la matriz errors.

Mensaje con errores fatales

Si tu mensaje tiene un error fatal, recibirás la siguiente respuesta:

1
2
3
4
5
6
7
8
{
  "message": <fatal error message>,
  "errors": [
    {
      <fatal error message>
    }
  ]
}

Códigos de respuesta de error fatal

Para conocer los códigos de estado y los mensajes de error asociados que se devolverán si tu solicitud encuentra un error fatal, consulta Errores fatales y respuestas.

Si recibes el error “provided external_id is blacklisted and disallowed”, es posible que tu solicitud haya incluido un “usuario ficticio”. Para más información, consulta Bloqueo de correo no deseado.

Preguntas más frecuentes

¿Qué ocurre cuando se encuentran varios perfiles con la misma dirección de correo electrónico?

Si existe external_id, el perfil actualizado más recientemente con un ID externo tendrá prioridad para las actualizaciones. Si no existe external_id, se dará prioridad al perfil actualizado más recientemente.

¿Qué ocurre si no existe actualmente ningún perfil con la dirección de correo electrónico?

Se creará un nuevo perfil y un usuario sólo por correo electrónico. No se creará un alias. El campo de correo electrónico se configurará en [email protected], como se indica en el ejemplo de solicitud de actualización de un perfil de usuario por correo electrónico.

¿Cómo se utiliza /users/track para importar datos de usuario heredados?

Puedes enviar datos a través de la API de Braze de un usuario que aún no haya utilizado tu aplicación móvil para generar un perfil de usuario. Si el usuario utiliza posteriormente la aplicación, toda la información posterior a su identificación mediante el SDK se fusionará con el perfil de usuario existente que creaste mediante la llamada a la API. Cualquier comportamiento de usuario registrado anónimamente por el SDK antes de la identificación se perderá al fusionarse con el perfil de usuario existente generado por la API.

La herramienta de segmentación incluirá a estos usuarios independientemente de si han interactuado o no con la aplicación. Si quieres excluir a los usuarios subidos mediante la API de usuario que aún no han interactuado con la aplicación, añade el filtro Session Count > 0.

¿Cómo gestiona /users/track los eventos duplicados?

Cada objeto evento de la matriz de eventos representa una única ocurrencia de un evento personalizado por parte de un usuario en un momento determinado. Esto significa que cada evento ingestado en Braze tiene su propio ID de evento, por lo que los eventos “duplicados” se tratan como eventos separados y únicos.

Usuarios activos al mes CY 24-25

Para los clientes que hayan comprado Usuarios activos al mes - CY 24-25, Braze gestiona diferentes límites de velocidad en su punto final /users/track:

• Los límites de velocidad por hora se establecen en función de la actividad prevista de ingesta de datos en tu cuenta, que puede corresponder al número de usuarios activos al mes que hayas comprado, al sector, a la estacionalidad o a otros factores.
• Además del límite horario, Braze aplica un límite de ráfagas al número de solicitudes que pueden enviarse cada tres segundos.
• Cada solicitud puede contener hasta 50 actualizaciones combinadas de objetos de atributo, evento o compra.

Los límites actuales basados en la ingesta prevista se pueden encontrar en el panel en Configuración > API e identificadores > Panel de uso de API. Podemos modificar los límites de velocidad para proteger la estabilidad del sistema o permitir un mayor caudal de datos en tu cuenta. Ponte en contacto con el soporte de Braze o con tu administrador del éxito del cliente si tienes preguntas o dudas sobre el límite de solicitudes por hora o por segundo y las necesidades de tu empresa.