Criar novo alias de usuário

Use esse endpoint para adicionar novos aliases de usuário para usuários identificados existentes ou para criar novos usuários não identificados.

Podem ser especificados até 50 aliases de usuário por solicitação.

A adição de um alias de usuário para um usuário existente requer que um external_id seja incluído no novo objeto de alias de usuário. Se o external_id estiver presente no objeto, mas não houver nenhum usuário com esse external_id, o alias não será adicionado a nenhum usuário. Se um external_id não estiver presente, um usuário ainda será criado, mas precisará ser identificado posteriormente. Você pode fazer isso usando o endpoint “Identificação de usuários” e o endpoint users/identify.

A criação de um novo usuário somente de alias exige que o external_id seja omitido no novo objeto de alias de usuário. Depois que o usuário for criado, use o endpoint /users/track para associar o usuário somente de alias a atributos, eventos e compras, e o endpoint /users/identify para identificar o usuário com um external_id.

Quando alias_label e alias_name já existem

A combinação de alias_label e alias_name deve ser única em toda a sua base de usuários. Para saber mais, consulte Aliases de usuário.

Se você enviar uma solicitação em que o par alias_label e alias_name já existe para qualquer usuário (seja no mesmo usuário ou em outro), o endpoint ainda retornará uma resposta de sucesso (por exemplo, "aliases_processed": 1, "message": "success"). Nesse caso, nenhum novo alias é adicionado ao usuário na solicitação. Como o par alias_label e alias_name já está em uso, a solicitação não faz nenhuma alteração, e pode parecer que o alias nunca foi adicionado ao usuário em questão.

Pré-requisitos

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

Limite de frequência

Aplicamos um limite de frequência compartilhado de 20.000 solicitações por minuto a esse endpoint. Esse limite de frequência é compartilhado com os endpoints /users/delete, /users/identify, /users/merge e /users/alias/update, conforme documentado em Limites de frequência da API.

Corpo da solicitação

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

1
2
3
{
  "user_aliases" : (required, array of new user alias object)
}

Parâmetros de solicitação

Corpo da solicitação do endpoint com a especificação do novo objeto de alias de usuário

1
2
3
4
5
{
  "external_id" : (optional, string),
  "alias_name" : (required, string),
  "alias_label" : (required, string)
}

Exemplo de solicitação

1
2
3
4
5
6
7
8
9
10
11
12
curl --location --request POST 'https://rest.iad-01.braze.com/users/alias/new' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_REST_API_KEY' \
--data-raw '{
  "user_aliases" :[
    {
      "external_id": "external_identifier",
      "alias_name" : "example_name",
      "alias_label" : "example_label"
    }
  ]
}'

Resposta

Quando um alias é ignorado porque o mesmo alias_label e alias_name já existem para um usuário, o corpo da resposta ainda pode indicar sucesso. Consulte Quando alias_label e alias_name já existem para mais detalhes.

1
2
3
4
{
    "aliases_processed": 1,
    "message": "success"
}

Solução de problemas

Por que meus atributos não estão sendo atualizados depois que eu crio um alias de usuário usando esse endpoint?

Isso geralmente acontece quando /users/alias/new é seguido por uma solicitação separada de /users/track que tenta atualizar atributos por alias. A solicitação de rastreamento pode ser processada antes que a Braze consiga resolver de forma consistente o novo par alias_label e alias_name para um perfil, de modo que os atributos não são aplicados ao usuário esperado.

Abordagem recomendada: Use uma única chamada /users/track somente quando quiser criar um perfil somente de alias ou atualizar um perfil por um alias que já existe. No vetor attributes, coloque user_alias e os campos do perfil no mesmo objeto de atributos de usuário para que a Braze resolva o usuário e aplique a atualização em uma única etapa.

Defina _update_existing_only como false quando for necessário criar um perfil somente de alias a partir desse objeto. Se você omitir esse campo ao usar user_alias, a Braze assume o comportamento de somente atualização e não cria o perfil somente de alias. Se o alias já existir em um usuário no seu espaço de trabalho, a mesma solicitação atualizará esse perfil com os novos atributos.

Não é possível usar /users/track para adicionar um novo alias a um usuário existente identificado por external_id. Em um objeto de atributos de usuário, external_id e user_alias são mutuamente exclusivos. Para adicionar um alias a um usuário identificado, primeiro chame /users/alias/new. Depois que o alias estiver vinculado, você poderá atualizar esse perfil com /users/track usando o external_id ou o alias existente.

Por exemplo, o corpo de /users/track a seguir cria um perfil somente de alias se o alias ainda não existir, ou atualiza o perfil existente que já possui esse alias:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "attributes": [
    {
      "user_alias": {
        "alias_name": "[email protected]",
        "alias_label": "email"
      },
      "_update_existing_only": false,
      "string_attribute": "test_alias_only_update"
    }
  ]
}