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

# 用户模型和迁移指南

> 了解如何从 OneSignal 的设备中心模型迁移到新的用户中心 API 和 SDK，以实现更个性化的多渠道参与。

OneSignal 已从以设备为中心（Player ID）的模型迁移到围绕统一用户概念构建的以用户为中心的模型。本指南介绍了新模型，它与旧方法的不同之处，以及如何安全成功地迁移您的应用。

<Note>
  本指南适用于长期使用 OneSignal 移动 SDK 版本 2、3 或 4，或 Web SDK v15 的客户。

  如果您是新客户或已迁移到移动 SDK 版本 5 或 Web SDK v16，您可以跳过本指南并转到：

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

<Frame caption="使用用户模型的多渠道消息传递">
  <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="User Model multi-channel illustration" width="1280" height="720" data-path="images/docs/aafd98a-small-header-user-model.png" />
</Frame>

## 什么是用户模型？

用户模型让您能够针对真实用户在他们订阅的所有消息渠道（移动推送、Web 推送、邮件、短信和应用内）上进行定向，而不是针对单个设备。

每个用户：

* 拥有一个或多个身份别名（例如 external\_id、自定义别名）
* 可以拥有多个订阅，每个渠道或设备一个
* 包含标签、语言和活动历史等元数据

此模型简化了受众定向，支持个性化多渠道消息传递，并解锁了历程、用户级分析和实时身份解析等高级功能。

<Frame caption="Player 模型与用户模型对比">
  <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="Diagram showing difference between Player and User Models" width="4064" height="5214" data-path="images/docs/201ccdd-User_Model_Office_Visuals.png" />
</Frame>

***

## 关键概念

<Tabs>
  <Tab title="用户">
    **用户**代表真实的人。您可以使用系统生成的或自定义的别名来识别用户。

    * `onesignal_id`：由 OneSignal 自动生成
    * `external_id`：通过 SDK `login()` 或 API 设置（保留别名）
    * 自定义别名：例如 `user_id`、`email`、`facebook` 等

    了解更多：[用户](./users)
  </Tab>

  <Tab title="订阅">
    **订阅**代表用户订阅的渠道。这包括设备信息、令牌、会话历史和选择加入状态等元数据。

    * 移动和应用内
    * Web 推送
    * 邮件
    * 短信

    了解更多：[订阅](./subscriptions)
  </Tab>

  <Tab title="别名">
    别名将外部标识符（例如，您应用的用户 ID、Mixpanel ID）映射到 OneSignal 用户。您可以分配多个别名来统一跨平台的碎片化身份。

    * 特殊别名：
      * `onesignal_id`：自动管理，只读
      * `external_id`：可写，兼容旧版

    了解更多：[别名和外部 ID](./users)
  </Tab>
</Tabs>

***

## 迁移的好处

* **统一身份**：一个用户跨所有设备和渠道
* **高级消息传递**：强大功能，如历程、应用内登录跟踪和生命周期活动
* **清晰分段**：按标签、订阅状态、渠道参与度等对用户进行分组
* **简化的 API**：更少的端点，更一致的数据模型

***

## 迁移步骤

<Warning>
  用户模型不向后兼容。迁移是从 Player 模型到用户模型的**单向**操作。

  迁移前：

  * 在暂存环境中进行彻底测试
  * 仅在所有 SDK 和后端服务更新后才进行迁移
</Warning>

<Steps>
  <Step title="使用 external_id 统一用户">
    使用身份别名将现有的 player 记录链接到统一用户。

    **选项**：

    * SDK `login(externalId)`
    * API：[创建用户](/reference/create-user)、[更新用户](/reference/update-user)
    * CSV：[导入](./import)

    OneSignal 将自动合并相同外部 ID 下的订阅。
  </Step>

  <Step title="更新您的 OneSignal SDK">
    所有 OneSignal 移动 SDK v5+ 和 Web SDK v16+ 都支持用户模型。

    使用分阶段部署策略推出 SDK 更新以降低风险：

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

    查看[下方 SDK 支持表](#sdk-support)。
  </Step>

  <Step title="更新您的后端以使用新的用户 API">
    将弃用的 Player 模型 API 调用替换为新的用户模型等效调用。

    使用我们的 [API 参考](/reference/rest-api-overview) 和下面的表格将旧端点映射到新端点。
  </Step>
</Steps>

## SDK 支持和迁移指南

<Tabs>
  <Tab title="移动 SDK">
    | 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>
      有关旧 player 模型方法到新用户模型方法的映射，请参阅[移动 SDK 映射](./device-user-model-mobile-sdk-mapping)。
    </Note>
  </Tab>

  <Tab title="Web SDK">
    | 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>
      有关旧 player 模型方法到新用户模型方法的映射，请参阅[Web SDK 映射](./device-user-model-web-sdk-mapping)。
    </Note>
  </Tab>

  <Tab title="后端 SDK">
    | 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>

***

## API 参考

<Tabs>
  <Tab title="Player 模型（已弃用）">
    | 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="用户模型（新）">
    | 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) |

    ### 订阅 API

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

***

## 下一步

* 📘 查看我们的[用户](./users)和[订阅](./subscriptions)文档
* 🛠️ 在上线前更新 SDK 并在暂存环境中测试
* 💬 需要帮助？联系 `support@onesignal.com`

<Check>
  您现在已准备好构建由新用户模型支持的个性化多渠道消息传递体验！
</Check>

***