Background
HarmonyOS has added a new security mechanism to its meta-capabilities and window widgets. This mechanism prevents one Ability from launching another after an application moves to the background. As a result, when an app is offline, clicking a notification can no longer directly open a page within the app. For more information about the component startup rules, see HarmonyOS component startup rules.
This update addresses this issue by removing the mPaaS middle layer.
Client updates and integration
After you upgrade the HarmonyOS client baseline, you must configure the target page for the redirect. For example, to navigate to the PushLandingAbility page after a user clicks a notification, add the following configuration to the module.json5 file.
{
"name": "PushLandingAbility",
"srcEntry": "./ets/pushability/PushLandingAbility.ets",
"description": "$string:EntryAbility_desc",
"icon": "$media:icon",
"label": "$string:LandingAbility_label",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": true,
"skills": [
{
"actions": [""],
"uris": [
{
"scheme": "jump",
"host": "com.mpaas.harmony.push",
"path": "landing"
}
]
}
]
},mPaaS uses the URI in the message to match a specific page. The `actions` field is required and must be set to empty.
On the target page, use the `PushMsgHandler` utility class provided by mPaaS to parse the data from the notification message. Ensure that the server-side is upgraded before use. The following code shows an example:
import { MPPushMsg,PushMsgHandler,msgOutput } from '@mpaas/push';
export class PushLandingAbility extends UIAbility {
private TAG: string = "PushLandingAbility"
async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
super.onCreate(want, launchParam)
let msg: msgOutput | undefined = PushMsgHandler.parsePushMsg(want)
let msg_id: string | undefined = msg?.msg_id
let msg_data: MPPushMsg | undefined = msg?.msg_data
}
......
}msg_idcorresponds to the message ID.msg_datacorresponds to the specific message data.
Additionally, the upgraded SDK destroys the configuration page within `NcAbility`. Therefore, delete the `this.context.terminateSelf` code from the `onForeground` stage of the configuration page. The following code shows a configuration example:
export default class MpaasBridgeMsgAbility extends MpaasNcAbility {
static tag: string = "MpaasBridgeMsgAbility"
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
hilog.info(0x0000, MpaasBridgeMsgAbility.tag, "start MpaasBridgeMsgAbility onCreate")
super.onCreate(want, launchParam)
}
onForeground() {
console.log('MpaasBridgeMsgAbility onBackground');
}
}Warning 1: If you upgrade the client component but do not delete the destroy code, the redirect action fails.
Warning 2: If you upgrade the client component but not the server-side, you must keep the existing message parsing method. Do not use `PushMsgHandler` to parse messages, because the parsing will fail.
Server-side updates
The server-side uses the value of the `pushVersion` field to identify and adapt to different versions of the HarmonyOS push SDK. This field is reported when the client calls the initialization reporting API. Before the upgrade, the value of the `pushVersion` field is 2.5.0. After the upgrade, its value is 3.0.0.
For the pre-upgrade SDK, the server-side sends a push message with the following struct:
{
"pushOptions": {
"testMessage": true,
"biTag": "0#11#1.0.0#c_0_0_8314646940c9f7ceb2e0Grm&49bd2fa97769abdf",
"collapseKey": -1,
"ttl": 180
},
"payload": {
"notification": {
"badge": {
"addNum": 1
},
"notifyId": 1568946632,
"category": "MARKETING",
"title": "Push test-noUrl000",
"body": "Push test-noUrl000",
"clickAction": {
"actionType": 1,
"data": {
"com_harmony_push": {
"bData": "{\"harmonyos_badge_add_num\":\"1\",\"pushStyle\":0,\"silent\":false,\"notifyType\":\"notify\",\"action\":\"0\",\"id\":\"console_1709535017366\",\"params\":{\"ALIMpsChannel\":\"HARMONYOS\"},\"url\":\"https://www.baidu.com\",\"test_msg\":\"1\"}",
"k": "c_0_0_8314646940c9f7ceb2e0Grm"
}
},
"action": "com.mpaas.harmony.push",
"uri": "mpaasscheme://com.mpaas.harmony.push/longlink"
}
}
},
"target": {
"token": ["MAMzLgNB-HcFV6YAstOIywAAAGQAAAAAAAHmQeccAFJz604RQSgRll3LPikX2SogGoJtfDDs4lG2Vaz5MwV18jA9UsYKH4oNbTarIDVIjY9SzGrm"]
}
}For the post-upgrade SDK, the server-side sends a push message with the following struct:
{
"pushOptions": {
"testMessage": true,
"biTag": "0#11#1.0.0#c_0_0_8315cb56301994ccb601Grm&104aca1b4f59abd6",
"collapseKey": -1,
"ttl": 180
},
"payload": {
"notification": {
"badge": {
"addNum": 1
},
"notifyId": 1568946632,
"category": "MARKETING",
"title": "Push test-noUrl000",
"body": "Push test-noUrl000",
"clickAction": {
"actionType": 1,
"data": {
"com_harmony_push": {
"bData": "{\"harmonyos_badge_add_num\":\"1\",\"pushStyle\":0,\"silent\":false,\"notifyType\":\"notify\",\"action\":\"1\",\"id\":\"console_1709535017366\",\"params\":{\"ALIMpsChannel\":\"HARMONYOS\"},\"url\":\"jump://com.mpaas.harmony.push/landing\",\"test_msg\":\"1\"}",
"k": "c_0_0_8315cb56301994ccb601Grm"
}
},
"action": "",
"uri": "jump://com.mpaas.harmony.push/landing"
}
}
},
"target": {
"token": ["MAMzLgNB-HcFV6YAstOIywAAAGQAAAAAAAHmQeccAFJz604RQSgRll3LPikX2SogGoJtfDDs4lG2Vaz5MwV18jA9UsYKH4oNbTarIDVIjY9SzGrm"]
}
}Differences
For the pre-upgrade SDK, the server-side passes a fixed configuration page address in the URI: `mpaasscheme://com.mpaas.harmony.push/longlink`. When a user clicks the notification, the client opens this configuration page, which inherits from `NcAbility`. This page then launches the target page specified by the `URL` field in `bData`.
For the post-upgrade SDK, the server-side passes the address of the target page in the URI: `jump://com.mpaas.harmony.push/landing`. When a user clicks the notification, the HarmonyOS system performs the redirect directly.
Upgrade steps
This update involves both server-side and client-side upgrades. Upgrade the server-side first, and then upgrade the client-side.
An upgraded server-side is compatible with both older and newer client versions.
Server-side upgrade version: 1.35.0 or later
Client baseline version: 10.2.3.13 or later
For more information about how to integrate the HarmonyOS baseline, see Integrate HarmonyOS NEXT.
Warning: If you upgrade the client first, do not delete the original configuration page (the page that inherits from `NcAbility`). If this page is deleted before the server-side is upgraded, the client cannot handle notification click and redirect events.
Changes after the upgrade
After this upgrade, when a user clicks a notification, the client directly redirects to the in-app page that corresponds to the URI in the message, bypassing the `NcAbility` page. The upgrade also provides a data parsing tool to parse message data on the target page.
Warning: The HarmonyOS Push Kit does not currently support opening an HTTP link in a browser directly from a notification click. If a message pushed by the server-side contains a web page redirect address, the browser will not open the link automatically after the upgrade. You must adapt the redirect for this type of message. For more information, see the HarmonyOS document: Message click actions.
Compatibility and notes
Server-side upgraded, client not upgraded
The upgraded server-side is compatible with older client components. If you do not upgrade the client, the client continues to function as before.
Client upgraded, server-side not upgraded
If you upgrade the client but keep the configuration page that inherits from `NcAbility`, the original redirect logic is still used.