> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Aliases

> Aprenda a usar aliases personalizados no OneSignal para identificar e rastrear usuários em diferentes plataformas e dispositivos usando seus próprios identificadores únicos. Aliases ajudam a unificar dados de usuários de múltiplas fontes e são essenciais para integrações, gerenciamento de dados de usuários e mensagens transacionais.

Aliases personalizados permitem que você atribua identificadores chave-valor personalizados a usuários no OneSignal, possibilitando rastreamento e identificação de usuários multiplataforma usando seus próprios IDs internos.

<Warning>
  **Importante**: Você deve definir um [ID Externo](./users) **antes** de usar aliases personalizados.

  O OneSignal usa um `onesignal_id` único para identificar usuários. Este ID só permanece consistente entre [Assinaturas](./subscriptions) se elas tiverem o mesmo `external_id`.

  Aliases personalizados **não** vinculam Assinaturas—eles dependem do `external_id` para funcionar corretamente. Sem ele, os aliases não serão associados ao mesmo usuário entre dispositivos ou plataformas.
</Warning>

***

## O que é um alias personalizado?

Um alias personalizado é um par `chave : valor` onde:

* O `alias_label` (chave) é um identificador consistente e estático em todos os usuários (ex: `facebook_id`, `firebase_id`, `crm_user_id`).
* O `alias_id` (valor) é o ID específico do usuário para esse rótulo (ex: `facebook_id: 3453443`, `firebase_id: test3555`).

Isso permite vincular registros de usuários do OneSignal a identificadores de suas outras plataformas ou bancos de dados.

***

## Por que usar aliases?

1. Identificar usuários em múltiplas plataformas e bancos de dados.
2. Enviar mensagens transacionais direcionadas usando a [API REST Create Message](/reference/create-message).
3. Buscar, atualizar ou excluir usuários via APIs REST de Usuário.

***

## Como definir Aliases

Você pode definir aliases usando o SDK OneSignal ou via API REST.

### Usando o SDK

Siga estas etapas em seu aplicativo:

1. Defina o ID Externo
   Chame `OneSignal.login(externalId)` para associar o registro do usuário.

2. Defina aliases personalizados
   Use `OneSignal.User.addAlias(label, id)` para adicionar um único alias, ou `OneSignal.User.addAliases({ label1: id1, label2: id2 })` para definir múltiplos.

3. Logout (opcional)
   Use `OneSignal.logout()` para remover o ID externo e quaisquer aliases associados para aquele dispositivo ou sessão.

**Exemplo**:

```javascript theme={null}
OneSignal.login("user_123");

OneSignal.User.addAliases({
  facebook_id: "3453443",
  firebase_id: "test3555"
});

// Mais tarde, quando o usuário fizer logout
OneSignal.logout();
```

***

### Usando a API REST

Para definir aliases personalizados via API, use o endpoint [Create Alias](/reference/create-alias). Este método é tipicamente usado em sistemas backend para gerenciamento de usuários do lado do servidor.

**Exemplo de Solicitação**:

```json theme={null}
POST /aliases
{
  "subscription_id": "abc123",
  "aliases": {
    "facebook_id": "3453443",
    "crm_user_id": "XYZ789"
  }
}
```

***

## Melhores práticas

* Sempre defina o `external_id` antes de atribuir qualquer alias.
* Use rótulos estáveis e descritivos (ex: `crm_user_id`, `legacy_user_id`) para evitar confusão entre equipes.
* Evite usar informações sensíveis como endereços de email ou números de telefone como valores de alias.
* Use `logout()` para limpar aliases ao sair do dispositivo ou em eventos de troca de usuário.

***

<Check>
  Tutorial de aliases personalizados concluído!
  Próximos passos:

  * Revise nossa documentação de [Usuários](./users) e [Assinaturas](./subscriptions) se ainda não o fez.
  * Explore nossa documentação da [API REST](/reference/create-alias) para mais detalhes sobre o uso de aliases via API.
  * Configure [Integrações](./integrations) para sincronizar dados de usuários entre sistemas.
</Check>

***