该文档介绍了阿里云移动推送服务从 PushV1 升级到 PushV2 的必要性与核心改进，包括结构化参数设计、精简参数体系和增强推送能力（如新增持续推送）。同时，文档详细说明了迁移所需的工作，涵盖接口调整、参数重构、推送方式适配及测试建议，以确保平滑过渡。
为什么要升级到 PushV2
阿里云移动推送服务 PushV2 是在 V1 版本基础上进行的大量升级和优化。V1 版本在长期使用过程中暴露出一些设计上的不足，主要体现在：
V1 将所有推送参数平铺在同一层级，难以管理
V1 存在历史遗留的废弃参数，增加了理解和使用成本
V1 对于透传消息和通知消息两种推送类型的组合传参处理复杂
PushV2 的核心优势
结构化的参数设计
采用层次化的参数结构，将推送配置分为 Target（目标）、Message（透传消息）、Notification（通知消息）、Options（选项）等清晰的模块
平台特定参数统一归类到对应的配置对象中（如
Ios、Android、Hmos）参数命名更加规范和直观，例如Android厂商通道必填参数
AndroidPopupActivity改为Android.VendorChannelActivity
精简高效的参数体系
移除所有废弃参数，只保留有效和必要的配置项
减少参数冗余，降低学习和使用成本
提供更清晰的参数文档和示例
增强的推送能力
新增持续推送（Continuous Push）功能，支持创建一次消息模板后向多批设备推送，大幅提升大规模推送的效率
支持立即推送、定时推送、持续推送三种推送方式，满足不同业务场景需求
优化的传参逻辑
统一的参数验证机制
更合理的默认值设置
更友好的错误提示
MassPushV2 请求对象复用
PushTask对象可以直接复用到新版批量推送接口
迁移到 PushV2 涉及的工作
1. 接口调用方式调整
核心变化
V1 使用
Push接口，V2 使用PushV2接口请求参数从平铺结构改为嵌套的
PushV2Request对象响应结果结构保持类似，仍返回
MessageId等关键信息
代码改动
更新 SDK 依赖版本
修改推送请求的构建方式，使用新的参数结构
调整参数映射关系
2. 参数映射和重构
平台通用参数
AppKey：保持不变Target：目标类型和值的设置方式调整为Target对象Title、Body：分别归类到Message或Notification对象中PushTime、ExpireTime、JobKey：此类推送选项归类到Options对象中
iOS 平台参数
IosRelevanceScore→Notification.Ios.RelevanceScoreIosBadge→Notification.Ios.BadgeIosMusic→Notification.Ios.MusiciOSLiveActivityEvent→Notification.Ios.LiveActivity.Event
Android 平台参数
各厂商通道参数从平铺改为嵌套在
Notification.Android.Options中华为参数：
Notification.Android.Options.Huawei.*小米参数：
Notification.Android.Options.Xiaomi.*OPPO 参数：
Notification.Android.Options.Oppo.*阿里云自有通道参数：
Notification.Android.Options..*其他厂商参数类似调整
HarmonyOS 平台参数
统一归类到
Notification.Hmos对象参数命名和结构更加规范
3. 推送方式适配
立即推送
V1：默认行为
V2：默认行为或设置
PushTask.Action = "PUSH_IMMEDIATELY"（默认值）
定时推送
V1：设置
PushTime参数V2：设置
PushTask.Action = "SCHEDULED_PUSH"并在Options.PushTime中指定时间
持续推送（新增）
V2 新增功能，分两步操作：
创建持续推送任务：
Action = "CREATE_CONTINUOUS_PUSH"执行批次推送：
Action = "CONTINUOUS_PUSH"并指定MessageId
4. 推送类型适配
透传消息（只发在线）
V1：设置
PushType = "MESSAGE"和StoreOffline = falseV2：设置
Message对象
透传消息（离线保存）
V1：设置
PushType = "MESSAGE"和StoreOffline = trueV2：设置
Message对象并在Options.ExpireTime中指定过期时间
通知消息
V1：设置
PushType = "NOTICE"V2：设置
Notification对象
消息离线转通知
V1：设置
PushType = "MESSAGE"和AndroidRemind = true、iOSRemind = true等V2：同时设置
Message对象和Notification对象
迁移建议
完成功能验证
验证iOS、Android和HarmonyOS各平台推送功能正常
测试在线和离线透传消息、通知消息、消息离线转通知等场景
验证定时推送和持续推送功能
渐进式迁移
建议先在测试环境完成迁移和验证
可以先迁移部分非核心业务，逐步推广
保持 V1 和 V2 并行一段时间，确保平稳过渡
重点关注
参数映射的准确性，特别是平台特定参数
推送方式的调整，特别是定时推送
错误处理和日志记录的适配
充分测试
覆盖所有推送场景
验证各平台和厂商通道
进行压力测试确保性能