Harmonyos Moblink Integration — Harmonyos Moblink 集成

HarmonyOS MobLink 集成 Skill 适用场景 当用户提到以下任一主题时，使用本 skill： harmonyos moblink MobLink 集成（鸿蒙 / HarmonyOS / 鸿蒙 NEXT） 鸿蒙深度链接 / Deeplink MobTech MobLink 鸿蒙接入 场景还原 MobLink 的 ohpm 配置 HarmonyOS URI scheme / host 配置 ZztSDK.init / ZztSDK.submitPolicyGrantResult getMobID / setRestoreSceneListener / Scene MobLink 隐私合规 ZztCustomController 扩展业务功能控制 我要在鸿蒙 app 中增加深度链接能力 我要在 HarmonyOS 项目中接入 MobLink 帮我配置鸿蒙场景还原 一键集成 MobLink 自动配置 MobLink 如果用户问题明确与 HarmonyOS 的 MobLink 接入、工程配置、场景还原、隐私合规有关，应优先使用本 skill。

官方文档依据 使用以下官方文档作为事实来源： 文档入口：https://www.mob.com/wiki/detailed?wiki=661&id=34 HarmonyOS NEXT 集成指南：https://mob.com/wiki/detailed?wiki=731&id=34 MobLink 后台基本配置：https://mob.com/wiki/detailed?wiki=527&id=34 MobLink 鸿蒙端合规使用说明：https://mob.com/wiki/detailed?wiki=758&id=34 常见问题：https://mob.com/wiki/detailed?wiki=530&id=34 MobLink 隐私政策：https://mob.com/wiki/detailed?wiki=97&id=34 扩展业务功能设置：https://www.mob.com/wiki/detailed?wiki=730&id=34

关键事实： 官方 HarmonyOS 集成方式：ohpm 在线安装 @zztsdk/zztcore 和 @zztsdk/moblink。 最低 API version：12（首批接口从 OpenHarmony SDK API version 12 开始支持）。 ohpm 安装命令：ohpm install @zztsdk/zztcore 和 ohpm install @zztsdk/moblink。 导入方式：import { ZztSDK } from '@zztsdk/zztcore'; 和 import mobLink from '@zztsdk/moblink';。 ZztSDK 初始化：ZztSDK.init(context, "您的 AppKey", "您的 AppSecret")。 隐私提交：ZztSDK.submitPolicyGrantResult(granted) 或 ZztSDK.submitPolicyGrantResult(true, new MyCustomController())。 MobLink 初始化：mobLink.init(context)，需在 ZztSDK 初始化和隐私提交之后调用。 场景还原监听器：建议在 AbilityStage 中设置 mobLink.setRestoreSceneListener(receiver)。 onNewWant 处理：在 Ability 的 onNewWant 中调用 mobLink.updateNewWant(want)。 鸿蒙端需配置 module.json5 中的 skills 标签以支持 URI scheme 唤醒。

6 步交互式集成工作流 每步操作前都需要展示内容给用户确认，获得明确同意后再执行。

步骤 1：启动流程 1-1 询问项目路径 我来帮你集成 MobLink 场景还原功能。 请提供需要集成的 HarmonyOS 项目根路径，例如：/path/to/your-harmonyos-project 请确保项目包含 build-profile.json5、oh-package.json5 和 module.json5 文件。 1-2 验证路径合法性 验证逻辑： 检查路径是否存在。 检查路径下是否有 build-profile.json5 或 app.json5。 检查是否存在 oh-package.json5。 检查是否存在 module.json5（或 entry/src/main/module.json5）。 如果路径不合法： 路径验证失败，可能原因：

• 路径不存在：{path}
• 未找到 build-profile.json5 / app.json5
• 未找到 oh-package.json5
• 未找到 module.json5

请重新提供正确的 HarmonyOS 项目根路径。 如果路径合法：进入步骤 2。

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

• 在"基础信息"Sheet 中填写 MobTech 的 appKey、appSecret 和鸿蒙包名
• 在"MobLink 配置"Sheet 中填写 uriScheme、host 和默认场景路径
• 在"隐私合规"Sheet 中确认隐私政策、授权回调和扩展采集控制配置
• "填写说明"Sheet 中有官方文档链接和字段说明

填写完成后告诉我"填好了"，我将继续下一步。 2-2 等待用户填写完成 等待用户回复"填好了""已填写"或类似表达。 2-3 读取并验证配置 操作：读取 {path}/MobLink_Config.xlsx。 验证规则： 检查项 规则 不通过时的提示 appKey 必填，不能为空字符串 "基础信息 Sheet 中的 appKey 未填写，请从 MobTech 官网获取" appSecret 必填，不能为空字符串 "基础信息 Sheet 中的 appSecret 未填写" bundleName 必填，建议符合 com.xxx.xxx 格式 "鸿蒙包名格式不正确，应类似 com.example.app" uriScheme 建议填写，来自 MobLink 后台配置 "MobLink uriScheme 未填写，可能影响 scheme 唤醒" host 建议填写，来自 MobLink 后台配置 "MobLink host 未填写，可能影响 AppLink 唤醒" defaultScenePath 如填写，建议以 / 开头 "场景路径建议以 / 开头，例如 /demo/a" privacyPolicyReady 转为布尔值 "隐私合规配置请填写 是/否 或 true/false" 隐私合规布尔项 转为布尔值 "隐私合规配置请填写 是/否 或 true/false" 类型转换规则： appKey、appSecret、bundleName、uriScheme、host、defaultScenePath、restoreAbility 等标识符字段强制转为字符串。 privacyPolicyReady、useZztCustomController、allowLocationData、allowDeviceIdData、allowAppListData、allowNetworkData 转为 true / false。 如果不合法： 配置信息验证失败，请修正以下问题：{具体问题列表} 请修改 Excel 文件后保存，然后重新告诉我"填好了"。 如果合法：提取配置信息，进入步骤 3。

步骤 3：完成 SDK 集成 3-1 ohpm 安装依赖 操作：在项目根目录执行以下命令： ohpm install @zztsdk/zztcore ohpm install @zztsdk/moblink 验证 oh-package.json5 中是否已添加依赖： "dependencies": { "@zztsdk/zztcore": "^x.x.x", "@zztsdk/moblink": "^x.x.x" } 注意：需要访问 https://ohpm.openharmony.cn/ohpm 获取最新依赖包的版本。 3-2 权限配置 在 module.json5 中添加权限： 必需权限： "reqPermissions": [ { "name": "ohos.permission.INTERNET" } ] 建议权限： { "name": "ohos.permission.APP_TRACKING_CONSENT" }, { "name": "ohos.permission.GET_NETWORK_INFO" } 注意：APP_TRACKING_CONSENT 是 user_grant 权限，需要补 reason 和 usedScene。 示例： { "name": "ohos.permission.APP_TRACKING_CONSENT", "reason": "用于为您提供个性化的内容推荐服务", "usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } } 3-3 URI scheme 配置 在 module.json5 的对应 Ability 的 skills 中添加 skill 对象： "skills": [ { "entities": ["entity.system.home"], "actions": ["action.system.home"] }, { "actions": ["your.custom.action"], "uris": [ { "scheme": "{uriScheme}", "host": "{host}" } ] } ] 如果存在多个跳转场景，需配置多个 skill 对象。actions 不能为空，否则会造成目标方匹配失败。

步骤 4：插入隐私授权回调 4-1 说明合规原因 根据 MobTech 合规要求，MobLink 需要在用户同意隐私政策后才能提交授权结果并使用 SDK 功能。 ZztSDK.init() 内部会做隐私授权状态的判断，在应用向 ZztSDK 提交隐私授权同意状态之前不会做任何业务的初始化。 请告知用户点击隐私政策"同意"按钮的回调代码在哪个文件、哪个方法中？ 例如：EntryAbility.ts 的 onPrivacyAgreed() 方法，或具体位置如 entry/src/main/ets/ability/EntryAbility.ts:80 4-2 展示并确认插入代码 普通