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" : "Jon",
  "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 (REST API syntax)
  "my_array_of_objects_attribute": { "add": [{"key": "value"}] },
  // Removing from an array of objects (REST API syntax)
  "my_array_of_objects_attribute": { "remove": [{"$identifier_key": "key", "$identifier_value": "value"}] },
}

• ID de usuário externo
• Alias do usuário

Nota

Para solicitações da REST API para /users/track, use as chaves add, remove e update para operações de array. Chaves prefixadas com $ (como $add) são para cargas úteis de métodos do SDK.

Quando uma solicitação da REST API usa $add, $remove ou $update, a Braze pode retornar success sem aplicar a atualização do array.

Para mais detalhes, veja Exemplo de API de array de objetos e Exemplo de SDK de array de objetos.

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

Resolução de identificador

A menos que você esteja realizando uma importação de token por push anônimo, cada objeto de atributos de usuário deve incluir pelo menos um identificador: external_id, user_alias, braze_id, email ou phone. Sempre que 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 ambos email e phone forem incluídos no mesmo objeto, a Braze usa email como o 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 diferentes perfis de usuário pode levar a atributos sendo aplicados ao perfil errado.

Atualizar apenas os perfis existentes

Se desejar atualizar apenas os perfis de usuário existentes na Braze, passe a chave _update_existing_only com o valor true no corpo da solicitação. Se esse valor for omitido, a Braze cria um novo perfil de usuário se o external_id ainda não existir.

Nota

Se você estiver criando um perfil de usuário apenas 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 apenas com alias.

Importação de token por push

Antes de importar tokens por push para a Braze, verifique novamente se é necessário. Quando os SDKs da Braze são implementados, eles lidam com tokens por push automaticamente, sem a necessidade de fazer upload deles por meio da API.

Se achar que precisa fazer upload deles por meio da API, eles podem ser carregados para usuários identificados ou usuários anônimos. Isso significa que um external_id precisa estar presente ou que 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 a transição para a Braze, é possível 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 atribuição deve conter um token por push
• Se o token já existir na Braze, a solicitação é ignorada; caso contrário, a Braze cria um perfil de usuário anônimo temporário para cada token para permitir que você continue a enviar 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 automaticamente move seu token por push importado para seu perfil de usuário Braze e limpa o perfil temporário.

A Braze verifica uma vez por mês para encontrar qualquer perfil anônimo com a flag push_token_import que não tenha 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 um atributo personalizado:

Dica

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

Exemplo de array de objetos

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

Campos de perfil de usuário da Braze

Importante

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

Dica

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

Os valores de idioma que são definidos explicitamente através desta API têm precedência sobre as informações de localidade que a Braze recebe automaticamente do dispositivo.

Exemplo de solicitação de atribuição de usuário

Este exemplo contém quatro objetos de atributo de usuário, de um total de 75 objetos de atributo 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" : "Jon",
      "has_profile_picture" : true,
      "dob": "1988-02-14",
      "music_videos_favorited" : { "add" : [ "calvinharris-summer" ], "remove" : ["nickiminaj-anaconda"] }
    },
    {
      "external_id" : "user2",
      "first_name" : "Jill",
      "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" : "Alice",
      "has_profile_picture" : false
    },
    {
      "external_id": "user3",
      "subscription_groups" : [{"subscription_group_id" : "subscription_group_identifier", "subscription_state" : "subscribed"}]
    }
  ]
}

Migração de 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 token por push permite que você continue enviando notificações por push aos seus usuários com tokens por push registrados.

Migração automática através do SDK

Depois que você 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 seu app. Até lá, você não pode enviar notificações por push para esses usuários através da Braze.

Alternativamente, você pode migrar seus tokens por push manualmente, permitindo que você reengaje seus usuários mais rapidamente.

Considerações sobre tokens da web

Devido à natureza dos tokens por push da web, certifique-se de considerar o seguinte ao implementar push para a web:

Migração manual através da API

A migração manual de token por push é o processo de importação dessas chaves criadas anteriormente para sua plataforma Braze por meio da API.

Migre programaticamente os tokens do iOS (APNs) e do Android (FCM) para sua plataforma usando o endpoint users/track. É possível migrar tanto usuários identificados (usuários com um ID externo associado) quanto usuários anônimos (usuários sem um ID externo).

Especifique o app_id do seu app durante a migração do token por push para associar o token por push apropriado ao app apropriado. Cada app (iOS, Android, etc.) tem seu próprio app_id, que pode ser encontrado na seção Identificação da página Chaves de API. Confira se está usando o app_id da plataforma correta.

Importante

Não é possível migrar tokens por push da web por meio da API. Isso ocorre porque os tokens por push da web não estão em conformidade com o mesmo esquema de outras plataformas.

Se estiver tentando migrar tokens por push da 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 da API, recomendamos que você integre o SDK e permita que sua base de tokens seja preenchida 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"}
      ]
    }
  ]
}'

Importação de tokens por push do Android

Importante

A seguinte consideração se aplica apenas para apps Android. Apps iOS não requerem essas etapas porque essa plataforma tem 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 for necessário enviar notificações por push do Android aos seus usuários antes que a integração do SDK da Braze seja concluída, use pares de valores-chave para validar as notificações por push.

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

Nota

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