迁移到 OneSignal

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

​

先决条件

• 在 OneSignal 设置账户
• 邀请您的团队

​

迁移步骤

​

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

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

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

​

2. OneSignal 核心概念

• 用户 - 通过外部 ID 识别。用户由属性（标签、会话数据等）和订阅（推送、电子邮件、短信）组成。
• 订阅 - 指用户如何接收消息。有 4 种类型的订阅：
  • 移动：可以接收推送通知、应用内消息和 Live Activities。
  • 网页推送：可以接收网页推送通知。
  • 电子邮件：可以接收电子邮件通知。
  • 短信：可以接收短信通知。
• 细分 - 共享共同属性的用户组。
• 标签 - 自定义用户属性。
• 自定义事件 - 用户执行的操作。

​

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

​

使用外部 ID 识别用户

• Mobile SDK
• Web SDK

​

收集新的电子邮件和电话号码

• 电子邮件订阅：在我们的移动 SDK和网页 SDK中使用 addEmail 方法
• 短信订阅：在我们的移动 SDK和网页 SDK中使用 addSms 方法

​

4. 移除您的旧版实施

​

推送令牌冲突和格式

• 使用我们的前端移动 SDK获取设备的推送令牌标识符
• 使用我们的查看用户 API 获取设备的标识符

• iOS 推送 APNS 令牌格式：64 个字符，仅十六进制字符（0-9,a-f）。deviceToken.map {String(format: "%02x", $0)}.joined()
• Android 推送 FCM 令牌格式：通常 163 个字符，字母数字字符，可能包含连字符、冒号和下划线。

​

推送负载处理

​

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

• 不要让多个 SDK 生成推送令牌。 让 OneSignal 处理，如需要可与您的旧系统共享令牌。
  • 使用前端 SDK或查看用户 API
• 更新负载过滤器，使您的旧版 SDK 不处理 OneSignal 推送。
  • OneSignal 在其 rawPayload 中使用 "custom" 键（文档）。
  • 在 NotificationCompat（Android）中检查此键。
• 决定哪个提供商处理哪些类型的通知。
• 设置明确的截止日期并为旧版系统制定淘汰计划。
  • 为您发送的每种类型的通知创建通知模板。
  • 设置您的旧提供商向使用旧版本应用的用户发送消息，OneSignal 向使用新版本应用的用户发送消息。
  • 创建细分以定向特定用户组。

​

5. 网页推送迁移

• 由于浏览器安全限制，您无法导入网页推送订阅。OneSignal 将在用户返回时注册用户。
• 您必须在 OneSignal 接管之前取消注册您的旧推送服务工作器。

1. 移除旧版 SDK：网站上的代码和服务工作器文件。
2. 添加此代码以确保取消注册服务工作器。
3. 将 sw.js 替换为第三方服务工作器文件的名称。

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

​

6. 电子邮件和短信设置

​

是否需要电子邮件预热？

​

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

​

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

​

平台注意事项

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

​

导入步骤

1. 查看用户和订阅文档以了解。
2. 从旧系统导出测试用户数据。
3. 为 OneSignal 的创建用户 API 格式化数据。
4. 导入测试用户，成功测试后，保持流程在预发布检查清单中重复。

• token - 推送令牌或电子邮件地址或电话号码
• type - 订阅类型：iOSPush、AndroidPush、WebPush、Email、SMS
• external_id - 用户的唯一标识符。建议用于跟踪和分析。

  {
    "identity": {
      "external_id": "user_12345"
    },
    "subscriptions": [
      {
        "type": "iOSPush",
        "token": "7abcd49d0affb7426a8f1202420e8f4e2fc4df58e49501adc383f3bd66df8636"
      },
      {
        "type": "AndroidPush",
        "token": "dQGm89TZQXiTvLsRIj_GBo:APA91bpgqFgqkP2qYvV1uW2kdK5Z3TjgCXB_1jkL6VJrgH3hoYn16MvFY19tzDE4OuSgKjYC7itbFpSJYHBfKLWt-xZYBpgCVhYn9K5neV_9-Zj7s9mOSjRUJ2IwEwVSYhR-j5ICF9WB"
      },
      {
        "type": "Email",
        "email": "test@example.com"
      },
      {
        "type": "SMS",
        "phone_number": "+1234567890"
      }
    ]
  }

​

7. 测试迁移

1. 在 OneSignal SDK 中启用调试日志。
2. 在所有平台（Android、iOS、网页等）的真实设备上测试。
3. 验证前台和后台通知处理。

• 在添加 OneSignal SDK 之前从 OneSignal 向导入的用户发送测试通知。
  • 您应该在 iOS 上收到推送，但不会获得确认投递或点击分析。
  • 如果您有另一个推送 SDK 且尚未实施负载处理要求，您可能会在 Android 上收到推送。通知可能缺少数据，点击时无法按预期工作。
• 在添加 OneSignal SDK 之后从 OneSignal 向导入的用户发送测试通知。
  • 您应该在 Android 和 iOS 上都收到推送，以及确认投递和点击分析。
• 测试应用在不同状态下的通知行为。
• 验证深度链接和自定义操作正常工作。

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

​

发布前检查清单

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

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

​

发布您的应用/网站

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

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

​

监控结果

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

• 标记应用发布日期。
• 与您的开发人员沟通：
  • 采用了哪种迁移路径（干净或分阶段迁移）。
  • 是否导入了用户？
• 如果遵循干净迁移：
  • 在之前的平台中，创建继续活跃的用户细分或群组。检查他们的会话时间、接收的消息和点击事件。
  • 只有未更新应用的用户应该继续活跃并包含在此组中。
  • 继续从您之前的提供商向这些用户发送推送和应用内消息，温和地推动他们更新。
  • 停止从之前的提供商发送，直到您准备好完全移至 OneSignal。
• 如果遵循分阶段迁移：
  • 在之前的平台中，创建拥有 OneSignal 之前旧应用版本的用户细分或群组。
  • 继续从您之前的提供商向这些旧应用用户发送推送和应用内消息，温和地推动他们更新。
  • 停止从之前的提供商发送，直到您准备好完全移至 OneSignal。
  • 在下次应用发布时移除之前推送提供商的代码。