通知消息通过Push Kit通道直接下发，可在终端设备的通知中心、锁屏、横幅等展示，用户点击后拉起应用。您可以通过设置通知消息样式来吸引用户。
发送通知消息能力支持Phone、Tablet、PC/2in1设备。并且从18版本开始新增支持Wearable设备；从19版本开始，新增支持TV设备。
参见指导获取Push Token。
为确保应用可正常收到消息，应用发送通知前需调用requestEnableNotification方法弹出提醒，告知用户需要允许接收通知消息。示例代码如下：
// 文件路径: src/main/ets/entryability/EntryAbility.ets
import { BusinessError } from '@kit.BasicServicesKit';
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { notificationManager } from '@kit.NotificationKit';
export default class EntryAbility extends UIAbility {
onWindowStageCreate(windowStage: window.WindowStage) {
hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
windowStage.loadContent('pages/Index', (err, data) => {
if (err.code) {
hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
return;
}
hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
notificationManager.requestEnableNotification(this.context).then(() => {
hilog.info(0x0000, 'testTag', `[ANS] requestEnableNotification success`);
}).catch((err: BusinessError) => {
hilog.error(0x0000, 'testTag', `[ANS] requestEnableNotification failed, code is ${err.code}, message is ${err.message}`);
});
});
}
}
为确保点击消息可以正常跳转应用页面，在应用项目中完成skills标签配置，详情请参见点击消息动作。
应用服务端调用Push Kit服务端的REST API推送通知消息。
说明：
本示例仅包含REST API中部分消息字段，关于服务端开发的更多详情请参见端云调试。
请求URL（
https://oh-push-api.getui.com/v3/[appId]/messages:send）进行消息推送。
请求示例如下（注意category参数设置为实际消息类型）：
// Request URL
POST "https://oh-push-api.getui.com/v3/[appId]/messages:send"
// Request Header
Content-Type: application/json
Authorization: Bearer eyJ0eX******IUzI1NiJ9.eyJpc******YzNTZ9.j6y1NGM******NncAeLE
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "xxxxxx",// 替换为实际消息类型
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
// 通知是否在应用在前台情况下展示，仅对push-type为0的通知消息生效
"foregroundShow": true,
"notifyId": 12345
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true,
"ttl": 86400
}
}
[appId]：推送appId，请与个推进行商务及技术对接获取。
Authorization：JWT格式字符串，可参见Authorization获取。
push-type：0表示Alert消息，此处为通知消息场景。
actionType：0表示点击消息进入应用首页，1表示点击消息后进入应用内页。
token：Push Token，可参见获取Push Token获取。
ttl：（选填）消息缓存时间，详见ttl。
notifyId：（选填）自定义消息标识字段。不携带或者设置-1时，推送服务自动为每条消息生成一个唯一标识；不同的通知消息可以拥有相同的notifyId，实现新消息覆盖旧消息功能。仅支持数字，范围 [0, 2147483647]。详情请参见notifyId。
foregroundShow：（选填）通知消息是否在应用在前台时候展示。true表示应用在前后台都展示。false表示应用只在后台展示，应用在前台时，通知栏消息将不会展示。默认为true。foregroundShow为true时，receiveMessage不会被触发，无法获取消息数据。
检查项目模块级别下的src/main/module.json5中的skills标签标签配置，其中用于标识应用首页的skill（即配置了"entity.system.home"和"ohos.want.action.home"的skill）中不要配置uris，否则消息会接收不到。
说明：
module.json5文件中的skills标签下可以同时存在多个skill对象，每个对象对应一种能力。
若您需要同时设置推送消息跳转能力和其他跳转能力（如NFC跳转、浏览器跳转等），需要在skills数组中创建不同的skill对象，分别映射对应的能力。
点击消息进入应用首页skills标签配置示例：
{
"module": {
// ...
"abilities": [
{
"name": "TestAbility",
"srcEntry": "./ets/abilities/TestAbility.ets",
"exported": false,
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"skills": [
// 该skill标识应用首页，不要配置uris
{
"entities": [
"entity.system.home"
],
"actions": [
// "action.system.home"为API19以下版本配置，已废弃
"ohos.want.action.home"
]
},
// 其他skill配置
{}
]
}
]
}
}
发送消息时设置actionType字段为0。
// Request URL
POST "https://oh-push-api.getui.com/v3/[appId]/messages:send"
// Request Header
Content-Type: application/json
Authorization: Bearer eyJ0eX******IUzI1NiJ9.eyJpc******YzNTZ9.j6y1NGM******NncAeLE
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0,
"data": {"testKey": "testValue"}
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
场景化消息请求体中，接口URL版本为（
https://oh-push-api.getui.com/v3/[appId]/messages:send）。
在您的项目模块级别下的src/main/module.json5 中设置目标Ability中skills标签的actions或uris值，两种方式如下：
方式一：在skills标签中新增一个独立的skill对象，配置actions参数用于点击消息进入应用内页，示例如下：
{
"name": "TestAbility",
"srcEntry": "./ets/abilities/TestAbility.ets",
"exported": false,
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"skills": [
// 保持现有skill对象不变
{
"actions": [
"com.app.action"
]
},
// 新增一个独立的skill对象，配置actions参数
{
"actions": [
"com.test.action"
]
}
]
}
方式二：在skills标签中新增一个独立的skill对象，配置uris参数用于点击消息进入应用内页（必须同时配置actions参数和uris参数，actions参数为空），示例如下：
{
"name": "TestAbility",
"srcEntry": "./ets/abilities/TestAbility.ets",
"exported": false,
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"skills": [
// 保持现有skill对象不变
{
"actions": [
"com.app.action"
]
},
// 新增一个独立的skill对象，配置uris参数，且必须同时配置actions参数，actions参数为空字符串
{
"actions": [""],
"uris": [
{
"scheme": "https",
"host": "www.xxx.com",
"port": "8080",
"path": "push/test"
}
]
}
]
}
说明：
module.json5文件中的skills标签下可以同时存在多个skill对象，每个对象对应一种能力。
若您需要同时设置推送消息跳转能力和其他跳转能力（如NFC跳转、浏览器跳转等），需要在skills数组中创建不同的skill对象，分别映射对应的能力。
发送消息时clickAction中设置actionType字段为1。
// Request URL
POST "https://oh-push-api.getui.com/v3/[appId]/messages:send"
// Request Header
Content-Type: application/json
Authorization: Bearer eyJ0eX******IUzI1NiJ9.eyJpc******YzNTZ9.j6y1NGM******NncAeLE
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 1,
"action": "com.test.action",
"uri": "https://www.xxx.com:8080/push/test",
"data": {"testKey": "testValue"}
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
场景化消息请求体中，接口URL为（
https://oh-push-api.getui.com/v3/[appId]/messages:send）若action和uri都未匹配成功，则点击消息后会进入应用首页。
应用服务端调用Push Kit服务端的REST API推送通知消息时，可携带data字段，当用户点击消息时将传递数据至客户端应用。
调用REST API推送通知消息，消息体中clickAction携带data字段。
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0,
"data": {"testKey": "testValue"} // 携带data字段
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
data：点击消息时携带的JSON格式的数据。
在待跳转页面（以TestAbility为例）中的onCreate()方法中覆写如下代码（冷启动时进入该生命周期回调）：
// 文件路径: src/main/ets/abilities/TestAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
export default class TestAbility extends UIAbility {
onCreate(want: Want): void {
// 获取消息中传递的data数据
const data = want.parameters;
const value = want.parameters?.["testKey"]; // value: "testValue"
hilog.info(0x0000, 'testTag', 'Succeeded in getting message data, value is %{public}s', value);
// 根据实际业务场景对data进行处理
}
}
onNewWant()方法中覆写如下代码（热启动时进入该生命周期回调）：
// 文件路径: src/main/ets/abilities/TestAbility.ets
import { UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
export default class TestAbility extends UIAbility {
onNewWant(want: Want): void {
// 获取消息中传递的data数据
const data = want.parameters;
const value = want.parameters?.["testKey"]; // value: "testValue"
hilog.info(0x0000, 'testTag', 'Succeeded in getting message data, value is %{public}s', value);
// 根据实际业务场景对data进行处理
}
}
说明：
onNewWant()方法仅在单例（singleton）模式下可用。
Push Kit提供了多种通知消息样式，您可以自定义其中内容来吸引用户，从而提高应用的日活跃用户数量。
您在发送通知消息时notification 参数中必须携带title与body字段，来设置应用收到通知消息后展示在通知中心的标题与内容。文本内容最多显示3行，超出3行以“...”截断。
消息体示例：
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "推送服务",
"body": "推送服务（Push Kit）是个推提供的消息推送平台，建立了从云端到终端的消息推送通道。您通过集成推送服务，可以向客户端应用实时推送消息，构筑良好的用户关系，提升用户的感知度和活跃度。",
"clickAction": {
"actionType": 0
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
Wearable、TV不支持此通知样式。
您可以发送通知消息时携带badge字段来设置应用收到通知消息后以数字的形式展示角标，提醒用户查看消息。
消息体示例：
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "通知标题",
"body": "通知内容",
"badge":{
"addNum": 1,
"setNum": 99
},
"clickAction": {
"actionType": 0
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
addNum设置后为应用角标累加数字，非应用角标实际显示数字。
setNum设置后为应用角标实际显示数字。setNum优先级高于addNum。
打开应用或者点击、清理通知消息并不会清理角标数字，开发者可通过setBadgeNumber()方法清理角标，使用前需先导入模块。
当setBadgeNumber()方法中的badgeNumber设置为0时，可以实现清理效果。
说明：
Wearable不支持此通知样式。
推送服务禁止推送包含敏感信息的图片。
您可以发送通知消息时携带image字段设置消息大图标内容，提醒用户查看消息。
消息体示例：
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "推送服务",
"body": "推送服务是个推提供的消息推送平台",
"image": "https://***.png", // 支持的图片格式为PNG、JPG、JPEG、BMP，图片长*宽建议小于128*128像素，若超过49152像素，则图片不展示。
"clickAction": {
"actionType": 0
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
Wearable不支持此通知样式。
您可以发送通知消息时在notification中携带inboxContent和style字段设置通知消息为多行文本样式。最多可展示3行内容，每行内容无法完全展示时以“...”截断。
消息体示例：
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "推送个性化显示",
"body": "通知内容",
"style": 3,
"inboxContent": [
"1. 通知栏消息样式",
"2. 通知栏消息提醒方式和展示方式",
"3. 通知栏消息语言本地化"
],
"clickAction": {
"actionType": 0
}
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
说明：
多行文本样式需要设置style字段为3。
当您发送多条通知消息导致用户通知消息折叠时，多行文本样式在展开前显示的标题与内容取自title与body字段。
当用户展开多行文本消息，或仅存在一条多行文本消息时，通知中显示的标题与内容取自title与inboxContent字段。
为实现应用在后台时展示通知消息，在前台时只接收通知消息并自行完成业务处理，需要服务端和客户端协同配置，具体步骤可以参考以下：
服务端调用REST API推送通知消息，消息体中携带foregroundShow字段，并且设置为false（默认为true，表示前后台都展示） ，则应用在前台时不会展示通知消息。
{
"payload": {
"notification": {
"category": "MARKETING",
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
"foregroundShow": false // 设置为false则应用在前台时不会展示通知消息
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true
}
}
在客户端项目模块的src/main/module.json5文件的对应Ability配置中（以PushMessageAbility为例），skills标签的actions属性内容配置为action.ohos.push.listener（项目中有且只能有一个ability定义该action）。
{
"name": "PushMessageAbility",
"srcEntry": "./ets/abilities/PushMessageAbility.ets",
"launchType": "singleton",
"startWindowIcon": "$media:startIcon",
"startWindowBackground": "$color:start_window_background",
"exported": false,
"skills": [
// 保持现有skill对象不变
{
"actions": [
"com.app.action"
]
},
// 新增一个独立的skill对象，配置actions参数
{
"actions": [
"action.ohos.push.listener"
]
}
]
}
在客户端项目中，已经通过步骤2配置了actions属性内容的UIAbility类的onCreate()中（以PushMessageAbility为例），通过receiveMessage()方法传入PushType为"DEFAULT"获取通知消息，用于应用在前台时接收通知消息，示例代码如下：
// 文件路径: src/main/ets/abilities/PushMessageAbility.ets
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中的参数固定为DEFAULT
pushService.receiveMessage('DEFAULT', this, (payload) => {
try {
// 获取服务端传递的数据
const data: string = payload.data;
// TODO：业务自行处理
hilog.info(0x0000, 'testTag', 'Succeeded in getting notification,data=%{public}s',
JSON.stringify(JSON.parse(data)?.notification));
} catch (e) {
let errRes: BusinessError = e as BusinessError;
hilog.error(0x0000, 'testTag', 'Failed to process data: %{public}d %{public}s',
errRes.code, errRes.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);
}
}
}
当用户终端收到通知消息时，通知提示会播放系统默认通知铃声。如需实现自定义铃声功能（category取值为MARKETING不支持该功能）， 消息需要携带sound字段。此功能需要服务端和客户端协同配置，具体步骤可以参考以下：
将自定义铃声文件放在客户端工程中/resources/rawfile路径下（例如设置为alert.mp3，对应本地的/resources/rawfile/alert.mp3文件），重新编译安装应用程序包。
服务端调用REST API推送通知消息，消息体中携带sound字段。
// Request URL
POST "https://oh-push-api.getui.com/v3/[appId]/messages:send"
// Request Header
Content-Type: application/json
Authorization: Bearer eyJ0eX******IUzI1NiJ9.eyJpc******YzNTZ9.j6y1NGM******NncAeLE
push-type: 0
// Request Body
{
"payload": {
"notification": {
"category": "TRAVEL", // 替换为实际消息类型
"title": "普通通知标题",
"body": "普通通知内容",
"clickAction": {
"actionType": 0
},
"notifyId": 12345,
"sound": "alert.mp3", // category取值为MARKETING时，不支持该功能
"soundDuration": 10 // 请求同时携带sound字段时才会生效
}
},
"target": {
"token": ["o39qtoP7Nd6s*******2d4d5636"]
},
"pushOptions": {
"testMessage": true,
"ttl": 86400
}
}
以上文档对您是否有帮助？
