Migration guide from the Push API to the PushV2 API-Enterprise Mobile Application Studio(EMAS)-阿里云帮助中心

This document explains why you need to upgrade from PushV1 to PushV2 for Alibaba Cloud Mobile Push. It covers core improvements, such as a structured parameter design, a simplified parameter system, and enhanced push features like continuous push. This document also details the migration work, which includes API adjustments, parameter refactoring, push method adaptation, and testing suggestions to ensure a smooth transition.

Why upgrade to PushV2

PushV2 is a major upgrade and optimization of the V1 version of the Alibaba Cloud Mobile Push service. Long-term use of the V1 version exposed several design shortcomings, which include the following:

In V1, all push parameters are flattened at the same level, which makes them difficult to manage.
V1 contains legacy deprecated parameters, which makes it harder to learn and use.
In V1, passing combined parameters for both pass-through messages and notification messages is complex.

Core advantages of PushV2

Structured parameter design

PushV2 uses a hierarchical parameter structure. Push configurations are divided into clear modules, such as Target, Message (pass-through message), Notification (notification message), and Options.
Platform-specific parameters are grouped into their corresponding configuration objects, such as Ios, Android, and Hmos.
Parameter naming is more standardized and intuitive. For example, the required parameter AndroidPopupActivity for Android vendor channels is changed to Android.VendorChannelActivity.

Streamlined and efficient parameter system

All deprecated parameters have been removed, leaving only valid and necessary configuration items.
It reduces parameter redundancy, which lowers the cost of learning and using the API.
It offers clearer parameter documentation and examples.

Enhanced push capabilities

The new Continuous Push feature lets you create a message template once and push it to multiple batches of devices. This greatly improves the efficiency of large-scale pushes.
PushV2 supports three push methods to meet different business needs: immediate push, scheduled push, and continuous push.

Optimized parameter passing logic

Unified Parameter Validation Mechanism
It provides more logical default value settings.
It provides more user-friendly error messages.

MassPushV2 request object reuse

The PushTask object can be reused in the new batch push API.

Migration work for PushV2

1. API call adjustments

Core changes

V1 uses the Push API, and V2 uses the PushV2 API.
Request parameters are changed from a flat structure to a nested PushV2Request object.
The response structure is similar and still returns key information, such as MessageId.

Code changes

Update the software development kit (SDK) dependency version.
Modify how you build push requests to use the new parameter structure.
Adjust the parameter mappings.

2. Parameter mapping and refactoring

General platform parameters

AppKey: Unchanged.
Target: The target type and value are now set in the Target object.
Title and Body are now part of the Message or Notification objects.
Push options such as PushTime, ExpireTime, and JobKey are now in the Options object.

iOS platform parameters

IosRelevanceScore → Notification.Ios.RelevanceScore
IosBadge → Notification.Ios.Badge
IosMusic → Notification.Ios.Music
iOSLiveActivityEvent → Notification.Ios.LiveActivity.Event

Android platform parameters

Vendor channel parameters are no longer flat. They are nested within Notification.Android.Options.
Huawei parameters: Notification.Android.Options.Huawei.*
Xiaomi parameters: Notification.Android.Options.Xiaomi.*
OPPO parameters: Notification.Android.Options.Oppo.*
Alibaba Cloud channel parameters: Notification.Android.Options..*
Parameters for other vendors are adjusted similarly.

HarmonyOS platform parameters

They are grouped into the Notification.Hmos object.
Parameter naming and structure are more standardized.

3. Push method adaptation

Immediate push

V1: Default behavior.
V2: This is the default behavior, or you can set PushTask.Action = "PUSH_IMMEDIATELY" (default value).

Scheduled push

V1: Set the PushTime parameter.
V2: Set PushTask.Action = "SCHEDULED_PUSH" and specify the time in Options.PushTime.

Continuous push (New)

This is a new feature in V2. It is a two-step operation:
1. Create a continuous push task: Action = "CREATE_CONTINUOUS_PUSH"
2. Execute a batch push: Action = "CONTINUOUS_PUSH" and specify the MessageId

4. Push type adaptation

Pass-through message (online only)

V1: Set PushType = "MESSAGE" and StoreOffline = false.
V2: Set the Message object.

Pass-through message (save for offline)

V1: Set PushType = "MESSAGE" and StoreOffline = true.
V2: Set the Message object and specify the time-to-live (TTL) in Options.ExpireTime.

Notification message

V1: Set PushType = "NOTICE".
V2: Set the Notification object.

Offline message to notification

V1: Set PushType = "MESSAGE" and parameters such as AndroidRemind = true and iOSRemind = true.
V2: Set both the Message object and the Notification object.

Migration recommendations

Complete functional validation

Verify that push functions work correctly on iOS, Android, and HarmonyOS platforms.
Test scenarios such as online and offline pass-through messages, notification messages, and offline messages converted to notifications.
Verify the scheduled push and continuous push features.

Phased migration

First, complete the migration and validation in a staging environment.
Migrate non-core services first, and then gradually expand the migration.
Keep V1 and V2 running in parallel for a period to ensure a smooth transition.

Key considerations

The accuracy of the parameter mapping, especially for platform-specific parameters
Adjustments to the push method, especially for scheduled pushes
Adapt your error handling and log recording.

Thorough testing

Cover all push scenarios.
Verify all platforms and vendor channels.
Perform stress tests to ensure performance.