迁出 OneSignal？大型出海 App 安全迁移推送 SDK 的 9 款工具

在小型 App 中，OneSignal SDK 迁移只需要替换 1 个初始化调用和一个点击处理器。而在大型 App 中，OneSignal 散落在几十个地方：个人资料模块里设置的标签、登录鉴权中的外部用户 ID、导航里的点击处理器，以及结账流程某处的应用内消息触发器。

漏掉其中任何 1 处调用，App 都不会崩溃。但用户分群会悄悄偏移，深度链接只会打开首页，曾经把用户拉回来的推送也不再送达。对于依赖 FCM 和 APNs 触达海外用户的出海 App，这种「静默失败」往往要等留存数据下滑才会被发现。

本指南介绍 9 款让推送 SDK 迁移更安全的工具，按迁移的 5 个步骤分组：梳理、替换、测试、发布和监控。

推送服务商侧的迁移步骤，请参阅我们的 OneSignal 迁移到 Pushwoosh 完整指南。

为什么大型 App 的推送 SDK 迁移容易出问题

推送 SDK 触及的代码范围，比大多数第三方库都广。通常有 4 类问题：

• 调用分散。 标签、外部用户 ID 和点击处理器分布在不同模块中，有时甚至在不同的代码仓库里。全文搜索「OneSignal」能找到显而易见的调用，却会漏掉封装层。
• 隐藏依赖。 分析事件、深度链接和 A/B 测试常常挂在 SDK 回调上。删掉回调，下游某个数据看板就会归零。
• 2 个 SDK，1 个构建。 同一个 App 里的 2 个推送 SDK 会争抢同一组通知回调。这就是为什么 Pushwoosh 迁移指南要求在加入新 SDK 的同一个版本中移除 OneSignal SDK。
• 静默失败。 推送未送达不会抛出错误，崩溃报告依然干干净净。

分步迁移流程

每个步骤都有各自的失败模式和对应工具。

安全迁移 OneSignal SDK 的 9 款工具

第 1 步：梳理每一处 OneSignal 调用

1. CodeAlive：在大型及多仓库代码库中梳理 SDK 调用的最佳选择

CodeAlive 为 AI 编程智能体提供覆盖整个代码库的精准上下文，并减少它们在查找上下文时消耗的 token。它是一个为 100 万行以上代码库打造的上下文引擎：语义搜索加上由文件、符号、调用、依赖和测试构成的关系图谱，通过 MCP 和 API 提供服务。

它在迁移中的作用： 在任何人改代码之前，先问 CodeAlive：OneSignal 在哪里被使用、哪些东西依赖它。关系图谱会显示显而易见之外的调用：封装层、分析事件依赖的回调、模拟（mock）该 SDK 的测试。同样的上下文也会提供给负责替换代码的 AI 智能体。

核心功能：

• 混合检索： 1 次查询同时完成语义搜索、词法匹配和图谱遍历
• 每次 push 都会刷新索引，迁移分支持续变化时，调用地图也始终保持最新
• MCP 工具，包括 semantic_search、grep_search 和 chat，支持 Cursor、Claude Code、Codex、Windsurf、Zed、Continue 和 Cline
• AI 拉取请求审查，会把整个系统纳入考量
• Git 托管平台： GitHub、GitLab、Bitbucket、Azure DevOps、Gitea。IDE：VS Code 和 JetBrains

优点：

第 2 步：替换 SDK 并迁移受众

2. Pushwoosh：支持受众导入的目标平台的最佳选择

Pushwoosh 是一个客户互动平台，支持推送、应用内消息、邮件、短信和 WhatsApp。迁移期间，Pushwoosh 团队会在您的开发人员发布新 SDK 的同时为您导入受众。

它在迁移中的作用： iOS 和 Android 的推送 Token 会被导入并继续有效，因为 Token 属于您的 App 和您的密钥。邮件和短信订阅者也会随导入一起迁移过来。external_user_id 会映射到 Pushwoosh User ID（请在 OneSignal 导出中专门申请这一列，默认导出中不包含），标签则根据您的导出数据重新创建。网页推送是例外：浏览器订阅无法被任何服务商迁移，因此 Pushwoosh Web SDK 会静默地为访客重新订阅。

核心功能：

• SDK 覆盖 iOS 和 Android，以及 React Native、Flutter、Unity、Capacitor、Cordova、MAUI、Expo 等
• 受众导入与 SDK 发布并行进行，用户更新 App 之前设备就已可触达
• 测试设备，可在正式发送前在真机上预览推送

优点：

定价： 仅推送方案为每 1,000 MAU $7，前 1,000 MAU 免费。可用 OneSignal 成本计算器 对比您当前的账单。

第 3 步：测试注册和送达

3. Apple Push Notifications Console：通过 APNs 测试 iOS 送达的最佳选择

Push Notifications Console 是 Apple 用于通过 APNs 发送测试通知的网页工具。当 iOS 推送没有到达时，用它可以快速排除推送服务商方面的原因。

它在迁移中的作用： 您直接向某个设备 Token 发送推送，查看 APNs 是否接受并送达。如果从这里能收到，而从新的推送服务商发送却收不到，请先检查服务商侧的配置。

核心功能：

• 向设备发送测试通知，修改属性后可重新发送
• 送达日志，显示通知在 APNs 中的传递路径，适用于开发环境
• Token 验证，可针对特定环境和推送类型
• 送达指标，覆盖测试和生产环境的通知

优点：

4. Firebase Cloud Messaging：按 Token 测试 Android 推送的最佳选择

在搭载 Google Play 服务的设备上，Android 推送通过 Firebase Cloud Messaging 发送，这也是出海 App 触达海外 Android 用户的主要通道。Firebase 控制台可以向 1 个注册 Token 发送测试消息，因此它是 Android 构建的简易推送测试工具。

它在迁移中的作用： 新 SDK 注册设备后，把设备的 FCM Token 粘贴到控制台并发送测试。如果收到了，说明 Token 和 Firebase 配置都没有问题。

核心功能：

• 在控制台中向指定 FCM 注册 Token 发送测试消息
• 快速检查无需编写代码，只需从设备上读取 Token

优点：

5. Proxyman：检查 SDK 流量和载荷的最佳选择

Proxyman 是一款适用于 macOS、Windows 和 Linux 的 HTTP 调试代理。它能显示推送 SDK 实际发送了什么：注册调用、用户 ID 更新、标签请求。

它在迁移中的作用： 运行集成了新 SDK 的 App 并观察它的请求。如果某个标签根本没有从设备发出，您会在这里看到，而不必等到某个用户分群变成空的。

核心功能：

• HTTPS 流量抓取，覆盖真机、Simulator 和 Emulator 上的 App
• 付费方案支持一键抓取 iOS Simulator 和 Android Emulator
• 断点和 Map Local/Remote，可修改请求和响应

第 4 步：分阶段发布

6. fastlane：自动化分阶段发布的最佳选择

fastlane 是一个用于自动化 iOS 和 Android 部署的开源平台。对迁移而言，它的价值在于 2 个可以写进发布 lane 的参数。

它在迁移中的作用： upload_to_app_store 接受 phased_release: true，会在 7 天内逐步发布更新。upload_to_play_store 接受 rollout 值，即获得该构建的用户比例（0.1 表示 10%；1 表示完成发布）。迁移版本每次都走同样的分阶段路径，也不会有人忘记勾选。

核心功能：

• deliver / upload_to_app_store，支持 phased_release
• supply / upload_to_play_store，支持 rollout 和 release_status（包括 halted）
• 1 条 lane 同时覆盖两个应用商店

优点：

7. App Store 分阶段发布和 Google Play 分阶段发布：控制影响范围的最佳选择

两大应用商店都支持先把更新推送给一部分用户。无论您使用什么发布工具，这都是推送 SDK 替换的安全网。

它在迁移中的作用： 集成 Pushwoosh 的新构建先触达一小部分用户。如果送达率或崩溃率异常，您可以在它触达所有人之前停止发布。与此同时，OneSignal 会继续向尚未更新的用户发送推送，所以没有人会错过营销活动。

核心功能：

• App Store： 在 7 天内依次向 1%、2%、5%、10%、20%、50%，最终 100% 开启了自动更新的用户发布。您总共可以暂停最多 30 天，也可以随时向所有人发布
• Google Play： 由您设定百分比并手动提高。可以暂停和恢复发布，已经更新的用户会保留该构建
• 两个应用商店都对用户进行随机抽样

优点：

第 5 步：监控崩溃和送达

8. Firebase Crashlytics：在替换后捕获崩溃的最佳选择

Firebase Crashlytics 报告来自 Android、Apple、Flutter 和 Unity App 的崩溃和非致命错误。在整个发布过程中都运行它，并把新构建与上一个构建进行对比。

它在迁移中的作用： 通知处理器中或 SDK 初始化期间的崩溃会首先出现在这里。非致命事件则有助于发现更隐蔽的问题：在推送注册失败时记录一个非致命事件，您就能按构建看到它。

核心功能：

• 崩溃报告按问题分组，可按构建筛选
• 非致命事件，在设备上记录，并在下次启动 App 时发送
• 官方 SDK 支持 Android、Apple、Flutter 和 Unity

9. Pushwoosh 消息统计：发现静默送达下降的最佳选择

崩溃报告不会告诉您推送已经不再送达，Pushwoosh 推送统计会。

它在迁移中的作用： 对每一条推送，您都能按平台看到从受众到发送、送达和打开的漏斗，此外还有单独的错误标签页。把切换后的前几次营销活动与之前的 OneSignal 数据进行对比。如果 iOS 送达落后于 Android，先检查凭证，再检查代码。

大型 App 的 5 步迁移计划

动代码之前，先盘点每一处 OneSignal 调用

列出所有代码仓库中的每一个 SDK 调用、封装层、回调和测试。这份清单会成为替换工作和代码审查的检查清单。

用 1 个内部接口封装推送

把所有推送调用都通过一个统一的内部服务来路由：登录、退出、标签、通知处理。这样迁移只需修改 1 个实现，而不是 50 处调用点，下一次更换服务商也会更容易。

protocol PushService {
    func login(userId: String)
    func setTags(_ tags: [String: Any])
    func handleNotificationOpen(_ payload: [AnyHashable: Any])
}

在 1 个版本中完成 SDK 替换

在同一个构建中加入 Pushwoosh SDK 并移除 OneSignal SDK。同一个 App 中的 2 个推送 SDK 会争抢通知回调。在新构建逐步发布期间，继续通过 OneSignal 向仍在使用旧版本的用户发送推送。

分阶段发布并对比送达指标

先通过分阶段发布向一小部分用户推出。在 Crashlytics 中观察崩溃，在 Pushwoosh 统计中观察送达情况，然后再扩大发布范围。

确认送达后再停止 OneSignal 发送

在停止通过 OneSignal 发送之前，回滚就意味着继续用 OneSignal 发送。等 Pushwoosh 的送达和受众导入都得到确认后，再停止使用 OneSignal。

常见问题