鸿蒙 Push 接入实践：从开通服务到通知点击，客户端与后端如何协作

给一款学习类应用接入推送时，最容易产生的疑问是：控制台已经能把通知发到手机，是不是就算接好了？后续交给后端，客户端还要做什么？

能收到控制台消息，说明这次测试使用的应用、Token 和通知通道能够协同工作。要做成可上线的业务能力，还需要把账号绑定、发送规则、退出解绑、点击跳转和异常处理接起来。

本文以一个虚构的学习应用为例，梳理原生 HarmonyOS 应用接入 Push Kit 的完整流程。应用名、包名、域名、标识和接口示例均已脱敏；文中的自有业务接口是建议契约，不代表已经部署的接口。讨论范围为通知栏通知，不涉及 Android HMS 接入、后台消息、语音播报或实况窗。

一、先确定哪些提醒需要服务器

假设应用有四类提醒：

场景	推荐触发方式	点击后打开
用户自行设置时间的学习提醒	若原有本地提醒已满足需求，可继续使用；跨设备同步等需求另行设计	学习首页
晚间学习任务提醒	后端根据当天任务状态和用户开关决定是否发送	学习首页
早间复习提醒	后端根据待复习内容和用户开关决定是否发送	学习首页
每日一句订阅提醒	后端根据订阅状态和内容发布时间决定是否发送	对应内容的应用内网页

固定时间不意味着必须由后端发送。是否依赖服务器上的学习状态、订阅关系和最新内容，才是选择方式的重要依据。

本地通知由应用在设备侧安排；远程通知由业务服务器通过 Push Kit 下发。对于本文的普通通知场景，它们都受应用的系统通知开关控制，无需让用户分别授予两套“允许通知”。Push Kit 与 Notification Kit 的分工，可参考官方 Push Kit 简介。

二、从创建应用到上线，完整流程是什么

![在这里插入图片描述](https://i-blog.csdnimg.cn/direct/484f08f5b0a54d0e93b59eb8fff1ae1e.png)

图中是完整目标流程，不表示所有环节已经开发完成。项目通常需要以下角色协作：

阶段	主要负责人	要做的操作	需要准备的内容
创建项目和应用	平台管理员、客户端	创建原生 HarmonyOS 应用，核对控制台与工程身份一致	包名、应用标识、项目标识、开发者权限
开通 Push	平台管理员	开通推送服务，核对数据处理位置	所属项目、目标应用
申请消息分类	产品或运营、平台管理员	按真实使用场景提交材料，确认审核结果	场景说明、通知样例、触发条件、用户操作说明
核查应用签名	客户端、发布负责人	按开通状态配置调试和发布签名	相应证书、Profile；调试时还可能需要设备信息
建立服务端调用能力	后端、平台管理员	配置服务账号和鉴权，接入消息发送 API	项目 ID、服务账号及私钥等服务端凭据
完成客户端基础接入	客户端	查询和申请通知权限、获取 Token、处理通知点击	UIAbilityContext、当前 Token、点击协议
建立业务绑定	客户端、后端	登录注册、Token 更新、退出解绑、换号重绑	登录态、安装实例标识、Token、平台及版本
开发发送任务	后端、产品	筛选用户，生成内容，调度发送，处理结果	用户开关、任务状态、发送时间、分类、标题、正文、有效期
联调和发布	客户端、后端、测试、发布负责人	验证真实签名包、账号切换、收取通知及点击落地	测试账号、当前安装的 Token、验收清单

控制台入口名称可能随版本变化，实际操作应以开通推送服务中的当前指引为准。

三、开通服务、消息分类、用户授权和签名是不同的事

这一部分值得在开发前对齐，否则很容易出现“权限已经通过，怎么还不能用”的误会。

开通 Push 服务，是为项目和应用准备云端推送能力。

申请消息自分类权益，是让应用按照获批的业务分类发送消息。分类应同时符合实际内容、触发条件和获批范围。不能因为某一种分类审核通过，就把所有学习提醒、内容订阅或营销消息统一塞进这个分类。具体要求见自分类权益申请说明和Push 接入规范。

用户允许通知，是设备上的系统授权。开发者后台审核通过，不会替用户打开通知开关；拿到 Token，也不能据此判断通知已经获准展示。

签名与 Profile，负责应用身份及相关能力配置。证书和 Profile 不是同一个文件，不能笼统地说“接入 Push 必须换证书”，也不能一概说“不需要更新签名配置”。

按照官方当前开通流程，手动调试签名应在开通 Push 后重新申请调试 Profile；发布阶段也需要使用开通后申请的发布 Profile 完成签名。支持相应能力的 DevEco Studio 自动签名，可以在勾选 Push Kit 后自动重新签名。应结合项目已有配置核查，不必因为一次消息分类审核就随意更换证书本体。官方签名配置步骤

因此，测试包已经收到通知，只能作为该次测试成功的证据；正式发布包的签名与配置仍要单独确认。

四、客户端先完成三件事

1. 把通知权限和 Token 能力统一封装

可以在公共模块建立一个 PushService，让首页、设置页和调试页共用它：

方法	职责
isNotificationEnabled()	查询真实的系统通知开关
requestNotificationPermission(context)	必要时发起授权，并返回重新查询后的状态
openNotificationSettings(context)	打开应用通知设置
getToken()	获取当前应用安装实例的 Push Token

授权流程建议是“先查询 → 未开启时申请 → 再查询”。同时到达的申请应合并，避免多个页面各自触发一次请求。状态查询失败应作为错误处理，不要直接记成“用户关闭了通知”。平台接口入口见请求通知授权。

原来负责权限埋点的代码，可以继续作为上层调用入口：系统能力交给 PushService，埋点层只负责上报和去重。这样既能整理旧逻辑，也不必把业务账号和统计依赖塞进基础服务。

还有一个容易遗漏的细节：旧版 openNotificationSettings() 完成，只表示设置界面已打开。用户可能没有开启通知，也可能在里面把通知关闭。设置界面采用半模态形式时，关闭后不一定触发应用前后台切换，因此可以在页面根容器恢复焦点时重新读取开关，并保留页面显示、应用返回前台时的刷新。HarmonyOS SDK 团队的通知设置说明

2. 获取 Token，再与自己的后端建立账号绑定

Token 用来定位推送目标，不能作为固定的硬件设备号，也不能直接等同于用户 ID。重装、清理数据或平台侧变化后，都应重新获取当前值并按约定同步。获取接口可从官方 Push Token 文档查阅。

“获取 Token”和“上传 Token”是两个步骤：前者调用 Push Kit，后者调用自己的业务接口。控制台手动测试可以直接填当前 Token；正式业务需要后端保存有效的账号绑定。官方也建议成功获取 Token 后及时上报应用服务端。Push Kit 业务流程

下面是一种自有业务接口的建议设计，不是华为接口，也不是已经实现的服务：

PUT /api/push/installations/{installationId}
Authorization: Bearer <BUSINESS_SESSION_TOKEN>
Content-Type: application/json

{
  "pushToken": "<CURRENT_PUSH_TOKEN>",
  "platform": "harmonyos",
  "appVersion": "1.0.0",
  "notificationEnabled": true
}

这里的 installationId 是应用生成的安装实例标识，随重装可以变化。后端从经过验证的登录态确定用户身份，不依赖客户端随意传入的用户 ID。机型、系统版本等可以用于排查问题，但不是发送通知的必需地址；是否上传应按实际需要确定。notificationEnabled 只是客户端最后一次观察到的状态，不能保证之后一直有效。

绑定接口应幂等，至少处理以下情况：

时机	客户端和后端的配合
用户登录	获取当前 Token，绑定当前账号和安装实例
Token 或绑定信息变化	更新服务端记录，避免继续使用旧目标
同一个账号多设备登录	按产品约定保留多设备绑定或选择目标设备
退出登录	停止该账号与该安装实例关联的业务推送
切换账号	解除旧绑定，建立新绑定；避免迟到请求覆盖新账号
弱网或接口失败	重试并校验当前登录态，防止旧账号请求被重放

退出时只清除本地变量，并不会自动通知后端。如果解绑失败或用户离线退出，服务器可能暂时不知道这件事；上线前需要明确重试、会话失效和有效绑定校验策略。停止后续发送，也不代表能自动撤回已经提交或投递的通知。

3. 接住通知点击，跳转到正确页面

对于普通学习提醒，点击打开首页即可。对于每日一句，则需要双方约定内容地址或内容标识，让客户端打开对应落地页。

应用内网页与外部浏览器也应提前约定。本文选择现有的应用内 WebView 页面承载内容。

五、后端负责决定发给谁、何时发、发什么

正式发送链路是：业务后端查询有效绑定和提醒条件，调用华为 Push 服务，由平台向设备投递通知。客户端不需要为此保持业务长连接，也不应依赖页面定时器去模拟服务器推送。

服务端开发可拆成四部分：

1. 认证与配置：准备服务账号及相应凭据，按基于服务账号生成鉴权令牌配置认证与发送接口。服务端私钥留在服务端，客户端只需要获取自己的 Push Token。
2. 业务筛选：检查提醒开关、订阅关系、任务是否完成、账号绑定是否有效，以及是否已经发送过。
3. 消息构造与发送：设置实际获批的分类、通知标题和正文、当前目标 Token、有效期及点击参数。
4. 结果处理：记录请求结果，按错误类型重试或清理失效绑定，需要时接入回执、报告与点击统计。

以本文使用的原生 HarmonyOS 通知 V3 为例，服务端发送地址与关键请求头如下；完整请求体应按对应版本文档组装：

POST https://push-api.cloud.huawei.com/v3/{projectId}/messages:send
Authorization: Bearer <SERVER_JWT>
Content-Type: application/json
push-type: 0

其中路径参数是 projectId。设备 Push Token、自有业务登录令牌和服务端鉴权 JWT 是三种用途不同的值，不能相互替代。接入时应从原生 HarmonyOS 发送通知消息文档核对请求体和鉴权入口，避免把 Android HMS 或其他版本示例混进来。

定时任务还需要关注时区、重复发送和过期提醒。例如“当天尚未完成学习”应在发送前重新判断；临近截止时间的提醒不宜设置过长的有效期。后台按计划时间触发请求，并不保证设备能在同一秒展示通知。

同时，API 接受请求、设备收到通知、用户点击通知，是不同的事件。不能只根据一次接口成功响应，就把整条链路记为完成。

六、每日一句的点击参数怎样设计

客户端和后端可以先约定一个简单、可调整的临时协议。以下是放在通知 V3 请求 payload.notification.clickAction 下的片段，不是完整发送请求：

{
  "actionType": 1,
  "action": "com.example.learning.push.OPEN_DAILY_SENTENCE",
  "data": {
    "url": "https://learning.example.com/daily-sentence/sample"
  }
}

actionType: 1 表示进入应用内页；action 与客户端在 module.json5 中配置的独立 skill 保持一致。不要为了这个入口覆盖已有的其他启动配置。

华为会把 clickAction.data 中的数据传到 Want.parameters。因此这份协议读取的是 want.action 和 want.parameters.url，不应又假设里面还有一层 data 字符串。官方应用内页跳转与传参说明

客户端需要同时覆盖两种入口：应用冷启动时的 onCreate()，以及单实例 UIAbility 再次接收 Want 时的 onNewWant()。是否采用单实例模式，应结合现有应用结构明确配置。

收到点击参数后，先识别 action，再校验内容地址，最后等待页面条件就绪：

• 普通启动和其他业务 action 继续走原有逻辑。
• 每日一句只接受受信任业务域名的 HTTPS 地址；域名应解析后严格匹配，不能只判断是否“包含”某段字符串。
• 缺少网址或传入空字符串时，可以打开预先约定的默认每日一句入口。
• 明确传入格式错误、非受信任域名或不支持协议的地址时拒绝跳转，不能悄悄改成默认地址来掩盖问题。
• 尚未完成协议、登录或导航初始化时，先暂存点击，待条件满足后再处理。

这次实践选择“未处理的点击只保留最近一次”。这是产品策略，不是平台限制。导航还需要避开登录成功后清空页面栈的时机，否则可能出现刚打开落地页又被首页覆盖的问题。

后端最终字段调整时，优先改统一的参数解析层，避免每个页面各自理解一套推送数据。

七、怎样验证接入完成

建议按从平台通道到业务行为的顺序验收：

验证项	通过条件
控制台发送	当前测试安装实例的 Token 可以收到通知
用户授权	允许、拒绝及在设置中修改开关后，应用读取的状态正确
Token 注册	登录后后端保存当前 Token；重装后不会继续只向旧 Token 发送
账号隔离	退出和换号后不会继续为旧账号产生新的有效业务发送
业务规则	已完成任务、未订阅内容、关闭提醒的用户符合预期筛选规则
通知点击	前台、后台、进程未运行、需要登录等状态都能正确落地
异常参数	非法网址、缺失字段、未知 action 不导致崩溃或错误页面
正式签名包	使用对应发布配置安装后，重新完成获取 Token、发送和点击验证
发送结果	能区分平台受理、设备送达与用户点击，失败可定位

Debug 页可以提供“查看通知权限、申请通知权限、打开通知设置、获取 Token、模拟通知点击”等工具。模拟点击适合快速检查路由，但仍要通过真实通知验证系统分发、冷启动及网页加载。用于复制完整 Token 的调试入口不应无条件向普通用户开放。

卸载重装后收不到通知时，应先取当前安装的 Token，再检查发送目标、通知开关和签名配置，而不是反复向原来的 Token 发送。

八、这次实践完成到了哪一步

截至本文整理时，客户端已完成通知权限统一封装、Push Token 获取封装、调试入口，以及每日一句点击的参数解析和冷、热启动路由；相关行为测试和 Debug 构建已通过。控制台向测试手机发送通知也已经验证成功。

登录后的 Token 自动获取与上传、Token 更新同步、退出解绑、换号重绑，以及后端定时发送仍属于下一阶段联调工作。此次权限改造和真实通知点击进入每日一句，也需要继续在真机上验收。

这次接入让前后端职责变得清晰：客户端提供可用的推送目标，维护账号与安装实例的关系，并负责用户授权和点击落地；后端维护发送规则、有效绑定和消息任务；平台负责承载投递。按照这些边界推进，才能从“发出一条测试消息”逐步走到可运行、可排查的正式业务。