鸿蒙 MPS 使用文档_移动开发平台 mPaaS(mPaaS)-阿里云帮助中心

初始化与接入 SDK

前置条件

已在华为的应用平台上开通 App 的推送服务，详情请参考华为的 Push 服务。
添加消息推送SDK 前，请确保已经接入工程到 mPaaS。更多信息请参见基于已有工程使用 ohpmrc 接入。

组件接入

需在 Ability 的 onCreate 方法中设置调用。

代码如下：

import { MpaasPushServiceImpl, MPPush, CallResp } from '@mpaas/push';

let tokenGet: CallResp
try {
	tokenGet = await MPPush.init()	
	console.info("CallResp="+tokenGet)
	if (tokenGet.success) {
		this.tokenVal = tokenGet.msg
	} else {
		console.info("MPPush.init failed=" + tokenGet.msg)
	}
} catch (e) {
	console.info("MPPush.init err=" + e.message)
}

该方法会初始化 Push 的服务组件，同时会获取一个鸿蒙推送的 token，然后将其上报到服务器。

如果成功，则该方法会返回 token 值。
如果失败，则会返回空字符串，并且打印日志。

编写一个承接 MPS 组件的 Ability，继承 MpaasNcAbility。

代码如下：

import { MpaasNcAbility } from '@mpaas/push'

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');
      try {
        // 销毁掉中间过渡的 Ability
        this.context.terminateSelf((err: BusinessError) => {
          if (err.code) {
            // 处理业务逻辑错误
            console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          // 执行正常业务
          console.info('terminateSelf succeed');
        });
      } catch (err) {
        // 捕获同步的参数错误
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`terminateSelf failed, code is ${code}, message is ${message}`);
      }
  }
}

在 module.json5 文件中，描述 MpaasBridgeMsgAbility。

代码如下：

{
 "name": "MpaasBridgeMsgAbility",
 "srcEntry": "./ets/pushability/MpaasBridgeMsgAbility.ets",
 "description": "$string:EntryAbility_desc",
 "icon": "$media:icon",
 "label": "$string:BridgeAbility_label",
 "startWindowIcon": "$media:startIcon",
 "startWindowBackground": "$color:start_window_background",
 "exported": true,
 "removeMissionAfterTerminate": true,
 "skills": [
 {
 "actions": ["com.mpaas.harmony.push"]
 }
 ]
}

重要

actions 必须和代码中的描述保持一致。
removeMissionAfterTerminate 字段必须设置为 true，否则 MpaasBridgeMsgAbility 不会被彻底销毁，从而造成应用中有一个多余且无效的 UIAbility。

使用 SDK

绑定/解绑 token

用户调用绑定接口，将 App 的用户 id 和 token 发送到后端即可进行绑定，解绑即为取消绑定。

绑定接口如下：

import { MpaasPushServiceImpl, MPPush, CallResp } from '@mpaas/push';

// 第一个入参： phoneNumber，如果没有电话号码，填入 ""
// 第二个入参： token 就是 init 方法返回的 token 值，必填
// 第三个入参： userId，用户 ID，如果不填，则从框架层获取
let res: CallResp = await MpaasPushServiceImpl.getInstance().bind("12345678900", this.tokenVal, "mpaas_user_id")
console.log("bind res="+res.msg)
if (res.success) {
	this.bindState = "bind state: " + "binded"
}

返回值 res.success 表示绑定是否成功。

解绑接口如下：

import { MpaasPushServiceImpl, MPPush, CallResp } from '@mpaas/push';

// 第一个入参： token 就是 init 方法返回的 token 值，必填
// 第二个入参： userId，用户 ID，如果不填，则从框架层获取
let res: CallResp = await MpaasPushServiceImpl.getInstance().unbind(this.tokenVal, "mpaas_user_id")
console.log("unbind res="+res.msg)
if (res.success) {
	this.bindState = "bind state: " + "unbind"
}

返回值 res.success 表示解绑是否成功。

配置跳转消息 Ability

在客户端的 module.json5 文件中配置目标应用内的 Ability，例如下面的 PushLandingAbility：

{
 "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"
 }
 ]
 }
 ]
}

在控制台推送消息时，需要填入跳转的 uri 为 jump://com.mpaas.harmony.push/landing，和上述的 uris 对应。在控制台推送消息结束之后，可以点击客户端的通知栏，即可跳转至配置好的 PushLandingAbility 所对应的页面。用户也可以点击通知栏，打开消息中包含的 http 链接地址，如果该消息的 url 字段中 http 链接合法，那么应用会打开本地默认的浏览器应用，同时跳转到 url 对应的链接地址。

配置落地页面的 Ability 示例代码

import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import window from '@ohos.window';
import hilog from '@ohos.hilog';
import { MpaasPushServiceImpl } from '@mpaas/push';
import pushService from '@hms.core.push.pushService';
import { BusinessError } from '@ohos.base';

export class PushLandingAbility extends UIAbility {
  private static TAG: string = "PushLandingAbility"

  private pushData: object = JSON.parse("{}");
  private pushKey: string = "";
  public  para: Record<string,string> = { 'msg_id': "default", 'msg_data': "default"};
  public storageData: LocalStorage = new LocalStorage(this.para);
  landingWindowStage: window.WindowStage | undefined = undefined;

  async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    hilog.info(0x0000, PushLandingAbility.TAG, 'PushLandingAbility create. Data: %{public}s', JSON.stringify(want.parameters) ?? '');
    let k: string = ""
    let v: object = JSON.parse("{}")
    if (want.parameters) {
      if (want.parameters["msg_id"]) {
        k = want.parameters["msg_id"] as string
        hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant k: %{public}s', k);
      }
      if (want.parameters["msg_data"]) {
        v = want.parameters["msg_data"]
        hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant k: %{public}s', v);
      }
    }

    this.storageData.set('msg_id', k)
    this.storageData.set('msg_data', JSON.stringify(v))
    hilog.info(0x0000, PushLandingAbility.TAG, 'onCreate push_msgkey from storage: %{public}s', this.storageData.get("msg_id"));
    hilog.info(0x0000, PushLandingAbility.TAG, 'onCreate push_msgdata from storage: %{public}s', JSON.stringify(this.storageData.get("msg_data")));
  }

  async onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    let k: string = ""
    let v: object = JSON.parse("{}")
    if (want.parameters) {
      if (want.parameters["msg_id"]) {
        k = want.parameters["msg_id"] as string
        hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant k: %{public}s', k);
      }
      if (want.parameters["msg_data"]) {
        v = want.parameters["msg_data"]
        hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant k: %{public}s', v);
      }
    }
    this.storageData.set('msg_id', k)
    this.storageData.set('msg_data', JSON.stringify(v))

    hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant push_msgkey: %{public}s', this.storageData.get("msg_id"));
    hilog.info(0x0000, PushLandingAbility.TAG, 'onNewWant push_msgdata: %{public}s', JSON.stringify(this.storageData.get("msg_data")));
    
		// 进入该阶段需要手动加载一下页面
		if (this.landingWindowStage != null) {
      await this.landingWindowStage.loadContent('pushpages/pushLandingPage', this.storageData)
    }

  }

  onDestroy(): void {
    hilog.info(0x0000, PushLandingAbility.TAG, '%{public}s', 'Ability onDestroy');
  }

  async onWindowStageCreate(windowStage: window.WindowStage): Promise<void> {
    // Main window is created, set main page for this ability
    // 创建新实例并使用给定对象初始化
    this.landingWindowStage = windowStage
    hilog.info(0x0000, PushLandingAbility.TAG, 'this.pushKey= %{public}s',this.storageData.get("msg_id"));
    hilog.info(0x0000, PushLandingAbility.TAG, 'this.pushData= %{public}s', JSON.stringify(this.storageData.get("msg_data")));

    try {
      await windowStage.loadContent('pushpages/pushLandingPage', this.storageData)
      hilog.info(0x0000, PushLandingAbility.TAG, 'Succeeded in loading the content. Key: %{public}s, Data: %{public}s',this.storageData.get("msg_id"), JSON.stringify(this.storageData.get("msg_data")) ?? '');
    } catch (e) {
      console.log("err msg="+e.message)
      return
    }
  }

  onWindowStageDestroy(): void {
    hilog.info(0x0000, PushLandingAbility.TAG, '%{public}s', 'Ability onWindowStageDestroy');
  }

  onForeground(): void {
    hilog.info(0x0000, PushLandingAbility.TAG, '%{public}s', 'Ability onForeground');
  }

  onBackground(): void {
    hilog.info(0x0000, PushLandingAbility.TAG, '%{public}s', 'Ability onBackground');
  }
}

配置透传消息 Ability

后端可以向客户端推送 App 的后台消息，而不展示通知栏。但开发者仍然可以通过特定的方法获取推送的数据。MPS 已经实现了不拉起应用子进程的后台消息。

开发者需继承 MpaasExtDefaultNcAbility 类实现自己的 Ability，如下所示：

import { MpaasExtDefaultNcAbility } from '@mpaas/push';

export default class MpaasBridgeExtMsgAbility extends MpaasExtDefaultNcAbility {

  async onCreate(): Promise<void> {
    // 收到eventId为9999的事件后执行回调函数
    emitter.on(innerEvent, (data) => {
      if (data.data != null) {
        console.log("onCreate receivedMsg="+JSON.stringify(data.data["receivedMsg"]))
      } else  {
        console.log("onCreate receivedMsg="+data.data)
      }

    });
    await super.onCreate()
  }

}

在 onCreate() 方法中执行 super.onCreate()，之后即可通过 MpaasExtDefaultNcAbility.getReceivedMsg() 获取后台推送的消息。

需要在 module.json5 文件中配置 MpaasBridgeExtMsgAbility，如下所示：

{
 "name": "MpaasBridgeExtMsgAbility",
 "srcEntry": "./ets/pushability/MpaasBridgeExtDeMsgAbility.ets",
 "launchType": "singleton",
 "startWindowIcon": "$media:icon",
 "startWindowBackground": "$color:start_window_background",
 "skills": [
 {
 "actions": [
 "action.ohos.push.listener"
 ]
 }
 ]
}

其中，skills 里配置 actions 内容为 action.ohos.push.listener。

重要

有且只能有一个 ability 定义该 action，若同时添加 uris 参数，则 uris 内容需为空。

角标清理

可以调用 MPS 提供的方法，实现在打开 App 的时候将应用的角标数字清理掉，方法如下所示：

BadgeUtil.clearBadge()