《鸿蒙应用消息推送实战:Push Kit 接入与通知渠道管理》
鸿蒙应用消息推送实战:Push Kit 接入与通知渠道管理
消息推送是应用触达用户的关键通道:订单状态提醒、活动通知、重要消息提醒,都离不开一条稳定可靠的推送链路。本文以鸿蒙 Push Kit 为例,讲清推送的完整链路、接入步骤,以及通知渠道、角标、点击跳转这些容易踩坑的细节。
一、推送链路:消息是怎么到达手机的
一条推送消息要走完四个环节:应用服务器把消息发给 Push 服务端,Push 服务端按设备 Token 找到目标设备,通过系统通道下发到手机,系统再把消息展示为通知。开发者需要打通的其实只有两端:应用端拿到 Token 并上报给自己的服务器,服务器端按 Token 调用 Push 服务端接口下发。
理解这条链路很重要:很多“收不到推送”的问题,根源不在代码,而在 Token 没上报、Token 过期、或者服务端下发时选错了目标。
二、接入第一步:申请权限与获取 Token
在 module.json5 中声明推送相关权限,并向用户申请通知权限。鸿蒙的通知权限属于受限权限,需要在合适的时机动态申请,而不是一进应用就弹。
import { pushService } from '@kit.PushKit';
import { BusinessError } from '@kit.BasicServicesKit';
async function getPushToken(): Promise<string> {
try {
const token = await pushService.getToken();
return token;
} catch (err) {
const e = err as BusinessError;
console.error(`获取 Token 失败:${e.code} ${e.message}`);
return '';
}
}
拿到 Token 后要立刻上报到应用服务器,并和用户账号绑定。Token 会变化:应用重装、数据清除、系统升级都可能导致 Token 失效,应用应在每次启动时重新获取并比对上报,服务端也要处理 Token 失效的回执,及时清理无效 Token。
三、通知渠道:先分类,再发通知
Android 8.0 之后引入通知渠道,鸿蒙同样遵循“先建渠道、再发通知”的模型。不同业务用不同渠道:订单通知、营销通知、系统提醒分开建,用户可以在系统设置里单独关闭某一类,而不至于一刀切关掉全部推送。
import { notificationManager } from '@kit.NotificationKit';
const channel: notificationManager.NotificationChannel = {
id: 'order_channel',
name: '订单通知',
description: '订单状态变更提醒',
enableVibration: true
};
await notificationManager.addChannel(channel);
建渠道的时机建议放在应用首次启动或用户登录后,不要等到发通知时才临时创建。渠道一旦创建,名称和重要性等属性用户可以在系统设置中修改,应用侧重复创建不会覆盖用户的选择。
四、消息分类:普通消息与透传消息
Push Kit 的消息分两类:通知栏消息由系统直接展示,应用无需处理;透传消息只把数据送达应用,由应用自己决定如何处理。订单提醒、活动公告适合通知栏消息;数据同步、配置下发、静默更新适合透传消息。
透传消息要特别注意电量与频控:高频透传会被系统限流,重要业务不要依赖透传做实时同步,关键状态还是要以应用主动拉取为准。
五、点击跳转与角标管理
通知被点击后要跳到正确的页面。做法是在下发消息时带上自定义参数,应用收到点击事件后解析参数做路由跳转,比如订单号对应订单详情页。跳转前要先判断用户是否登录,未登录先走登录流程再进目标页,避免跳到空白页。
角标是另一个容易忽略的细节:未读数要和服务端保持一致,用户在应用内读完消息后要及时清除角标;角标数字长期不准,用户很快就会关掉通知权限。
// 收到通知点击事件后按参数跳转
function handleNotificationClick(extra: Record<string, string>): void {
const orderId = extra['orderId'];
if (orderId) {
// 跳转到订单详情页
router.pushUrl({ url: 'pages/OrderDetail', params: { orderId } });
}
}
六、收不到推送:按链路逐段排查
排查时按链路顺序走:先确认 Token 是否成功获取并上报;再看服务端下发接口的返回码,确认消息是否进入 Push 服务端;然后检查手机的通知权限、渠道开关和省电策略;最后确认应用是否被系统杀掉、以及是否处于免打扰时段。
最常见的三个坑:一是测试机开了省电模式,后台进程被清理;二是通知渠道被用户手动关闭,应用侧却还在按旧渠道发;三是服务端缓存了过期 Token,消息发到了不存在的设备上。
结语
推送接入本身不难,难的是把链路当成一个整体来维护:Token 的生命周期、渠道的分类、点击后的跳转、角标的一致性,任何一环掉链子,用户感受到的都是“收不到消息”。先把通知栏消息跑通,再按需引入透传消息,最后把排查清单沉淀成运维手册,推送这条链路才算真正立住了。
- 点赞
- 收藏
- 关注作者
评论(0)