{"skill":{"slug":"harmonyos-mobpush-integration","displayName":"Harmonyos Mobpush Integration","summary":"Interactive guide for integrating MobTech MobPush into HarmonyOS NEXT projects with 6-step workflow. Use when user says \"我要在鸿蒙app中增加推送能力\", \"MobPush集成\", \"鸿蒙推送...","description":"---\nname: harmonyos-mobpush-integration\ndescription: Interactive guide for integrating MobTech MobPush into HarmonyOS NEXT projects with 6-step workflow. Use when user says \"我要在鸿蒙app中增加推送能力\", \"MobPush集成\", \"鸿蒙推送功能\", \"配置推送通知\", or asks about MobPush setup, ohpm configuration, Huawei push channel, push message handling, alias/tags management, or privacy compliance. Supports step-by-step interactive integration with user confirmation at each step.\ntags:\n  - harmonyos\n  - mobpush\n  - mobtech\n  - push-notification\n  - ohpm\n  - privacy\n  - interactive-integration\n  - huawei-push\n---\n\n# HarmonyOS MobPush 集成 Skill\n\n## 适用场景\n\n当用户提到以下任一主题时，使用本 skill：\n\n- 鸿蒙 MobPush 集成\n- 鸿蒙推送通知配置\n- MobPush 推送 SDK 接入（鸿蒙）\n- MobPush appKey / appSecret 配置\n- MobPush 隐私合规（鸿蒙端）\n- 华为推送通道配置（鸿蒙）\n- 推送消息接收与处理（鸿蒙）\n- 别名/标签/角标设置（鸿蒙）\n- **我要在鸿蒙app中增加推送能力**\n- **我要在鸿蒙项目中接入推送功能**\n- **帮我配置鸿蒙推送通知**\n- **一键集成 MobPush（鸿蒙）**\n- **自动配置 MobPush（鸿蒙）**\n\n---\n\n## 6 步交互式集成工作流\n\n当用户表达集成 MobPush 的意图时，执行以下 6 步交互式流程。每步操作前都需要展示内容给用户确认，获得明确同意后再执行。\n\n---\n\n### 步骤 1：启动流程\n\n#### 1-1 询问项目路径\n\n**主动询问用户**：\n\n```\n我来帮你集成 MobPush 推送功能到鸿蒙项目。\n\n请提供需要集成的鸿蒙项目根路径，例如：\n/Users/xxx/your-harmonyos-project\n\n请确保项目是有效的鸿蒙项目（包含 build-profile.json5 或 oh-package.json5 文件）。\n```\n\n#### 1-2 验证路径合法性\n\n**验证逻辑**：\n1. 检查路径是否存在\n2. 检查路径下是否有 `build-profile.json5` 或 `oh-package.json5`\n3. 检查是否为有效的鸿蒙 Stage 模型项目结构\n\n**如果不合法**：\n\n```\n路径验证失败：\n- 路径不存在或未找到 build-profile.json5 / oh-package.json5 文件\n- 请确认这是鸿蒙项目根目录\n\n请重新提供正确的项目路径。\n```\n\n**如果合法**：进入步骤 2\n\n---\n\n### 步骤 2：注册 MobPush 配置信息\n\n#### 2-1 生成配置模板文件\n\n**操作**：\n1. 执行 `assets/generate_excel_template.py`，生成 `assets/MobPush_Config_Template.xlsx`\n2. 将生成的模板复制到 鸿蒙项目根目录下，命名为 `MobPush_Config.xlsx`\n\n**告知用户**：\n\n```\n已在你项目的根目录生成 {path}/MobPush_Config.xlsx 配置文件。\n\n请打开文件填写：\n1. \"基础信息\"：appKey、appSecret、鸿蒙包名\n   （appKey/appSecret 从 https://www.mob.com/ 注册应用获取）\n2. \"华为推送\"：如需使用华为推送通道，填写 Client ID\n   （从 AppGallery Connect 获取，不需要可填写\"否\"）\n3. \"隐私合规\" 和 \"填写说明\" 有详细指引\n\n填写完成后告诉我\"填好了\"。\n```\n\n#### 2-2 等待用户填写 → 读取并验证\n\n**验证规则**：\n\n| 检查项       | 规则       | 不通过时的提示                       |\n| --------- | -------- | ----------------------------- |\n| appKey    | 必填       | \"基础信息 Sheet 中的 appKey 未填写\"    |\n| appSecret | 必填       | \"基础信息 Sheet 中的 appSecret 未填写\" |\n| 包名        | 必填，反域名格式 | \"包名格式不正确\"                     |\n\n**类型转换**：appKey、appSecret、包名、Client ID 等标识符字段强制转为字符串。\n\n如果合法，提取配置信息，进入步骤 3。\n\n---\n\n### 步骤 3：完成 SDK 集成\n\n#### 3-1 安装 ohpm 依赖\n\n**展示命令**：\n\n```bash\nohpm install @zztsdk/zztcore\nohpm install @zztsdk/mobpush\n```\n\n**询问**：\"以上命令将安装 MobPush 鸿蒙 SDK 依赖，是否确认？\"\n\n执行后确认安装成功。如失败则提示用户检查 ohpm 环境，或通过 DevEco Studio 依赖管理面板手动添加。\n\n#### 3-2 工程级 build-profile.json5 配置\n\n**展示修改内容**：\n\n```json5\n{\n  \"app\": {\n    \"products\": [\n      {\n        \"compatibleSdkVersion\": \"5.0.0(12)\",\n        \"buildOption\": {\n          \"strictMode\": {\n            \"useNormalizedOHMUrl\": true\n          }\n        }\n      }\n    ]\n  }\n}\n```\n\n**询问**：\"以上内容将合并到项目级 build-profile.json5，是否确认修改？\"\n\n#### 3-3 entry模块 module.json5 权限配置\n\n**展示添加的权限**：\n\n```json5\n\"requestPermissions\": [\n  { \"name\": \"ohos.permission.INTERNET\" },\n  { \"name\": \"ohos.permission.GET_NETWORK_INFO\" }\n]\n```\n\n**说明**：INTERNET 用于网络连接和推送，GET_NETWORK_INFO 用于检测网络状态。\n\n**询问**：\"以上权限将添加到 entry/src/main/module.json5，是否确认修改？\"\n\n#### 3-4 华为 Client ID 配置（可选）\n\n如果用户在 Excel 中启用了华为推送并填写了 Client ID：\n\n```json5\n\"metadata\": [\n  {\n    \"name\": \"client_id\",\n    \"value\": \"{用户填写的Client ID}\"\n  }\n]\n```\n\n**说明**：如使用华为推送，需在 AppGallery Connect 获取 Client ID 并配置到此。\n\n**询问**：\"是否在 module.json5 中添加以上华为 Client ID 配置？\"\n\n#### 3-5 项目同步提示\n\n```\n工程配置文件已修改，请在 DevEco Studio 中执行 Build -> Build Hap(s) 同步项目。\n⚠️ 确保 ohpm 依赖已正确安装后再编译。\n```\n\n进入步骤 4\n\n---\n\n### 步骤 4：插入初始化与隐私授权代码\n\n#### 5-1 说明合规原因\n\n```\n根据 MobTech 隐私合规要求，使用 MobPush 需在用户同意隐私政策后才能初始化。\n\n你需要：\n1. 首次启动时展示《隐私政策》弹窗\n2. 用户点击\"同意\"后调用初始化和隐私授权代码\n3. 用户不同意则不调用\n\n请告知：SDK 初始化代码应放在哪个文件、哪个方法中？\n以及用户点击\"同意\"的回调位置？\n```\n\n#### 5-2 等待用户告知 → 展示确认代码\n\n**初始化代码**：\n\n```typescript\nimport { ZztSDK } from '@zztsdk/zztcore';\nimport mobPush from '@zztsdk/mobpush';\n\nZztSDK.init(getContext(this), \"{appKey}\", \"{appSecret}\");\nmobPush.init(getContext(this), \"{appKey}\", \"{appSecret}\");\n```\n\n**隐私授权代码**：\n\n```typescript\n// 用户同意隐私政策后调用\nZztSDK.submitPolicyGrantResult(true);\n```\n\n**询问**：\"以上代码将插入到 {用户指定的位置}，是否确认？\"\n\n用户确认后执行插入，进入步骤 5。\n\n---\n\n### 步骤 5：SDK API 接入\n\n#### 6-1 推送监听\n\n建议在 AbilityStage 中设置，确保消息不丢失：\n\n```typescript\nimport mobPush from '@zztsdk/mobpush';\n\nlet receiver: mobPush.MobPushReceiver = {\n  onCustomMessageReceive: (message: mobPush.MobPushCustomMessage) => {\n    // 透传消息：message.getMessageId()、message.getContent()\n  },\n  onNotifyMessageReceive: (message: mobPush.MobPushNotifyMessage) => {\n    // 通知到达：message.getMobNotifyId()、message.getMessageId()、message.getTitle()、message.getContent()\n  },\n  onNotifyMessageOpenedReceive: (message: mobPush.MobPushNotifyMessage) => {\n    // 通知点击（需配合 notificationClickAck）：message.getMobNotifyId()、message.getTitle()、message.getContent()\n  },\n  onCommandReceive: (type: number, map: HashMap<string, Object>) => {\n    // type=1: RID更新  type=2: 厂商deviceToken更新\n    let channel = map.get(mobPush.KEY_CHANNEL);  // channel: mobpush/harmony\n    let token = map.get(mobPush.KEY_TOKEN);      // 对应channel的更新token\n  }\n};\nmobPush.addPushReceiver(receiver);\n// 页面销毁时：mobPush.removePushReceiver(receiver);\n```\n\n#### 6-2 通知点击回执上报\n\n必须在 UIAbility 的 `onCreate` 和 `onNewWant` 中调用：\n\n```typescript\nexport default class EntryAbility extends UIAbility {\n  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {\n    mobPush.notificationClickAck(want);\n  }\n  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {\n    mobPush.notificationClickAck(want);\n    // 获取推送附加数据: want?.parameters?.[\"pushData\"]\n  }\n}\n```\n\n#### 6-3 别名与标签\n\n```typescript\n// 别名\nmobPush.setAlias(\"alias\").then((data: mobPush.AliasResult) => console.log(data.errorCode, data.alias));\nmobPush.getAlias().then((data: mobPush.AliasResult) => console.log(data.alias, data.errorCode));\nmobPush.deleteAlias().then((data: mobPush.AliasResult) => console.log(data.errorCode));\n\n// 标签\nmobPush.addTags([\"tag\"]).then((data: mobPush.TagsResult) => console.log(data.errorCode, data.tags));\nmobPush.getTags().then((data: mobPush.TagsResult) => console.log(data.tags, data.errorCode));\nmobPush.deleteTags([\"tag\"]).then((data: mobPush.TagsResult) => console.log(data.errorCode, data.tags));\nmobPush.cleanTags().then((data: mobPush.TagsResult) => console.log(data.errorCode, data.tags));\n```\n\n#### 6-4 其他 API\n\n完整 API 参考[官方文档](https://www.mob.com/wiki/detailed?wiki=698&id=136)，包括：\n- `getRegistrationId(callback)` / `getRegistrationId(): Promise<string>` — 获取注册 ID（Callback/Promise 两种方式）\n- `setShowBadge(show: boolean)` — 设置是否显示角标\n- `getShowBadgeAsync(): Promise<boolean>` — 获取是否显示角标\n- `setBadgeCounts(count: number)` — 设置角标数\n- `stopPush()` — 停止推送（仅可通过 restartPush 重新打开）\n- `restartPush()` — 重新打开推送服务\n- `isPushStoppedAsync(): Promise<boolean>` — 判断推送是否已停止\n- `clearAllNotification()` — 清除所有通知\n- `getDeviceTokenAsync(): Promise<string>` — 获取厂商 token\n- `isNotificationEnabled(callback)` / `isNotificationEnabled(): Promise<boolean>` — 判断通知权限是否开启\n- `checkTcpStatus(callback)` / `checkTcpStatus(): Promise<boolean>` — 检测 TCP 连接状态\n- `removePushReceiver(receiver)` — 移除推送监听（页面销毁时调用）\n\n进入步骤 6\n\n---\n\n### 步骤 6：补充说明\n\n#### 7-1 生成项目级 README\n\n在用户项目根目录生成 `MOBPUSH_README.md`，包含集成说明、关键文件位置、后续修改指引。\n\n#### 7-2 完成告知\n\n```\nMobPush 鸿蒙端集成已完成！\n\n📁 生成的文件：\n- {project_path}/MOBPUSH_README.md — 集成说明文档\n- {project_path}/MobPush_Config.xlsx — 项目配置文件\n\n📝 关键文件位置：\n- SDK 配置：EntryAbility.ets 中的 ZztSDK.init()\n- 隐私授权：用户隐私同意回调中的 ZztSDK.submitPolicyGrantResult(true)\n- 华为推送：entry/src/main/module.json5 中的 client_id metadata\n- 编译配置：项目级 build-profile.json5 中的 buildOption\n\n📖 官方文档：\n- 集成指南：https://www.mob.com/wiki/detailed?wiki=697&id=136\n- SDK API：https://www.mob.com/wiki/detailed?wiki=698&id=136\n- 后台配置：https://www.mob.com/wiki/detailed?wiki=560&id=136\n- 合规说明：https://www.mob.com/wiki/detailed?wiki=745&id=136\n- 隐私政策：https://policy.zztfly.com/sdk/mobpush/privacy\n\n⚠️ 重要提醒：\n1. 包名与 MobTech 后台配置一致\n2. 华为推送需在 AppGallery Connect 正确配置\n3. 用户同意隐私政策后才能调用 ZztSDK.submitPolicyGrantResult(true)\n4. 通知点击回执必须在 UIAbility 的 onCreate 和 onNewWant 中调用\n```\n\n---\n\n## 附录：技术参考\n\n### A. 工程配置\n\n#### build-profile.json5\n```json5\n{\n  \"app\": {\n    \"products\": [{\n      \"compatibleSdkVersion\": \"5.0.0(12)\",\n      \"buildOption\": { \"strictMode\": { \"useNormalizedOHMUrl\": true } }\n    }]\n  }\n}\n```\n\n#### module.json5 权限\n```json5\n\"requestPermissions\": [\n  { \"name\": \"ohos.permission.INTERNET\" },\n  { \"name\": \"ohos.permission.GET_NETWORK_INFO\" }\n]\n```\n\n#### module.json5 华为推送 metadata\n```json5\n\"metadata\": [\n  { \"name\": \"client_id\", \"value\": \"华为Client ID\" }\n]\n```\n\n#### ohpm 依赖\n```bash\nohpm install @zztsdk/zztcore\nohpm install @zztsdk/mobpush\n```\n\n### B. 华为推送通道配置\n\n1. 登录 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html)\n2. \"我的项目\" → 目标应用 → \"项目设置 > 常规 > 应用\" 获取 **Client ID**\n3. 在 entry 的 `module.json5` 中配置 metadata\n4. 在 MobTech 后台配置鸿蒙厂商参数\n\n### C. 隐私合规\n\n- 首次冷启动展示隐私政策 → 用户同意 → 调用 `ZztSDK.submitPolicyGrantResult(true)`\n- 可选使用 `ZztCustomController` 自定义数据采集控制器\n- 隐私政策中需披露：SDK 名称 MobPush、第三方主体\"上海掌之淘信息技术有限公司\"、链接 https://policy.zztfly.com/sdk/mobpush/privacy\n- 完整合规说明：https://www.mob.com/wiki/detailed?wiki=745&id=136\n\n### D. 常见问题\n\n| 问题        | 可能原因                                    |\n| --------- | --------------------------------------- |\n| 收不到推送     | 包名不一致、appKey/appSecret 错误               |\n| 华为推送失败    | Client ID 未配置或错误                        |\n| 无点击回调     | 未在 UIAbility 中调用 notificationClickAck() |\n| 别名/标签操作失败 | errorCode 非 0，检查 SDK 初始化状态              |\n| 通知权限未开启   | 引导用户在系统设置中开启                            |\n\n---\n\n## 回答边界\n\n- 仅聚焦 HarmonyOS NEXT Stage 模型 + ArkTS 的 MobPush 集成与合规\n- 不扩展到 Android、iOS、服务端、非 MobTech SDK\n- 不伪造真实账号、密钥、签名值\n","topics":["Harmonyos","Mobpush","Huawei Push","Interactive Integration","Mobtech"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":317,"installsAllTime":12,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778322455487,"updatedAt":1778492885325},"latestVersion":{"version":"1.0.0","createdAt":1778322455487,"changelog":"Initial release with interactive, step-by-step MobPush integration workflow for HarmonyOS NEXT projects.\n\n- Guides users through 6-step integration, confirming actions at each stage.\n- Validates project path and user-filled configuration, ensuring correct environment before proceeding.\n- Automates SDK dependency installation and config updates (permissions, metadata).\n- Explicit privacy compliance step: enforces SDK init only after user consents.\n- Offers code samples for push reception, alias/tags, and core MobPush API.\n- Generates project-level README summarizing integration steps and key file locations.","license":"MIT-0"},"metadata":null,"owner":{"handle":"mobsupport","userId":"s1795q9k9a75n8jgb852pqydgd85dg1d","displayName":"MobSupport","image":"https://avatars.githubusercontent.com/u/242118548?v=4"},"moderation":null}