Harmonyos Mobpush Integration — HarmonyOS Mobpush 集成

HarmonyOS MobPush 集成 Skill 适用场景 当用户提到以下任一主题时，使用本 skill： 鸿蒙 MobPush 集成 鸿蒙推送通知配置 MobPush 推送 SDK 接入（鸿蒙） MobPush appKey / appSecret 配置 MobPush 隐私合规（鸿蒙端） 华为推送通道配置（鸿蒙） 推送消息接收与处理（鸿蒙） 别名/标签/角标设置（鸿蒙） 我要在鸿蒙 app 中增加推送能力 我要在鸿蒙项目中接入推送功能 帮我配置鸿蒙推送通知 一键集成 MobPush（鸿蒙） 自动配置 MobPush（鸿蒙）

6 步交互式集成工作流 当用户表达集成 MobPush 的意图时，执行以下 6 步交互式流程。每步操作前都需要展示内容给用户确认，获得明确同意后再执行。

步骤 1：启动流程 1-1 询问项目路径 主动询问用户：我来帮你集成 MobPush 推送功能到鸿蒙项目。 请提供需要集成的鸿蒙项目根路径，例如：/Users/xxx/your-harmonyos-project 请确保项目是有效的鸿蒙项目（包含 build-profile.json5 或 oh-package.json5 文件）。 1-2 验证路径合法性 验证逻辑： 检查路径是否存在 检查路径下是否有 build-profile.json5 或 oh-package.json5 检查是否为有效的鸿蒙 Stage 模型项目结构 如果不合法： 路径验证失败：- 路径不存在或未找到 build-profile.json5 / oh-package.json5 文件 - 请确认这是鸿蒙项目根目录 请重新提供正确的项目路径。 如果合法：进入步骤 2

步骤 2：注册 MobPush 配置信息 2-1 生成配置模板文件 操作：执行 assets/generate_excel_template.py，生成 assets/MobPush_Config_Template.xlsx 将生成的模板复制到 鸿蒙项目根目录下，命名为 MobPush_Config.xlsx 告知用户：已在你项目的根目录生成 {path}/MobPush_Config.xlsx 配置文件。 请打开文件填写：

• "基础信息"：appKey、appSecret、鸿蒙包名 （appKey/appSecret 从 https://www.mob.com/ 注册应用获取）
• "华为推送"：如需使用华为推送通道，填写 Client ID （从 AppGallery Connect 获取，不需要可填写"否"）
• "隐私合规" 和 "填写说明" 有详细指引

填写完成后告诉我"填好了"。 2-2 等待用户填写 → 读取并验证 验证规则： 检查项 规则 不通过时的提示 appKey 必填 "基础信息 Sheet 中的 appKey 未填写" appSecret 必填 "基础信息 Sheet 中的 appSecret 未填写" 包名 必填，反域名格式 "包名格式不正确" 类型转换：appKey、appSecret、包名、Client ID 等标识符字段强制转为字符串。 如果合法，提取配置信息，进入步骤 3。

步骤 3：完成 SDK 集成 3-1 安装 ohpm 依赖 展示命令：ohpm install @zztsdk/zztcore ohpm install @zztsdk/mobpush 询问："以上命令将安装 MobPush 鸿蒙 SDK 依赖，是否确认？" 执行后确认安装成功。如失败则提示用户检查 ohpm 环境，或通过 DevEco Studio 依赖管理面板手动添加。 3-2 工程级 build-profile.json5 配置 展示修改内容：{ "app": { "products": [ { "compatibleSdkVersion": "5.0.0(12)", "buildOption": { "strictMode": { "useNormalizedOHMUrl": true } } } ] } } 询问："以上内容将合并到项目级 build-profile.json5，是否确认修改？" 3-3 entry模块 module.json5 权限配置 展示添加的权限："requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_NETWORK_INFO" } ] 说明：INTERNET 用于网络连接和推送，GET_NETWORK_INFO 用于检测网络状态。 询问："以上权限将添加到 entry/src/main/module.json5，是否确认修改？" 3-4 华为 Client ID 配置（可选） 如果用户在 Excel 中启用了华为推送并填写了 Client ID："metadata": [ { "name": "client_id", "value": "{用户填写的Client ID}" } ] 说明：如使用华为推送，需在 AppGallery Connect 获取 Client ID 并配置到此。 询问："是否在 module.json5 中添加以上华为 Client ID 配置？" 3-5 项目同步提示 工程配置文件已修改，请在 DevEco Studio 中执行 Build -> Build Hap(s) 同步项目。 确保 ohpm 依赖已正确安装后再编译。 进入步骤 4

步骤 4：插入初始化与隐私授权代码 5-1 说明合规原因 根据 MobTech 隐私合规要求，使用 MobPush 需在用户同意隐私政策后才能初始化。 你需要：

• 首次启动时展示《隐私政策》弹窗
• 用户点击"同意"后调用初始化和隐私授权代码
• 用户不同意则不调用

请告知：SDK 初始化代码应放在哪个文件、哪个方法中？以及用户点击"同意"的回调位置？ 5-2 等待用户告知 → 展示确认代码 初始化代码：import { ZztSDK } from '@zztsdk/zztcore'; import mobPush from '@zztsdk/mobpush'; ZztSDK.init(getContext(this), "{appKey}", "{appSecret}"); mobPush.init(getContext(this), "{appKey}", "{appSecret}"); 隐私授权代码：// 用户同意隐私政策后调用 ZztSDK.submitPolicyGrantResult(true); 询问："以上代码将插入到 {用户指定的位置}，是否确认？" 用户确认后执行插入，进入步骤 5。

步骤 5：SDK API 接入 6-1 推送监听 建议在 AbilityStage 中设置，确保消息不丢失：import mobPush from '@zztsdk/mobpush'; let receiver: mobPush.MobPushReceiver = { onCustomMessageReceive: (message: mobPush.MobPushCustomMessage) => { // 透传消息：message.getMessageId()、message.getContent() }, onNotifyMessageReceive: (message: mobPush.MobPushNotifyMessage) => { // 通知到达：message.getMobNotifyId()、message.getMessageId()、message.getTitle()、message.getContent() }, onNotifyMessageOpenedReceive: (message: mobPush.MobPushNotifyMessage) => { // 通知点击（需配合 notificationClickAck）：message.getMobNotifyId()、message.getTitle()、message.getContent() }, onCommandReceive: (type: number, map: HashMap) => { // type=1: RID更新 type=2: 厂商deviceToken更新 let channel = map.get(mobPush.KEY_CHANNEL); // channel: mobpush/harmony let token = map.get(mobPush.KEY_TOKEN); // 对应channel的更新token } }; mobPush.addPushReceiver(receiver); // 页面销毁时：mobPush.removePushReceiver(receiver); 6-2 通知点击回执上报 必须在 UIAbility 的 onCreate 和 onNewWant 中调用：export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { mobPush.notificationClickAck(want); } onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void { mobPush.notificationClickAck(want); // 获取推送附加数据: want?.parameters?.["pushData"] } } 6-3 别名与标签 // 别名 mobPush.setAlias("alias").then((data: mobPush.AliasResult) => console.log(data.errorCode, data.alias)); mobPush.getAlias().then((data: mobPush.AliasResult) => console.log(data.alias, data.errorCode)); mobPush.deleteAlias().then((data: mobPush.AliasResult) => console.log(data.errorCode)); // 标签 mobPush.addTags(["tag"]).then((data: mobPush.TagsResult) => console.log(data.errorCode, data.tags)); mobPush.getTags().then((data: mobPush.TagsResult) => console.log(data.tags, data.errorCode)); mobPush.deleteTags(["tag"]).then((data: mobPush.TagsResult) => console.log(data.errorCode, d