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

> 从其他消息提供商迁移到 OneSignal，包含 SDK 集成、用户导入、分阶段推出和测试指导。

本指南介绍如何从当前消息平台迁移到 OneSignal，同时将中断降至最低。

适用于：

* 实施 OneSignal SDK 的**开发人员**
* 管理活动和分析的**营销人员**

***

## 先决条件

开始之前：

* 在 [OneSignal](https://onesignal.com) 设置账户
* [邀请您的团队](./manage-team-members)

***

## 迁移步骤

### 1. 审计您当前的消息设置

在迁移之前，清点您当前的实施情况：

**对于开发人员：**

* 您支持的平台：iOS、Android、Web、电子邮件、SMS 等。
* 处理推送和应用内消息事件的代码：
  * 前台显示和点击处理
  * 推送、电子邮件等的深度链接使用
  * 推送令牌和负载处理
* 您如何收集电子邮件地址、电话号码、推送令牌等。
* 电子邮件域名和 DNS 所有权
* SMS 发送方和选择加入机制

**对于营销人员：**

* 您发送的消息类型（交易、营销等）及各类型的模板
* 您如何细分和定向用户
* 您跟踪的分析或转化指标

### 2. 将您的术语映射到 OneSignal

大多数消息平台在不同名称下共享相似的概念。以下是 OneSignal 术语与您可能已在使用的术语的对应关系：

| Your platform                           | OneSignal term                  | Details                          |
| --------------------------------------- | ------------------------------- | -------------------------------- |
| User / contact / profile                | [User](./users)                 | 通过外部 ID 识别。包含属性和订阅。              |
| Push token, email address, phone number | [Subscription](./subscriptions) | 用户可以接收消息的渠道（移动推送、网页推送、电子邮件、SMS）。 |
| Audience, cohort, list                  | [Segment](./segmentation)       | 基于共同属性或行为的动态用户组。                 |
| Custom attribute, user property         | [Tag](./add-user-data-tags)     | 附加到用户的键值对，用于定向和个性化。              |
| Tracked action, analytics event         | [Custom Event](./custom-events) | 用户执行的操作，用于细分和触发消息。               |

### 3. 添加 OneSignal SDK（开发人员）

在您的移动应用和/或网站中设置 OneSignal SDK：

<Columns cols={2}>
  <Card title="移动 SDK 设置" icon="mobile" href="./mobile-sdk-setup">
    应用内消息必需，iOS 和 Android 推送通知推荐使用。
  </Card>

  <Card title="Web SDK 设置" icon="globe" href="./web-sdk-setup">
    网页推送通知必需。
  </Card>
</Columns>

集成 SDK 后，使用以下方法识别用户并收集订阅数据：

* **`login`** — 设置[外部 ID](./users#external-id)以在设备和渠道之间识别用户。
* **`addEmail`** — 从您的应用或网站收集的地址创建电子邮件订阅。
* **`addSms`** — 从您的应用或网站收集的电话号码创建 SMS 订阅。

有关实施详情，请参阅 SDK 参考文档：

<Columns cols={2}>
  <Card title="移动 SDK 参考" icon="mobile" href="./mobile-sdk-reference">
    `login`、`addEmail`、`addSms`、推送令牌访问和通知监听器的方法。
  </Card>

  <Card title="Web SDK 参考" icon="globe" href="./web-sdk-reference">
    `login`、`addEmail`、`addSms` 和网页推送事件处理的方法。
  </Card>
</Columns>

### 4. 移除您的旧版实施

迁移有两种路径：

* **干净迁移** — 完全移除旧 SDK，在单次应用发布中用 OneSignal 替换。这是推荐的方法。
* **分阶段迁移** — 临时保留两个 SDK，根据应用版本向不同用户组从各提供商发送。仅在无法在一次发布中移除旧 SDK 时使用。

无论哪种情况，都要移除收集推送令牌、电子邮件地址和电话号码的旧版方法和 API。推送令牌收集尤其可能与 OneSignal SDK 产生冲突。

#### 推送令牌冲突和格式

移除所有生成推送令牌的旧版代码。仅允许 OneSignal 生成推送令牌，这在 SDK 初始化时自动发生。

如需要，使用我们的 SDK 获取令牌并将其发送到您的其他提供商或后端。执行此操作的方法：

* 使用我们的[前端移动 SDK](./mobile-sdk-reference#user-pushsubscription-token) 获取设备的推送令牌标识符
* 使用我们的[查看用户](/reference/view-user) API 获取设备的标识符

<Note>
  推送令牌格式因平台而异（iOS APNS 与 Android FCM）。详情请参阅[推送令牌格式](./osnotification-payload#push-token-formats)。
</Note>

#### Firebase Messaging SDK 冲突

如果您的应用包含 Firebase Messaging SDK（`firebase_messaging` 或自定义 `FirebaseMessagingService`），它可能会在 OneSignal 处理 FCM 消息之前拦截它们。这会导致通知在 OneSignal 中显示为"Delivered"但从未出现在设备上。

解决此问题：

* 从 `AndroidManifest.xml` 中移除旧版 Firebase 接收器。
* 不要调用 `FirebaseMessaging.getToken()` 或 `FirebaseMessaging.deleteToken()`。
* 确保 OneSignal 是唯一管理推送令牌生命周期的 SDK。

完整排查步骤请参阅 [Firebase Messaging SDK 冲突](./notifications-show-successful-but-are-not-being-shown#firebase-messaging-sdk-conflict)。

#### 推送负载处理

如果并行使用 OneSignal 和另一个推送提供商，您需要防止您的其他 SDK 处理 OneSignal 通知以避免重复。

OneSignal 的推送负载在 `rawPayload` 中包含一个 `"custom"` 键，用于将其与其他提供商区分。如果同时运行两个 SDK，请更新您的通知处理程序以检查此键，以防止旧版 SDK 处理 OneSignal 通知。详情请参阅 [OSNotification 负载](./osnotification-payload)参考文档。

#### 分阶段迁移（仅限移动应用）

一种常见方法是继续从旧提供商向使用旧版应用的用户发送，从 OneSignal 向使用新版应用的用户发送。但如果您必须临时保留两个 SDK：

* 让 OneSignal 专门管理推送令牌。如需要可与旧系统共享令牌（见上文[推送令牌冲突](#push-token-conflicts--format)）。
* 更新负载过滤器，使您的旧版 SDK 忽略 OneSignal 推送（见上文[推送负载处理](#push-payload-handling)）。
* 从旧提供商向使用旧版应用的用户发送，从 OneSignal 向使用新版应用的用户发送。
* 设置明确的截止日期和淘汰计划。

### 5. 网页推送迁移

如果您使用相同的 HTTPS 站点[来源](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)，订阅者将在下次访问时静默添加到 OneSignal——不会显示提示，他们可以立即接收推送。由于浏览器安全限制，网页推送订阅无法导入。

在 OneSignal 接管之前，您必须取消注册旧推送服务工作器：

1. 从您的网站移除旧版 SDK 代码和服务工作器文件。
2. 添加以下代码片段以取消注册旧服务工作器。将 `sw.js` 替换为您旧提供商服务工作器的文件名。

```javascript theme={null}
if ('serviceWorker' in navigator) {
  navigator.serviceWorker.getRegistrations().then(function(registrations) {
    for (let registration of registrations) {
      if (registration.active.scriptURL.includes("sw.js")) {
        registration.unregister();
      }
    }
  });
}
```

#### 在 OneSignal 应用之间迁移

如果您要将订阅者从一个 OneSignal 应用（App A）迁移到另一个（App B）：

* 网页推送订阅无法直接在应用之间转移。每个订阅都与您网站的域名（来源）和 OneSignal App ID 绑定。

* 要迁移，请将您网站的 OneSignal 初始化代码更新为使用 App B 的 appId：

```javascript theme={null}
OneSignal.init({
  appId: "YOUR_APP_B_ID",
});
```

* 当用户再次访问您的网站时，浏览器现有的推送权限将允许 OneSignal 在 App B 中静默注册他们。

* 不会出现新的权限提示，但用户必须至少访问一次您的网站才能在 App B 中创建订阅。

* 订阅者将继续出现在 App A 中，直到他们变为不活跃。

<Info>
  **最佳实践：** 一旦确认足够多的用户已迁移，停止从 App A 发送。监控两个应用中的订阅者数量以验证迁移进度。
</Info>

### 6. 电子邮件和 SMS 设置

如果您使用 OneSignal 发送电子邮件和/或 SMS，您需要遵循我们的[电子邮件设置](./email-setup)和 [SMS 设置](./sms-setup)指南。

将您当前的电子邮件发送域名迁移到 OneSignal 需要更新 DNS 记录。如需要，您可以在 OneSignal 中设置多个电子邮件发送方。

迁移 SMS 发送方可能需要时间。如需协助，请联系 `support@onesignal.com`。

### 7. 导入现有用户（可选）

导入在过去 270 天内在您的应用中活跃的已订阅用户将有助于最小化迁移期间的中断。

我们建议您首先导入已知的测试用户，然后在应用启动前导入其余用户。

#### 平台注意事项

* 电子邮件地址必须来自活跃和有效的用户。不要导入之前从未点击或打开过电子邮件的电子邮件地址。
* 电话号码必须采用特定格式，用户必须同意接收 SMS。
* iOS 订阅可以在导入后立即开始接收推送通知。通知点击跟踪和确认投递等功能需要我们的 SDK 在设备上活跃。
* Android/华为/亚马逊订阅必须在设备上有我们的 SDK 活跃才能接收通知，无论是通过自动更新还是手动更新。
* 网页订阅无法导入。如果您遵循上述[网页推送迁移](#5-web-push-migration)中的内容，网页推送订阅将在用户返回站点时通过我们的 SDK 创建并获取推送令牌。

#### 导入步骤

1. 查看[用户](./users)和[订阅](./subscriptions)文档。
2. 从旧系统导出测试用户数据。
3. 为 OneSignal 的[创建用户](/reference/create-user) API 格式化数据。
4. 首先导入测试用户。验证后，在发布前对剩余用户重复此流程。

每个用户需要一个 `external_id`（身份标识）和至少一个包含 `type` 和 `token`（或 `email`/`phone_number`）的订阅。必填字段、支持的订阅类型和示例负载请参阅[创建用户 API 参考](/reference/create-user)。

### 8. 测试迁移

彻底测试对于平稳过渡至关重要。

1. 在 OneSignal SDK 中启用[调试日志](./capturing-a-debug-log)。
2. 在所有平台（Android、iOS、Web 等）的真实设备上测试。
3. 验证前台和后台通知处理。

**开发人员和营销人员团队的测试场景：**

* 在**添加 OneSignal SDK 之前**从 OneSignal 向导入的用户发送测试通知。
  * 您应该在 iOS 上收到推送，但不会获得确认投递或点击分析。
  * 如果您有另一个推送 SDK 且尚未实施[负载处理](#push-payload-handling)要求，您可能会在 Android 上收到推送。通知可能缺少数据，点击时无法按预期工作。

* 在**添加 OneSignal SDK 之后**从 OneSignal 向导入的用户发送测试通知。
  * 您应该在 Android 和 iOS 上都收到推送，以及确认投递和点击分析。

* 测试应用在不同状态下的通知行为。

* 验证深度链接和自定义操作正常工作。

**如果使用多个提供商：**

* 从您当前的提供商和 OneSignal 两者发送。
* 检查重复通知。
* 验证每个提供商的通知正确显示。
* 测试用户登录/注销场景。

***

## 发布前检查清单

**对于营销人员：**

* 制定消息传递计划以提示应用更新
* 考虑使用旧系统的推送和应用内消息温和地提醒用户更新。

**对于开发人员：**

* 验证推送和应用内消息分析按预期工作。
  * 在 Android 和 iOS 上跟踪点击事件和确认投递。
* 验证对两个提供商发送的消息正确处理点击事件和前台接收事件。
* 如果导入用户，导出在过去 270 天内在您的应用中活跃的 Android 和 iOS 用户，以防止导入过期令牌。详情请参阅 [FCM 过期令牌 FAQ](./fcm-expired-token-faq)。

***

## 发布您的应用/网站

* 大多数用户的应用将自动更新到最新版本。
* 当用户打开您的更新应用时，如果权限已经授予——无论是通过必需的权限提示还是应用的通知设置——他们将不会被提示订阅推送通知。

**如果您没有导入用户：**

* 当用户打开应用的更新版本时，用户将在 OneSignal 中自动创建。如果之前已订阅，他们不会被提示推送。
* 您需要等待他们打开更新的应用，然后才能向他们发送消息。
* 继续从之前的推送提供商发送通知和应用内消息几天，直到足够的用户出现在 OneSignal 中。发送额外警报要求他们将应用更新到最新版本。

***

## 监控结果

**对于开发人员：**

* 监控部署后的错误率和崩溃。
* 注意意外的令牌失效。
* 检查 SDK 集成分析。

**对于营销人员：**

* 标记应用发布日期，并与您的开发人员确认采用了哪种迁移路径（[干净或分阶段](#4-remove-your-legacy-implementation)）以及是否导入了用户。
* 在您之前的平台中，创建尚未更新到新版应用的用户细分。继续从旧提供商向这组用户发送，推动他们更新。
* 一旦 OneSignal 中的订阅者数量趋于稳定，停止从之前的提供商发送。
* 如果遵循**分阶段迁移**，在截止日期后的下次应用发布中移除旧提供商的 SDK。

***

## 常见问题

### 我可以在当前推送提供商的同时运行 OneSignal 吗？

可以，但仅限临时情况。并行运行两个推送 SDK 可能导致令牌冲突和重复通知。如果您需要分阶段迁移，请遵循[分阶段迁移](#phased-migration-mobile-apps-only)指导以防止冲突，并设置明确的截止日期。

### 我可以导入网页推送订阅者吗？

不可以。浏览器安全限制阻止在提供商之间转移网页推送订阅。当您在网站上集成 OneSignal 时，现有订阅者将在下次访问时静默重新注册——不会显示新提示。请参阅[网页推送迁移](#5-web-push-migration)。

### 迁移后需要重新提示用户推送权限吗？

不需要。如果用户已向您的应用或网站授予推送权限，OneSignal 将使用现有权限。不会显示新提示。

### 是否需要电子邮件预热？

如果您的发送域名已建立发送声誉则不需要。仅当您使用专用 IP 地址时才需要预热。

### 我可以获得专用 IP 地址吗？

可以，具体取决于您的计划类型和发送量。联系您的客户经理了解详情。

### 我应该继续从旧提供商发送多长时间？

继续从旧提供商发送，直到大多数用户打开了包含 OneSignal SDK 的更新应用。监控两个系统中的订阅者数量，一旦数量趋于稳定就停止从旧提供商发送。

***

<Check>
  您已成功迁移到 OneSignal！对于有关迁移规划的策略问题，请联系我们的客户成功团队获取个性化指导。
</Check>

<Info>
  需要帮助？

  与我们的支持团队聊天或发送邮件至 `support@onesignal.com`

  请包含以下信息：

  * 您遇到的问题详情以及复现步骤（如有）
  * 您的 OneSignal 应用 ID
  * 外部 ID 或订阅 ID（如适用）
  * 您在 OneSignal 控制台中测试的消息 URL（如适用）
  * 任何相关的[日志或错误信息](/docs/cn/capturing-a-debug-log)

  我们很乐意为您提供帮助！
</Info>