Objeto de atribuições do usuário

Uma solicitação de API com quaisquer campos no objeto de atributos cria ou atualiza um atributo desse nome com o valor dado no perfil de usuário especificado.

Use os nomes de campo do perfil de usuário da Braze (listados a seguir ou qualquer outro listado na seção de campos de perfil de usuário da Braze) para atualizar esses valores especiais no perfil de usuário no dashboard ou adicionar seus próprios dados de atributo personalizado ao usuário.

Corpo do 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 do usuário
• Aliases de usuário

Nota

Para atributos personalizados de array regular, use add e remove (sem $).

Para array de objetos (atributos personalizados aninhados), use $add, $remove e $update nos payloads de requisição /users/track. Esses operadores aplicam alterações no nível do objeto ao fazer a correspondência de identificadores ($identifier_key e $identifier_value) e suportam atualizações in-place com $new_object.

Use esse formato quando você precisar adicionar, remover ou atualizar objetos dentro de um array existente, preservando o restante do estado do array. Para exemplos completos de requisição, consulte Exemplo de API de array de objetos e Exemplo de SDK de array de objetos.

Para remover um atributo de perfil, defina-o como null. Alguns campos, como external_id e user_alias, não podem ser removidos depois de adicionados a um perfil de usuário.

Resolução de identificador

A menos que você esteja realizando uma importação anônima de token por push, cada objeto de atributos de usuário deve incluir pelo menos um identificador: external_id, user_alias, braze_id, email ou phone. Quando possível, inclua apenas um identificador por objeto para evitar ambiguidade sobre qual perfil de usuário está sendo atualizado ou criado.

Tenha em mente o seguinte ao usar identificadores:

• external_id e user_alias são mutuamente exclusivos. Incluir ambos no mesmo objeto de atributos de usuário retorna um erro. Para adicionar um alias a um usuário que já possui um external_id, use o endpoint /users/alias/new.
• email tem precedência sobre phone. Se tanto email quanto phone forem incluídos no mesmo objeto, a Braze usa email como identificador. Isso significa que os atributos são aplicados ao perfil de usuário associado a esse endereço de e-mail, mesmo que o número de telefone pertença a um perfil diferente.

Importante

Para evitar comportamentos inesperados, use um único identificador por objeto de atributos de usuário. Fornecer múltiplos identificadores que referenciam perfis de usuário diferentes pode levar à aplicação de atributos no perfil errado.

Atualizar apenas perfis existentes

Se você deseja atualizar apenas perfis de usuário existentes na Braze, deve passar a chave _update_existing_only com o valor true no corpo da sua requisição. Se esse valor for omitido, a Braze cria um novo perfil de usuário caso o external_id ainda não exista.

Nota

Se você está criando um perfil de usuário somente com alias através do endpoint /users/track, deve definir _update_existing_only como false. Se você omitir esse valor, a Braze não cria o perfil somente com alias.

Importação de token por push

Antes de importar tokens por push para a Braze, verifique se você realmente precisa. Quando os SDKs da Braze são implementados, eles lidam com os tokens por push automaticamente, sem necessidade de enviá-los pela API.

Se você identificar que precisa enviá-los pela API, eles podem ser enviados para usuários identificados ou usuários anônimos. Isso significa que ou um external_id precisa estar presente, ou os usuários anônimos devem ter o sinalizador push_token_import definido como true.

Nota

Ao importar tokens por push de outros sistemas, um external_id nem sempre está disponível. Para manter a comunicação com esses usuários durante sua transição para a Braze, você pode importar os tokens legados para usuários anônimos sem fornecer external_id, especificando push_token_import como true.

Ao especificar push_token_import como true:

• external_id e braze_id não devem ser especificados
• O objeto de atributo deve conter um token por push
• Se o token já existir na Braze, a requisição é ignorada; caso contrário, a Braze cria um perfil de usuário temporário e anônimo para cada token, para que você possa continuar enviando mensagens a esses indivíduos

Após a importação, à medida que cada usuário inicia a versão do seu app habilitada para Braze, a Braze move automaticamente o token por push importado para o perfil de usuário da Braze e limpa o perfil temporário.

A Braze verifica uma vez por mês para encontrar qualquer perfil anônimo com o sinalizador push_token_import que não possua um token por push. Se o perfil anônimo não tiver mais um token por push, a Braze exclui o perfil. No entanto, se o perfil anônimo ainda tiver um token por push, sugerindo que o usuário real ainda não fez login no dispositivo com o referido token por push, a Braze não faz nada.

Para saber mais, consulte Migração de tokens por push.

Tipos de dados de atributos personalizados

Os seguintes tipos de dados podem ser armazenados como atributo personalizado:

Dica

Para orientações sobre quando usar um evento personalizado versus um atributo personalizado, consulte Eventos personalizados e Atributos personalizados.

Exemplo de array de objetos

Esse array de objetos permite que você crie Segments com base em critérios específicos dentro das estadias e personalize suas mensagens usando os dados de cada estadia com templates 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 exemplos de array de objetos que usam $add, $remove e $update, consulte Exemplo de API de array de objetos e Exemplo de SDK de array de objetos.

Campos do perfil de usuário da Braze

Importante

Os seguintes campos do perfil de usuário diferenciam maiúsculas de minúsculas, portanto certifique-se de referenciar esses campos em letras minúsculas.

Dica

Para uma referência voltada ao cliente sobre atributos padrão organizada por categoria e com orientações para SDK, API, CSV e ingestão de dados na nuvem, consulte Atributos padrão.

Valores de idioma definidos explicitamente por esta API têm precedência sobre as informações de locale que a Braze recebe automaticamente do dispositivo.

Exemplo de requisição de atributos de usuário

Este exemplo contém quatro objetos de atributos de usuário, de um total de 75 objetos de atributos permitidos por chamada de 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 por push

Se você estava enviando notificações por push antes de integrar a Braze, seja por conta própria ou por meio de outro provedor, a migração de tokens por push permite que você continue enviando notificações por push para seus usuários com tokens por push registrados.

Migração automática pelo SDK

Depois de integrar o SDK da Braze, os tokens por push dos seus usuários que optaram por receber são migrados automaticamente na próxima vez que eles abrirem o app. Até lá, você não poderá enviar notificações por push para esses usuários pela Braze.

Como alternativa, você pode migrar seus tokens por push manualmente, permitindo re-engajar seus usuários mais rapidamente.

Considerações sobre tokens web

Devido à natureza dos tokens por push web, considere os pontos a seguir ao implementar push para web:

Migração manual pela API

A migração manual de tokens por push é o processo de importar essas chaves previamente criadas para a plataforma da Braze por meio da API.

Migre programaticamente tokens iOS (APNs) e Android (FCM) para a sua plataforma usando o endpoint users/track. Você pode migrar tanto usuários identificados (usuários com um ID externo associado) quanto usuários anônimos (usuários sem um ID externo).

Nota

A Braze assume que os tokens por push importados são tokens por push de primeiro plano válidos para o seu app e ambiente.

Quando você importa tokens iOS, a Braze não armazena um gateway do serviço de Notificações por Push da Apple (APN) (development ou production) para eles. A Braze envia para esses tokens por meio do gateway configurado do seu app. Se um token foi gerado para o outro ambiente, o APN o rejeita com BadDeviceToken, e o envio sofre bounce.

A Braze armazena um gateway para o token somente se o SDK registrar posteriormente o mesmo token e informar um gateway.

Especifique o app_id do seu app durante a migração de tokens por push para associar o token por push apropriado ao app correto. Cada app (iOS, Android, etc.) tem seu próprio app_id, que pode ser encontrado na seção Identification da página API Keys. Certifique-se de usar o app_id da plataforma correta.

Importante

Não é possível migrar tokens por push web pela API. Isso ocorre porque os tokens por push web não seguem o mesmo esquema de outras plataformas.

Se você está tentando migrar tokens por push web de forma programática, poderá ver um erro como o seguinte: Received '400: Invalid subscription auth' sending to 'https://fcm.googleapis.com/fcm/send

Como alternativa à migração por API, recomendamos que você integre o SDK e permita que sua base de tokens se repopule naturalmente.

• 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 por push do iOS

Ao migrar tokens por push do iOS com /users/track, o campo gateway não é definido no token por push. A Braze assume que os tokens importados pela API são tokens por push de primeiro plano válidos, mas não consegue determinar a qual ambiente APNs o token pertence.

Sem o campo gateway, a Braze usa a configuração de ambiente de fallback do seu app ao enviar notificações por push. Isso pode resultar em erros BadDeviceToken se o ambiente real do token for diferente do fallback configurado. Por exemplo, um token de desenvolvimento enviado pelo gateway de produção falhará.

Para evitar problemas de entrega:

• Certifique-se de que a configuração de ambiente do seu app no dashboard da Braze corresponda aos tokens que você está importando.
• Para apps em produção, importe apenas tokens de produção.
• Para ambientes de teste, verifique se tanto a configuração do app quanto os tokens importados usam o ambiente de desenvolvimento.

Nota

Tokens registrados pelo SDK da Braze incluem o campo gateway automaticamente, pois o SDK detecta o ambiente a partir dos entitlements do seu app.

Importar tokens por push do Android

Importante

A consideração a seguir se aplica apenas a apps Android. Apps iOS não requerem essas etapas porque essa plataforma possui apenas um framework para exibir push, e as notificações por push são renderizadas imediatamente, desde que a Braze tenha os tokens por push e certificados necessários.

Se você precisa enviar notificações por push Android para seus usuários antes que a integração do SDK da Braze esteja concluída, use pares de chave-valor para validar as notificações por push.

Você deve ter um receptor para processar e exibir cargas úteis de push. Para notificar o receptor sobre a carga útil de push, adicione os pares de chave-valor necessários à Campaign de push. Os valores desses pares dependem do parceiro de push específico que você usava antes da Braze.

Nota

Para alguns provedores de notificações por push, a Braze precisa nivelar os pares de chave-valor para que eles possam ser interpretados corretamente. Para nivelar pares de chave-valor para um app Android específico, entre em contato com seu gerente de sucesso do cliente.

Perguntas frequentes

Como encontro usuários tratados como spam ou bloqueados para envio de mensagens?

A Braze não fornece uma lista de spam dedicada no dashboard. A Braze bloqueia perfis de usuários individuais (“dummy users”) com mais de cinco milhões de sessões, mais de 20.000 nomes distintos de eventos personalizados ou mais de 20.000 nomes distintos de produtos em compras, e para de ingerir todos os dados recebidos para esse perfil, tanto dos SDKs quanto da REST API. Se um identificador estiver bloqueado, /users/track pode retornar o erro "provided external_id is blacklisted and disallowed". Essa mensagem é extraída literalmente da resposta da API. Para encontrar perfis bloqueados por excesso de sessões, crie um Segment com o filtro Session Count definido como mais de 5.000.000, exporte o Segment como CSV e verifique os campos do perfil em Engajamento > Pesquisar usuários ou com o endpoint /users/export/ids. Não há um filtro equivalente para nomes distintos de eventos personalizados ou nomes de produtos, então entre em contato com o gerente de conta da Braze para identificar perfis bloqueados por esses motivos. Para saber mais, consulte Bloqueio de spam.