Skill: mobsupport/harmonyos-mobpush-integration (version 1.0.0)

--- name: harmonyos-mobpush-integration description: 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. tags: - harmonyos - mobpush - mobtech - push-notification - ohpm - privacy - interactive-integration - huawei-push --- # 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 验证路径合法性 **验证逻辑**： 1. 检查路径是否存在 2. 检查路径下是否有 `build-profile.json5` 或 `oh-package.json5` 3. 检查是否为有效的鸿蒙 Stage 模型项目结构 **如果不合法**： ``` 路径验证失败： - 路径不存在或未找到 build-profile.json5 / oh-package.json5 文件 - 请确认这是鸿蒙项目根目录 请重新提供正确的项目路径。 ``` **如果合法**：进入步骤 2 --- ### 步骤 2：注册 MobPush 配置信息 #### 2-1 生成配置模板文件 **操作**： 1. 执行 `assets/generate_excel_template.py`，生成 `assets/MobPush_Config_Template.xlsx` 2. 将生成的模板复制到 鸿蒙项目根目录下，命名为 `MobPush_Config.xlsx` **告知用户**： ``` 已在你项目的根目录生成 {path}/MobPush_Config.xlsx 配置文件。 请打开文件填写： 1. "基础信息"：appKey、appSecret、鸿蒙包名 （appKey/appSecret 从 https://www.mob.com/ 注册应用获取） 2. "华为推送"：如需使用华为推送通道，填写 Client ID （从 AppGallery Connect 获取，不需要可填写"否"） 3. "隐私合规" 和 "填写说明" 有详细指引 填写完成后告诉我"填好了"。 ``` #### 2-2 等待用户填写 → 读取并验证 **验证规则**： | 检查项 | 规则 | 不通过时的提示 | | --------- | -------- | ----------------------------- | | appKey | 必填 | "基础信息 Sheet 中的 appKey 未填写" | | appSecret | 必填 | "基础信息 Sheet 中的 appSecret 未填写" | | 包名 | 必填，反域名格式 | "包名格式不正确" | **类型转换**：appKey、appSecret、包名、Client ID 等标识符字段强制转为字符串。 如果合法，提取配置信息，进入步骤 3。 --- ### 步骤 3：完成 SDK 集成 #### 3-1 安装 ohpm 依赖 **展示命令**： ```bash ohpm install @zztsdk/zztcore ohpm install @zztsdk/mobpush ``` **询问**："以上命令将安装 MobPush 鸿蒙 SDK 依赖，是否确认？" 执行后确认安装成功。如失败则提示用户检查 ohpm 环境，或通过 DevEco Studio 依赖管理面板手动添加。 #### 3-2 工程级 build-profile.json5 配置 **展示修改内容**： ```json5 { "app": { "products": [ { "compatibleSdkVersion": "5.0.0(12)", "buildOption": { "strictMode": { "useNormalizedOHMUrl": true } } } ] } } ``` **询问**："以上内容将合并到项目级 build-profile.json5，是否确认修改？" #### 3-3 entry模块 module.json5 权限配置 **展示添加的权限**： ```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： ```json5 "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 需在用户同意隐私政策后才能初始化。 你需要： 1. 首次启动时展示《隐私政策》弹窗 2. 用户点击"同意"后调用初始化和隐私授权代码 3. 用户不同意则不调用 请告知：SDK 初始化代码应放在哪个文件、哪个方法中？ 以及用户点击"同意"的回调位置？ ``` #### 5-2 等待用户告知 → 展示确认代码 **初始化代码**： ```typescript import { ZztSDK } from '@zztsdk/zztcore'; import mobPush from '@zztsdk/mobpush'; ZztSDK.init(getContext(this), "{appKey}", "{appSecret}"); mobPush.init(getContext(this), "{appKey}", "{appSecret}"); ``` **隐私授权代码**： ```typescript // 用户同意隐私政策后调用 ZztSDK.submitPolicyGrantResult(true); ``` **询问**："以上代码将插入到 {用户指定的位置}，是否确认？" 用户确认后执行插入，进入步骤 5。 --- ### 步骤 5：SDK API 接入 #### 6-1 推送监听 建议在 AbilityStage 中设置，确保消息不丢失： ```typescript 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<string, Object>) => { // type=1: RID更新 type=2: 厂商deviceToken更新 let channel = map.get(mobPush.KEY_CHANNEL); // channel: mobpush/harmony let [REDACTED_SECRET]); // 对应channel的更新token } }; mobPush.addPushReceiver(receiver); // 页面销毁时：mobPush.removePushReceiver(receiver); ``` #### 6-2 通知点击回执上报 必须在 UIAbility 的 `onCreate` 和 `onNewWant` 中调用： ```typescript 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 别名与标签 ```typescript // 别名 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, data.tags)); mobPush.cleanTags().then((data: mobPush.TagsResult) => console.log(data.errorCode, data.tags)); ``` #### 6-4 其他 API 完整 API 参考[官方文档](https://www.mob.com/wiki/detailed?wiki=698&id=136)，包括： - `getRegistrationId(callback)` / `getRegistrationId(): Promise<string>` — 获取注册 ID（Callback/Promise 两种方式） - `setShowBadge(show: boolean)` — 设置是否显示角标 - `getShowBadgeAsync(): Promise<boolean>` — 获取是否显示角标 - `setBadgeCounts(count: number)` — 设置角标数 - `stopPush()` — 停止推送（仅可通过 restartPush 重新打开） - `restartPush()` — 重新打开推送服务 - `isPushStoppedAsync(): Promise<boolean>` — 判断推送是否已停止 - `clearAllNotification()` — 清除所有通知 - `getDeviceTokenAsync(): Promise<string>` — 获取厂商 token - `isNotificationEnabled(callback)` / `isNotificationEnabled(): Promise<boolean>` — 判断通知权限是否开启 - `checkTcpStatus(callback)` / `checkTcpStatus(): Promise<boolean>` — 检测 TCP 连接状态 - `removePushReceiver(receiver)` — 移除推送监听（页面销毁时调用） 进入步骤 6 --- ### 步骤 6：补充说明 #### 7-1 生成项目级 README 在用户项目根目录生成 `MOBPUSH_README.md`，包含集成说明、关键文件位置、后续修改指引。 #### 7-2 完成告知 ``` MobPush 鸿蒙端集成已完成！ 📁 生成的文件： - {project_path}/MOBPUSH_README.md — 集成说明文档 - {project_path}/MobPush_Config.xlsx — 项目配置文件 📝 关键文件位置： - SDK 配置：EntryAbility.ets 中的 ZztSDK.init() - 隐私授权：用户隐私同意回调中的 ZztSDK.submitPolicyGrantResult(true) - 华为推送：entry/src/main/module.json5 中的 client_id metadata - 编译配置：项目级 build-profile.json5 中的 buildOption 📖 官方文档： - 集成指南：https://www.mob.com/wiki/detailed?wiki=697&id=136 - SDK API：https://www.mob.com/wiki/detailed?wiki=698&id=136 - 后台配置：https://www.mob.com/wiki/detailed?wiki=560&id=136 - 合规说明：https://www.mob.com/wiki/detailed?wiki=745&id=136 - 隐私政策：https://policy.zztfly.com/sdk/mobpush/privacy ⚠️ 重要提醒： 1. 包名与 MobTech 后台配置一致 2. 华为推送需在 AppGallery Connect 正确配置 3. 用户同意隐私政策后才能调用 ZztSDK.submitPolicyGrantResult(true) 4. 通知点击回执必须在 UIAbility 的 onCreate 和 onNewWant 中调用 ``` --- ## 附录：技术参考 ### A. 工程配置 #### build-profile.json5 ```json5 { "app": { "products": [{ "compatibleSdkVersion": "5.0.0(12)", "buildOption": { "strictMode": { "useNormalizedOHMUrl": true } } }] } } ``` #### module.json5 权限 ```json5 "requestPermissions": [ { "name": "ohos.permission.INTERNET" }, { "name": "ohos.permission.GET_NETWORK_INFO" } ] ``` #### module.json5 华为推送 metadata ```json5 "metadata": [ { "name": "client_id", "value": "华为Client ID" } ] ``` #### ohpm 依赖 ```bash ohpm install @zztsdk/zztcore ohpm install @zztsdk/mobpush ``` ### B. 华为推送通道配置 1. 登录 [AppGallery Connect](https://developer.huawei.com/consumer/cn/service/josp/agc/index.html) 2. "我的项目" → 目标应用 → "项目设置 > 常规 > 应用" 获取 **Client ID** 3. 在 entry 的 `module.json5` 中配置 metadata 4. 在 MobTech 后台配置鸿蒙厂商参数 ### C. 隐私合规 - 首次冷启动展示隐私政策 → 用户同意 → 调用 `ZztSDK.submitPolicyGrantResult(true)` - 可选使用 `ZztCustomController` 自定义数据采集控制器 - 隐私政策中需披露：SDK 名称 MobPush、第三方主体"上海掌之淘信息技术有限公司"、链接 https://policy.zztfly.com/sdk/mobpush/privacy - 完整合规说明：https://www.mob.com/wiki/detailed?wiki=745&id=136 ### D. 常见问题 | 问题 | 可能原因 | | --------- | --------------------------------------- | | 收不到推送 | 包名不一致、appKey/appSecret 错误 | | 华为推送失败 | Client ID 未配置或错误 | | 无点击回调 | 未在 UIAbility 中调用 notificationClickAck() | | 别名/标签操作失败 | errorCode 非 0，检查 SDK 初始化状态 | | 通知权限未开启 | 引导用户在系统设置中开启 | --- ## 回答边界 - 仅聚焦 HarmonyOS NEXT Stage 模型 + ArkTS 的 MobPush 集成与合规 - 不扩展到 Android、iOS、服务端、非 MobTech SDK - 不伪造真实账号、密钥、签名值


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)