HarmonyOS ShareSDK 集成 Skill

适用场景

当用户提到以下任一主题时，使用本 skill：

• HarmonyOS ShareSDK 集成
• 鸿蒙接入 ShareSDK
• HarmonyOS 分享能力接入
• ShareSDK HarmonyOS NEXT
• 华为授权接入
• MobTech ShareSDK 鸿蒙集成
• ShareSDK 隐私合规
• ShareSDK 扩展业务功能后续调整

如果用户的问题明确涉及 HarmonyOS NEXT 工程、ohpm 依赖、module.json5 权限、MobTech AppKey / AppSecret、ZztSDK.submitPolicyGrantResult() 或分享/授权功能接入，应优先使用本 skill。

官方文档来源

• 集成指南：https://www.mob.com/wiki/detailed?wiki=696&id=14
• 扩展业务功能设置：https://www.mob.com/wiki/detailed?wiki=711&id=14
• 鸿蒙端合规使用说明：https://www.mob.com/wiki/detailed?wiki=748&id=14

已确认的官方信息

• 开发工具：DevEco Studio
• 集成方式：在线集成
• HarmonyOS API 支持：>= 12
• 依赖安装方式：
  • ohpm install @zztsdk/zztcore
  • ohpm install @zztsdk/sharesdk
• 文档明确要求在 entry 模块的 module.json5 中配置 ohos.permission.INTERNET
• 文档明确支持：
  • 分享能力
  • 华为授权
  • ZztSDK.submitPolicyGrantResult(...) 隐私授权回传
  • ZztCustomController 主动数据采集控制
  • setUIAbilityContext(...) 以支持分享/授权 UI 能力
  • 扩展业务功能后续控制能力

基础集成默认策略

本 skill 按你的要求采用“先保证可用，再在文档中说明后续收敛”的策略：

• 基础集成阶段默认放开 ShareSDK 常用权限和可选能力
• 不在 Excel 模板中提供“权限/可选能力”开关给开发者选择
• 不在基础集成阶段主动插入 ZztCustomController 控制逻辑
• 仅在集成完成后的项目说明文档中描述 ShareSDK 扩展业务功能设置，供后期调整

基础集成阶段默认合并以下权限：

• ohos.permission.INTERNET
• ohos.permission.GET_NETWORK_INFO
• ohos.permission.APP_TRACKING_CONSENT
• ohos.permission.APPROXIMATELY_LOCATION
• ohos.permission.GET_WIFI_INFO

如果工程已有更严格的权限治理，或用户明确要求最小权限集，再停下来与用户确认，不要擅自缩减。

文档未明确的事项

以下内容在官方文档中未给出完整写法，执行时必须先检查实际工程和已安装依赖，不可凭空补全：

• @zztsdk/zztcore 和 @zztsdk/sharesdk 的 ArkTS 导入语句
• params 在 plat.authorize(params) 中的字段结构
• 是否必须修改 oh-package.json5、build-profile.json5、app.json5
• 项目中推荐放置初始化代码、分享代码、授权代码的具体文件路径

如果用户要求你写这些部分，先扫描工程现状、已安装依赖和类型声明；若仍无法确认，明确告诉用户“官方文档未明确”。

6 步交互式集成工作流

所有写文件和改文件操作前，都必须先展示计划修改内容并等待用户确认。

步骤 1：启动流程

1-1 询问项目路径

主动询问用户提供 HarmonyOS 项目根路径，例如：

/Users/xxx/your-harmony-project

1-2 验证项目结构

至少检查以下文件中的一种或多种是否存在：

• build-profile.json5
• oh-package.json5
• entry/src/main/module.json5
• 其他模块下的 src/main/module.json5

优先识别 entry 模块的 module.json5。

如果路径不合法或不像 HarmonyOS 工程，提示：

路径验证失败，未识别到有效的 HarmonyOS 工程结构。

请确认项目根目录下至少存在以下文件之一：
- build-profile.json5
- oh-package.json5
- entry/src/main/module.json5

步骤 2：生成并填写配置模板

2-1 生成 Excel 模板

执行：

1. 运行 assets/generate_excel_template.py
2. 生成 assets/ShareSDK_HarmonyOS_Config_Template.xlsx
3. 复制到用户项目根目录并命名为 ShareSDK_HarmonyOS_Config.xlsx

2-2 告知用户填写内容

明确要求用户填写：

• MobTech appKey
• MobTech appSecret
• HarmonyOS 包名（或应用标识）
• 是否启用华为授权
• 如启用华为授权，则填写 client_id

等待用户回复“填好了”后再继续。

2-3 校验规则

读取 ShareSDK_HarmonyOS_Config.xlsx 后，至少校验：

• appKey：必填，不能为空
• appSecret：必填，不能为空
• bundleName：必填，不能为空
• apiVersion：如填写，必须是整数且应 >= 12
• enableHuaweiAuth：必须可转换为 true / false
• clientId：当 enableHuaweiAuth=true 时必填

类型转换规则：

• appKey、appSecret、clientId、bundleName 一律按字符串处理
• 开关字段统一转为 true / false
• apiVersion 统一转为整数

若校验失败：

• 列出全部问题
• 不修改用户项目
• 让用户修正 Excel 后重新回复“填好了”

步骤 3：完成依赖与配置修改

确认后再执行以下修改。

3-1 依赖安装

官方文档给出的安装命令是：

ohpm install @zztsdk/zztcore
ohpm install @zztsdk/sharesdk

如果用户希望你代执行，应先说明将运行上述命令；如果项目已有依赖，则以实际工程为准，不重复破坏性修改。

3-2 module.json5 修改

必须优先在 entry 模块的 module.json5 中处理。

官方文档明确要求：

• 增加 requestPermissions
• 至少包含 ohos.permission.INTERNET

本 skill 的默认策略是：基础集成阶段直接合并以下权限，不把权限选择交给开发者在 Excel 中决定：

• ohos.permission.GET_NETWORK_INFO
• ohos.permission.APP_TRACKING_CONSENT
• ohos.permission.APPROXIMATELY_LOCATION
• ohos.permission.GET_WIFI_INFO

3-3 华为 client_id 配置

仅当用户启用华为授权时，在 module.json5 的 metadata 中增加：

{
  "name": "client_id",
  "value": "用户填写的Client ID"
}

如工程已存在 metadata，应在原结构中合并，而不是覆盖。

步骤 4：插入初始化与隐私授权代码

4-1 初始化

在使用 SDK 功能前，需先调用：

ZztSDK.init(context, "您的AppKey", "您的AppSecret")

优先把初始化放在应用启动路径或用户功能入口前的稳定位置。

如果工程入口无法快速确认，先扫描以下位置：

• entry/src/main/ets/entryability/EntryAbility.ets
• entry/src/main/ets/app.ets
• 其他 UIAbility / AppAbility / 启动页文件

如果仍无法判断，向用户展示候选位置并让其确认。

4-2 说明合规原因

向用户说明：

根据 MobTech 隐私合规要求，使用 ShareSDK 需要在用户同意隐私政策后才能回传授权结果。

你需要在 App 中：
1. 首次启动时展示《隐私政策》弹窗
2. 用户点击“同意”按钮后，调用隐私授权代码
3. 用户点击“不同意”则不应调用

请告知我：用户点击隐私政策“同意”按钮的回调代码在哪个文件、哪个方法中？
例如：EntryAbility.ets 的 onPrivacyAgreed() 方法，或具体位置如 entry/src/main/ets/entryability/EntryAbility.ets:80

4-3 询问回调位置

等待用户告知具体的文件路径和方法名。

4-4 隐私授权回传

文档要求：只有在用户同意隐私政策后，才能调用：

ZztSDK.submitPolicyGrantResult(isGranted)

要求：

• 在用户点击隐私弹窗“同意”后调用
• 在用户拒绝前，不得调用
• 基础集成阶段默认不插入 ZztCustomController 代码
• 如果后续用户要控制扩展业务功能，再通过项目内说明文档引导其使用 ZztCustomController 或 ZztSDK.updateZztCustomController(...)

4-5 展示并确认插入代码

展示要插入的代码：

// 用户同意隐私政策后调用
ZztSDK.submitPolicyGrantResult(true)

完整示例：

onPrivacyAgreed() {
  // 用户点击同意按钮

  // === ShareSDK 隐私授权 ===
  ZztSDK.submitPolicyGrantResult(true)
  // ========================

  // 其他业务逻辑...
}

询问：

以上代码将插入到 {文件} 的 {方法} 中，是否确认？

步骤 5：插入分享与授权示例

5-1 收集分享与授权落点

主动询问用户：

现在来配置分享和授权功能，请告诉我：

1. 希望在哪个位置执行分享？
   - 例如：ArticlePage.ets 的分享按钮点击事件
   - 或：SharePage.ets 的 onShareClick() 方法

2. 如需华为授权，希望在哪个位置执行授权？
   - 例如：LoginPage.ets 的 onHuaweiLoginClick() 方法

3. 分享内容是什么？
   - 文本内容：
   - 标题（如有）：
   - 链接 URL（如有）：
   - 图片（如有）：

4. 分享方式：
   - A. 使用系统分享能力
   - B. 使用指定平台能力（如实际工程和文档已确认）

5-2 设置 UIAbilityContext

在使用分享/授权 UI 前，先设置：

await mobShare.ShareSDK.getInstance().setUIAbilityContext(getContext() as common.UIAbilityContext)

5-3 分享示例

可按官方示例插入基础分享流程：

• 构造 mobShare.SharedParam[]
• 获取平台实例 mobShare.Platform.SYSTEM
• 设置 PlatformActionListener
• 调用 share(...)

5-4 华为授权示例

可按官方示例插入：

• getPlatformAsync(mobShare.Platform.HUAWEI)
• setPlatformActionListener(...)
• authorize(params)
• showUser()
• isAuthValid()
• removeAccount()

注意：authorize(params) 的 params 字段结构官方文档未明确，不能自行编造。若需要落业务代码，先在本地依赖类型或官方 API 文档中确认。

5-5 展示并确认插入代码

在生成分享或授权代码后，必须先向用户展示将插入的代码和目标位置，再询问：

以上是生成的 ShareSDK 代码，将插入到 {文件} 的 {方法} 中，是否确认？

步骤 6：补充项目内说明文档

完成集成后，在用户项目中生成一份 SHARESDK_HARMONYOS_README.md，至少包含：

• 已安装依赖
• 修改过的 module.json5 配置
• appKey / appSecret 来源
• 是否启用华为授权及 client_id 来源
• 隐私弹窗回调位置
• 基础集成阶段默认添加的权限清单
• 分享与授权能力入口位置
• ShareSDK 扩展业务功能设置说明：
  • ZztCustomController 的用途
  • 哪些能力可在后期关闭或改为 App 回传
  • ZztSDK.submitPolicyGrantResult(true, controller) 的使用场景
  • ZztSDK.updateZztCustomController(...) 的补充用法
• 仍待确认的文档未明确项

代码修改规则

• 所有修改前必须先展示 diff 计划或代码片段并等待确认
• 不要覆盖用户已有 requestPermissions、metadata、初始化逻辑或隐私弹窗逻辑
• 对已有权限和 metadata 做增量合并
• 若工程已存在 MobTech 相关依赖或旧版 ShareSDK 代码，先停下来说明冲突点，再让用户决定是否替换
• 若发现导入语句、类型声明或 API 名称与官方页面示例不一致，以本地实际依赖导出为准，并向用户说明
• 不要在基础集成阶段主动插入 ZztCustomController 控制逻辑，除非用户明确要求

隐私与合规要求

• 用户首次冷启动并同意隐私政策后，才可回传授权结果
• 未同意前，不得调用 ShareSDK 业务能力
• App 应向终端用户披露 ShareSDK：
  • SDK 名称：ShareSDK
  • 第三方主体：上海掌之淘信息技术有限公司
  • 使用目的：提供社会化登录和分享服务
  • 隐私政策链接：https://policy.zztfly.com/sdk/share/privacy
• 如果后续启用了扩展业务功能控制，应为用户提供退出能力

后续调整说明

如果用户在集成完成后要求严格控制可选信息采集，再建议实现 ZztCustomController，并根据官方文档控制以下能力：

• 地理位置信息
• OAID
• WiFi 信息
• 本地 IP 信息
• 运营商信息
• 社交平台信息
• 厂商 / 设备 / 系统 / 屏幕信息

基础集成默认先保证官方推荐能力可用；能力收敛与数据采集控制放到后续调整阶段处理。