华为HarmonyOS灵活高效的消息推送服务(Push Kit) -- 8 发送通知扩展消息

场景介绍

当用户终端收到您发送的通知扩展消息时：

• 若您的应用进程不在前台，Push Kit会将消息内容传递给通知扩展进程，您可以在该进程中自行完成业务处理（例如：语音播报等）后，返回自定义消息内容，Push Kit将弹出通知提醒。您需要在10秒内返回消息内容，否则Push Kit将默认展示原有的消息内容。
• 若您的应用进程在前台，则不弹出通知提醒，您可以在应用进程中获取通知扩展消息内容并自行完成业务处理。

开通权益

• 推送通知扩展消息需要申请场景化消息权益，请参见申请推送通知扩展消息权益。

频控规则

调测阶段，每个项目每日全网最多可推送1000条测试消息。发送测试消息需设置testMessage为true。

正式发布阶段，单设备单应用下每日推送消息总条数受设备消息频控限制，所有场景化消息发送条数不超过3000条。

开发步骤

1. 参见指导获取Push Token。
2. 为确保应用可正常收到消息，建议应用发送通知前调用requestEnableNotification()方法弹出提醒，告知用户需要允许接收通知消息。详情请参见Notification Kit-请求通知授权。
3. 在您的工程内创建一个ExtensionAbility类型的组件并且继承RemoteNotificationExtensionAbility，完成onReceiveMessage()方法的覆写，代码示例如下： import { pushCommon, RemoteNotificationExtensionAbility } from '@kit.PushKit';import { image } from '@kit.ImageKit';import { hilog } from '@kit.PerformanceAnalysisKit';import { resourceManager } from '@kit.LocalizationKit';import { common } from '@kit.AbilityKit';export default class RemoteNotificationExtAbility extends RemoteNotificationExtensionAbility {async onReceiveMessage(remoteNotificationInfo: pushCommon.RemoteNotificationInfo): Promise<pushCommon.RemoteNotificationContent> {hilog.info(0x0000, 'testTag', 'TestExtAbility onReceiveMessage, remoteNotificationInfo');// Read the pixel map objectconst resourceMgr: resourceManager.ResourceManager = (this.context as common.UIExtensionContext).resourceManager;const fileData: Uint8Array = await resourceMgr.getMediaContent($r('app.media.icon'));const buffer = fileData.buffer;const imageSource: image.ImageSource = image.createImageSource(buffer as ArrayBuffer);const pixelMap: image.PixelMap = await imageSource.createPixelMap();if (pixelMap) {pixelMap.getImageInfo((err, imageInfo) => {if (imageInfo) {hilog.info(0x0000, 'testTag', `imageInfo ${imageInfo.size.width} * ${imageInfo.size.height}`);}});}// Return the replaced message content.return {title: 'Default replace title.',text: 'Default replace text.',badgeNumber: 1,setBadgeNumber: 2,overlayIcon: pixelMap,wantAgent: {abilityName: 'DemoAbility',parameters: {key: 'Default value'}}}}onDestroy(): void {hilog.info(0x0000, 'testTag', 'RemoteNotificationExtAbility onDestroy.');}}- 函数的返回值用于替换最终展示在终端的通知，title和text代表您要展示的通知标题与通知内容。- badgeNumber字段为展示通知时增加的角标数量，setBadgeNumber字段为展示通知时显示的角标数量，两者同时返回时，setBadgeNumber优先于badgeNumber。详情请参见RemoteNotificationContent。- overlayIcon字段为展示通知时的叠加图标。详情请参见RemoteNotificationContent。- wantAgent.abilityName字段为需要替换的点击拉起的落地页abilityName（例如DemoAbility），DemoAbility需要您自行适配开发。详情请参见RemoteWantAgent。- wantAgent.parameters字段表示拉起落地页透传参数。详情请参见RemoteWantAgent。
4. 在项目工程的src/main/module.json5文件的extensionAbilities模块中配置RemoteNotificationExtAbility的type和actions信息（有且仅有一个ExtensionAbility，配置如下，若同时添加uris参数，则uris****内容需为空）： "extensionAbilities": [{"name": "RemoteNotificationExtAbility","type": "remoteNotification","srcEntry": "./ets/entryability/RemoteNotificationExtAbility.ets","description": "RemoteNotificationExtAbility test","exported": false,"skills": [{"actions": ["action.hms.push.extension.remotenotification"]}]}]- type：固定值为remoteNotification，表示通知扩展的ExtensionAbility类型。- actions：固定值为action.hms.push.extension.remotenotification，用于接收通知扩展消息。
5. 应用服务端调用REST API推送消息，消息详情可参见场景化消息API接口功能介绍，请求示例如下： ​// Request URLPOST https://push-api.cloud.huawei.com/v3/[projectId]/messages:send// Request HeaderContent-Type: application/jsonAuthorization: Bearer eyJr*****OiIx---****.eyJh*****iJodHR--***.QRod*****4Gp---****push-type: 2// Request Body{"payload": {"extraData": "通知扩展场景携带的额外数据","notification": {"category": "EXPRESS","title": "通知标题","body": "通知内容","clickAction": {"actionType": 0}}},"target": {"token": ["IQAAAACy0tEjCgBijrEB3************8o0m5EdTXbdlhiIiX_vNGQ5Ic5rXWmw"]},"pushOptions": {"testMessage": true}}​- [projectId]：项目ID，登录AppGallery Connect网站，选择“我的项目”，在项目列表中选择对应的项目，左侧导航栏选择“项目设置”，在该页面获取。- Authorization：JWT格式字符串，可参见Authorization获取。- push-type：2表示通知扩展场景。- category：消息自分类类别，当前支持设置为EXPRESS，发送消息前请确保您已申请通知消息自分类权益。- actionType：0表示点击消息打开应用首页。- token：Push Token，可参见获取Push Token获取。- extraData：通知扩展场景可携带的额外数据，字符串类型。详情参见ExtensionPayload 通知扩展消息。- testMessage：测试消息标识，true表示测试消息。每个项目每天限制发送1000条测试消息，单次推送可发送Token数不超过10个。详情请参见testMessage。
6. 发送消息后，若您的应用进程不在前台，Push Kit会将通知消息内容传递给通知扩展进程，您在该进程中自行完成语音播报业务处理，并返回特定的消息内容（例如title、body等）后，Push Kit将弹出通知提醒。若您的应用进程在前台，则不弹出通知提醒，您可以通过receiveMessage()方法实时获取通知扩展消息数据，示例代码如下： import { UIAbility } from '@kit.AbilityKit';import { pushService } from '@kit.PushKit';import { BusinessError } from '@kit.BasicServicesKit';import { hilog } from '@kit.PerformanceAnalysisKit';/*** 此处以PushMessageAbility为例，接收通知扩展消息内容*/export default class PushMessageAbility extends UIAbility {onCreate(): void {try {// receiveMessage中的参数固定为IMpushService.receiveMessage('IM', this, (data) => {hilog.info(0x0000, 'testTag', 'Succeeded in getting message');});} catch (err) {let e: BusinessError = err as BusinessError;hilog.error(0x0000, 'testTag', 'Failed to get message: %{public}d %{public}s', e.code, e.message);}}}并且在项目模块的src/main/module.json5中的skills里配置actions内容为** action.ohos.push.listener（有且只能有一个ability定义该action，若同时添加uris参数，则uris内容需为空**）：{"name": "PushMessageAbility","srcEntry": "./ets/abilities/PushMessageAbility.ets","launchType": "singleton","startWindowIcon": "$media:icon","startWindowBackground": "$color:startWindowBackgroundColor","exported": false,"skills": [{"actions": ["action.ohos.push.listener"]}]}