rastreia usuários

Use esse endpoint para registrar eventos e compras personalizados e atualizar as atribuições do perfil do usuário.

Pré-requisitos

Para usar esse endpoint, você precisará de uma chave de API com a permissão users.track.

Os clientes que usam a API para chamadas de servidor para servidor talvez precisem permitir a lista rest.iad-01.braze.com se estiverem protegidos por um firewall.

Limite de taxa

Starting on October 28th, 2024, we apply a base speed limit of 3,000 requests per three seconds to this endpoint for all customers. Each /users/track request can contain up to 75 event objects, 75 attribute objects, and 75 purchase objects. Each object (event, attribute, and purchase arrays) can update one user each. In total, this means a maximum of 225 users can be updated in a single call. In addition, a single user profile can be updated by multiple objects.

Different limits apply to customers who have purchased Monthly Active Users - CY 24-25. For details on these limits, see Monthly Active Users - CY 24-25 limits.

See our page on API rate limits for details, and reach out to your customer success manager if you need your limit increased.

Corpo da solicitação

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 solicitação

Exemplos de solicitações

Atualizar um perfil de usuário por endereço de e-mail

É possível atualizar um perfil de usuário por endereço de e-mail usando o ponto de extremidade /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": "test@braze.com",
            "string_attribute": "fruit",
            "boolean_attribute_1": true,
            "integer_attribute": 26,
            "array_attribute": [
                "banana",
                "apple"
            ]
        }
    ],
    "events": [
        {
            "email": "test@braze.com",
            "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": "test@braze.com",
            "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"
            }
        }
    ]
}'

Atualizar um perfil de usuário por número de telefone

Você pode atualizar um perfil de usuário por número de telefone usando o endpoint /users/track. Esse endpoint só funciona se você incluir um número de telefone 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"
            ]
        }
    ],
}'

Definir grupos de inscrições

Este exemplo mostra como criar um usuário e definir seu grupo de inscrições no objeto de atribuições do usuário.

A atualização do status da inscrição com esse ponto de extremidade atualizará o usuário especificado pelo endereço external_id (como User1) e atualizará o status da inscrição de todos os usuários com o mesmo e-mail desse usuário (User1).

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": "example@email.com",
    "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"
        }
      ]
    }
  ]
}'

Exemplo de solicitação para criar um usuário somente de alias

Você pode usar o ponto de extremidade /users/track para criar um novo usuário somente de alias, definindo a chave _update_existing_only com um valor de false no corpo da solicitação. Se esse valor for omitido, o perfil de usuário somente de alias não será criado. O uso de um usuário somente com alias garante que existirá um perfil com esse alias. Isso é especialmente útil ao criar uma nova integração, pois evita a criação de perfis de usuário 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@example.com"
        }
    ],
}'

Respostas

Ao usar qualquer uma das solicitações de API mencionadas acima, você deve receber uma das três respostas gerais a seguir: uma mensagem de sucesso, uma mensagem de sucesso com erros não fatais ou uma mensagem com erros fatais.

Envio de mensagens bem-sucedido

As mensagens bem-sucedidas receberão a seguinte resposta:

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

Mensagem bem-sucedida com erros não fatais

Se sua mensagem for bem-sucedida, mas tiver erros não fatais, como um objeto de evento inválido em uma longa lista de eventos, você receberá a seguinte resposta:

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

Para mensagens de sucesso, todos os dados não afetados por um erro na matriz errors ainda serão processados.

Envio de mensagens com erros fatais

Se sua mensagem tiver um erro fatal, você receberá a seguinte resposta:

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

Códigos de resposta a erros fatais

Para obter os códigos de status e as mensagens de erro associadas que serão retornadas se sua solicitação encontrar um erro fatal, consulte Erros e respostas fatais.

Se receber o erro “provided external_id is blacklisted and disallowed”, sua solicitação pode ter incluído um “usuário fictício”. Para saber mais, consulte Bloqueio de spam.

Perguntas frequentes

O que acontece quando são encontrados vários perfis com o mesmo endereço de e-mail?

Se o site external_id existir, o perfil atualizado mais recentemente com um ID externo terá prioridade para atualizações. Se o endereço external_id não existir, o perfil atualizado mais recentemente será priorizado para atualizações.

O que acontece se não houver nenhum perfil com o endereço de e-mail no momento?

Um novo perfil será criado e um usuário somente de e-mail será criado. Não será criado um alias. O campo de e-mail será definido como test@braze.com, conforme notado na solicitação de exemplo para atualizar um perfil de usuário por endereço de e-mail.

Como usar o site /users/track para importar dados de usuários antigos?

Você pode enviar dados por meio da API do Braze para um usuário que ainda não tenha usado seu app móvel para gerar um perfil de usuário. Se o usuário usar o aplicativo posteriormente, todas as informações após a identificação por meio do SDK serão mescladas com o perfil de usuário existente criado por meio da chamada à API. Qualquer comportamento de usuário registrado anonimamente pelo SDK antes da identificação será perdido ao ser mesclado com o perfil de usuário existente gerado pela API.

A ferramenta de segmentação incluirá esses usuários independentemente de seu engajamento com o app. Se quiser excluir usuários enviados por meio da API User que ainda não se engajaram com o app, adicione o filtro Session Count > 0.

Como o site /users/track lida com eventos duplicados?

Cada objeto de evento no vetor de eventos representa uma única ocorrência de um evento personalizado por um usuário em um momento designado. Isso significa que cada evento ingerido no Braze tem seu próprio ID de evento, de modo que os eventos “duplicados” são tratados como eventos separados e exclusivos.

Usuários ativos mensais CY 24-25

Para os clientes que adquiriram o Monthly Active Users - CY 24-25, o Braze gerencia diferentes limites de frequência em seu endpoint /users/track:

• Os limites de frequência são definidos de acordo com a atividade de ingestão de dados esperada em sua conta, que pode corresponder ao número de usuários ativos mensais adquiridos, ao setor, à sazonalidade ou a outros fatores.
• Além do limite de solicitações por hora, o Braze também impõe um limite de explosão no número de solicitações permitidas por segundo.
• Cada solicitação pode ter até 50 atualizações combinadas entre atributos, eventos ou objetos de compra.

Os limites atuais com base na ingestão esperada podem ser encontrados no dashboard em Settings > APIs and Identifiers > API limits. Podemos modificar os limites de frequência para proteger a estabilidade do sistema ou permitir o aumento da taxa de transferência de dados em sua conta. Entre em contato com o suporte da Braze ou com o seu gerente de sucesso do cliente em caso de dúvidas ou preocupações relacionadas ao limite de solicitação por hora ou por segundo e às necessidades da sua empresa.