> ## 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.

# User model & guia de migração

> Aprenda como migrar do modelo centrado em dispositivo do OneSignal para as novas APIs e SDKs centrados em usuário para engajamento multi-canal mais personalizado.

O OneSignal migrou de um modelo centrado em dispositivo (Player ID) para um modelo centrado em usuário construído em torno do conceito de um usuário unificado. Este guia explica o novo modelo, como ele difere da abordagem antiga, e como migrar seu app de forma segura e bem-sucedida.

<Note>
  Este guia é para clientes que vêm usando o OneSignal há muito tempo nas versões 2, 3 ou 4 dos nossos Mobile SDKs ou v15 do nosso Web SDK.

  Se você é um novo cliente ou já migrou para a versão 5 dos nossos Mobile SDKs ou v16 do nosso Web SDK, você pode pular este guia e ir para:

  * [Users](./users)
  * [Subscriptions](./subscriptions)
  * [Referência do Mobile SDK](./mobile-sdk-reference)
  * [Referência do Web SDK](./web-sdk-reference)
</Note>

<Frame caption="Mensagens multi-canal com o User Model">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/aafd98a-small-header-user-model.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=6d6b720a52fb316510a09653bae94385" alt="Ilustração multi-canal do User Model" width="1280" height="720" data-path="images/docs/aafd98a-small-header-user-model.png" />
</Frame>

## O que é o User Model?

O User Model permite que você direcione usuários reais através de todos os canais de mensagens aos quais eles se inscrevem (push móvel, push web, email, SMS e in-app) em vez de direcionar dispositivos individuais.

Cada User:

* Tem um ou mais Identity Aliases (ex: external\_id, alias personalizado)
* Pode ter múltiplas Subscriptions, uma para cada canal ou dispositivo
* Inclui metadados como tags, idioma e histórico de atividades

Este modelo simplifica o direcionamento de público, suporta mensagens multi-canal personalizadas e desbloqueia recursos avançados como Journeys, Análises em Nível de Usuário e Resolução de Identidade em Tempo Real.

<Frame caption="Player vs. User Model">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/201ccdd-User_Model_Office_Visuals.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=d7910b524fb166050871f47ea344141f" alt="Diagrama mostrando diferença entre Player e User Models" width="4064" height="5214" data-path="images/docs/201ccdd-User_Model_Office_Visuals.png" />
</Frame>

***

## Conceitos-chave

<Tabs>
  <Tab title="Users">
    Um **User** representa uma pessoa real. Você pode identificar um usuário usando aliases gerados pelo sistema ou personalizados.

    * `onesignal_id`: Auto-gerado pelo OneSignal
    * `external_id`: Definido via SDK `login()` ou a API (alias reservado)
    * Aliases Personalizados: ex: `user_id`, `email`, `facebook`, etc.

    Saiba mais: [Users](./users)
  </Tab>

  <Tab title="Subscriptions">
    Uma **Subscription** representa um canal ao qual o usuário está inscrito. Isso inclui metadados como informações do dispositivo, tokens, histórico de sessões e status de opt-in.

    * Mobile & In-app
    * Web Push
    * Email
    * SMS

    Saiba mais: [Subscriptions](./subscriptions)
  </Tab>

  <Tab title="Aliases">
    Aliases mapeiam identificadores externos (ex: ID de usuário do seu app, ID do Mixpanel) para um usuário OneSignal. Você pode atribuir múltiplos aliases para unificar identidades fragmentadas entre plataformas.

    * Aliases especiais:
      * `onesignal_id`: Auto-gerenciado, somente leitura
      * `external_id`: Gravável, compatível com legado

    Saiba mais: [Aliases & External ID](./users)
  </Tab>
</Tabs>

***

## Benefícios da migração

* **Identidade Unificada**: Um usuário através de todos os dispositivos e canais
* **Mensagens Avançadas**: Recursos poderosos como Journeys, rastreamento de login in-app e campanhas de ciclo de vida
* **Segmentação Limpa**: Agrupe usuários por tags, status de inscrição, engajamento de canal e mais
* **API Simplificada**: Menos endpoints, modelo de dados mais consistente

***

## Passos da migração

<Warning>
  O User Model não é compatível com versões anteriores. A migração é **unidirecional** do Player Model para o User Model.

  Antes de migrar:

  * Teste completamente com um ambiente de staging
  * Migre somente após todos os SDKs e serviços backend estarem atualizados
</Warning>

<Steps>
  <Step title="Unifique usuários com external_id">
    Use aliases de identidade para vincular registros de player existentes em usuários unificados.

    **Opções**:

    * SDK `login(externalId)`
    * API: [Create User](/reference/create-user), [Update User](/reference/update-user)
    * CSV: [Import](./import)

    O OneSignal fará auto-merge de subscriptions sob o mesmo External ID.
  </Step>

  <Step title="Atualize seus SDKs OneSignal">
    Todos os mobile SDKs OneSignal v5+ e web SDK v16+ suportam o User Model.

    Implante atualizações de SDK usando estratégias de implantação faseada para minimizar risco:

    * [Apple Phased Rollout](https://developer.apple.com/help/app-store-connect/update-your-app/release-a-version-update-in-phases)
    * [Google Play Staged Rollout](https://support.google.com/googleplay/android-developer/answer/6346149)

    Veja [tabela de suporte SDK abaixo](#sdk-support).
  </Step>

  <Step title="Atualize seu backend para usar as novas User APIs">
    Substitua chamadas de API do Player Model obsoletas pelos equivalentes do novo User Model.

    Use nossa [Referência da API](/reference/rest-api-overview) e tabelas abaixo para mapear endpoints antigos para novos.
  </Step>
</Steps>

## Suporte SDK & guias de migração

<Tabs>
  <Tab title="Mobile SDKs">
    | Platform     | SDK                                                                 | Migration Guide                                                                                            |
    | ------------ | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
    | Android      | [v5+](https://github.com/OneSignal/OneSignal-Android-SDK/releases)  | [Guide](https://github.com/OneSignal/OneSignal-Android-SDK/blob/user-model/main/MIGRATION_GUIDE.md)        |
    | iOS          | [v5+](https://github.com/OneSignal/OneSignal-iOS-SDK/releases)      | [Guide](https://github.com/OneSignal/OneSignal-iOS-SDK/blob/major_release_5.0.0/MIGRATION_GUIDE.md)        |
    | Unity        | [v5+](https://github.com/OneSignal/OneSignal-Unity-SDK/releases)    | [Guide](https://github.com/OneSignal/OneSignal-Unity-SDK/blob/user-model/main/MIGRATION_GUIDE_v3_to_v5.md) |
    | Flutter      | [v5+](https://github.com/OneSignal/OneSignal-Flutter-SDK/releases)  | [Guide](https://github.com/OneSignal/OneSignal-Flutter-SDK/blob/user_model/main/MIGRATION_GUIDE.md)        |
    | React Native | [v5+](https://github.com/OneSignal/react-native-onesignal/releases) | [Guide](https://github.com/OneSignal/react-native-onesignal/blob/major_release_5.0.0/MIGRATION_GUIDE.md)   |
    | .NET MAUI    | [v5+](https://github.com/OneSignal/OneSignal-DotNet-SDK/releases)   | [Guide](https://github.com/OneSignal/OneSignal-DotNet-SDK/blob/user-model/main/MIGRATION_GUIDE.md)         |

    <Note>
      Para um mapa de métodos antigos do player model para novos métodos do user model, veja [Mapeamento do Mobile SDK](./device-user-model-mobile-sdk-mapping).
    </Note>
  </Tab>

  <Tab title="Web SDKs">
    | Platform  | SDK                                                                 | Migration Guide                                                                            |
    | --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
    | Web       | [v16+](https://github.com/OneSignal/OneSignal-Website-SDK/releases) | [Guide](https://github.com/OneSignal/OneSignal-Website-SDK/blob/160000/MIGRATION_GUIDE.md) |
    | React     | [v3+](https://www.npmjs.com/package/react-onesignal)                | [Guide](https://github.com/OneSignal/react-onesignal/blob/main/MigrationGuide.md)          |
    | Vue 2 & 3 | [v2+/v3+](https://www.npmjs.com/package/@onesignal/onesignal-vue3)  | [Guide](https://github.com/OneSignal/onesignal-vue/blob/HEAD/MigrationGuide.md)            |
    | Angular   | [v2+](https://www.npmjs.com/package/onesignal-ngx)                  | [Guide](https://github.com/OneSignal/onesignal-ngx/blob/HEAD/MigrationGuide.md)            |

    <Note>
      Para um mapa de métodos antigos do player model para novos métodos do user model, veja [Mapeamento do Web SDK](./device-user-model-web-sdk-mapping).
    </Note>
  </Tab>

  <Tab title="Backend SDKs">
    | Language | SDK                                                                                  |
    | -------- | ------------------------------------------------------------------------------------ |
    | Node     | [@onesignal/node-onesignal](https://www.npmjs.com/package/@onesignal/node-onesignal) |
    | Python   | [onesignal-python-api](https://pypi.org/project/onesignal-python-api/)               |
    | Go       | [onesignal-go-api](https://pkg.go.dev/github.com/OneSignal/onesignal-go-api/v2)      |
    | .NET     | [OneSignalApi](https://www.nuget.org/packages/OneSignalApi)                          |
    | Rust     | [onesignal-rust-api](https://crates.io/crates/onesignal-rust-api)                    |
    | Ruby     | [onesignal](https://rubygems.org/gems/onesignal)                                     |
    | PHP      | [onesignal-php-api](https://packagist.org/packages/onesignal/onesignal-php-api)      |
  </Tab>
</Tabs>

***

## Referência da API

<Tabs>
  <Tab title="Player Model (Deprecated)">
    | Old API                                        | Replacement                                                                                    |
    | ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
    | [Add Device](/reference/add-a-device)          | [Create User](/reference/create-user) or [Create Subscription](/reference/create-subscription) |
    | [Edit Device](/reference/edit-device)          | [Update User](/reference/update-user) or [Update Subscription](/reference/update-subscription) |
    | [Delete Player](/reference/delete-user-record) | [Delete User](/reference/delete-user) or [Delete Subscription](/reference/delete-subscription) |
  </Tab>

  <Tab title="User Model (New)">
    | Action       | API                                     |
    | ------------ | --------------------------------------- |
    | Create       | [Create User](/reference/create-user)   |
    | View         | [View User](/reference/view-user)       |
    | Update       | [Update User](/reference/update-user)   |
    | Delete       | [Delete User](/reference/delete-user)   |
    | Add Alias    | [Create Alias](/reference/create-alias) |
    | Remove Alias | [Delete Alias](/reference/delete-alias) |

    ### Subscription APIs

    | Action   | API                                                       |
    | -------- | --------------------------------------------------------- |
    | Create   | [Create Subscription](/reference/create-subscription)     |
    | Update   | [Update Subscription](/reference/update-subscription)     |
    | Delete   | [Delete Subscription](/reference/delete-subscription)     |
    | Transfer | [Transfer Subscription](/reference/transfer-subscription) |
  </Tab>
</Tabs>

***

## Próximos passos

* 📘 Veja nossa documentação de [Users](./users) e [Subscriptions](./subscriptions)
* 🛠️ Atualize SDKs e teste em staging antes de ir ao ar
* 💬 Precisa de ajuda? Entre em contato com `support@onesignal.com`

<Check>
  Você está agora pronto para construir experiências de mensagens multi-canal personalizadas alimentadas pelo novo User Model!
</Check>

***