Ir para o conteúdo
View in Postman (opens in new tab)

Criar novo alias de usuário

post

/users/alias/new

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

Você pode especificar até 50 aliases de usuário por solicitação.

Adicionar um alias de usuário a um usuário existente exige 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 não houver um external_id, o usuário ainda será criado, mas precisará ser identificado depois. Você pode fazer isso com a “Identificação de usuários” e o endpoint users/identify.

Criar um novo usuário somente de alias exige que o external_id seja omitido do 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.

Você pode enviar Campaigns disparadas por API para usuários por user_alias usando o endpoint /campaigns/trigger/send.

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 o mesmo usuário ou 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 da 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.

Solução de problemas

Por que meus atributos não são atualizados depois que crio um alias de usuário com este endpoint?

Isso costuma acontecer quando o /users/alias/new é seguido por uma solicitação /users/track separada que tenta atualizar atributos pelo alias. A solicitação de track pode ser processada antes que a Braze consiga associar de forma consistente o novo par alias_label e alias_name a um perfil. Por isso, os atributos não chegam 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 array attributes, coloque o user_alias e os campos do perfil no mesmo objeto de atributos do usuário. Assim, a Braze identifica o usuário e aplica a atualização em uma única etapa.

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

Não é possível usar o /users/track para adicionar um novo alias a um usuário existente identificado por external_id. Em um objeto de atributos do usuário, external_id e user_alias são mutuamente exclusivos. Para adicionar um alias a um usuário identificado, primeiro chame o /users/alias/new. Depois que o alias estiver vinculado, você pode atualizar esse perfil com o /users/track pelo external_id ou pelo 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á tem esse alias:

{
  "attributes": [
    {
      "user_alias": {
        "alias_name": "[email protected]",
        "alias_label": "email"
      },
      "_update_existing_only": false,
      "string_attribute": "test_alias_only_update"
    }
  ]
}

Você pode baixar o documento OpenAPI e usá-lo para validar esquemas. Para saber como, consulte Usar esquemas OpenAPI para validação de solicitações.

New Stuff!