推送功能更新适配_移动开发平台 mPaaS(mPaaS)-阿里云帮助中心

背景

由于鸿蒙的元能力与窗口组件新增了安全机制（应用退出后台后，不允许执行 Ability 之间的拉起），因此当前 App 离线状态下点击通知栏之后，无法直接跳转到应用内页面。具体组件启动规则，参考鸿蒙组件启动规则。

说明

此次更新删除了 mPaaS 中间层，修复了上述问题。

客户端更新与接入

鸿蒙客户端基线升级之后，用户只需直接配置需要跳转的目标页面即可。例如，需要点击通知栏之后跳转到 PushLandingAbility 页面，需在 module.json5 文件中进行如下配置。

{
  "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 通过消息中的 URI 匹配具体的页面，actions 需要设置为空（不能缺少该字段）。

在跳转的目标页面中，用户可以使用 mPaaS 提供的工具类 PushMsgHandler 解析消息通知中包含的数据（使用时，需要确保服务端已经升级），具体代码参考如下：

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_id 对应消息 ID。
msg_data 对应具体的消息数据。

另外，升级后的 SDK 在 NcAbility 内部做了配置页面的销毁动作，因此 开发者需要删除在配置页面中 onForeground 阶段的 this.context.terminateSelf 代码，配置示例如下：

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');
  }

}

重要

风险点提示 1：如果升级客户端组件之后，没有删除上述销毁的代码，那么跳转动作会失败。

风险点提示 2：升级客户端组件之后，如果没有升级服务端，保持现有的消息解析方式不变，不要使用 PushMsgHandler 解析消息，否则会解析失败。

服务端更新内容

服务端通过 pushVersion 字段的值（在客户端调用初始化上报接口时会上报该字段）来判断和适配不同版本的鸿蒙推送 SDK，升级前的 pushVersion 字段值为 2.5.0，升级后的 pushVersion 字段值为 3.0.0。

针对 升级前的 SDK，服务端发送的推送消息结构体如下：

{
  "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": "推送测试-noUrl000",
      "body": "推送测试-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"]
  }
}

针对 升级后的 SDK，服务端发送的推送消息结构体如下：

{
  "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": "推送测试-noUrl000",
      "body": "推送测试-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"]
  }
}

区别

服务端对于升级前的 SDK，URI 传递的是一个固定的配置页面的地址：mpaasscheme://com.mpaas.harmony.push/longlink，客户端点击通知栏之后会跳转到固定的配置页面（即继承了 NcAbility 的页面），然后由该配置页面去拉起不同的页面（页面地址在 bData 里面的 URL 字段）。
服务端对于升级后的 SDK，URI 传递的是需要跳转的页面的地址：jump://com.mpaas.harmony.push/landing，点击后由鸿蒙系统直接跳转。

升级步骤

此次更新涉及到服务端升级与客户端升级，建议先升级服务端，后升级客户端。

说明

服务端升级之后，会兼容新旧两种客户端版本。

服务端升级版本：1.35.0 及其以上版本

客户端基线版本：10.2.3.13 及其以上版本基线

鸿蒙基线接入方式可参考文档：接入 HarmonyOS NEXT

重要

风险点提示：如果先升级客户端，则 不要删除原有的配置页面（继承 NcAbility 的配置页面），如果删除了继承 NcAbility 的配置页面，但是没有升级服务端，那么客户端将无法处理通知栏的点击跳转事件。

升级改动点

此次升级之后，客户端点击通知栏之后直接跳转到消息中包含的 URI 对应的应用内页面，不经过 NcAbility 页面中转，同时提供了数据解析工具，帮助用户在目标页面解析消息数据。

重要

风险点提示：鸿蒙 Push Kit 能力暂不支持点击通知消息直接跳转到浏览器并且打开 HTTP 链接，如果服务端推送的消息包含了网页类型的跳转地址，升级之后将无法自动打开浏览器打开链接，需要用户自行适配此种消息的跳转。详情请参考鸿蒙文档：点击消息动作。

兼容情况与说明

服务端升级，客户端不升级

由于升级之后的服务端可以兼容老版本客户端组件，因此客户端不升级则维持现有方式。

客户端升级，服务端不升级

若客户端升级之后，保持继承了 NcAbility 的配置页面存在，那么依然会走原有的跳转逻辑。