back
loading skill details...
Interactive guide for integrating MobTech ShareSDK into HarmonyOS NEXT projects. Use when the user wants ShareSDK sharing or Huawei authorization in a Harmon...
---
name: harmonyos-sharesdk-integretion
description: Interactive guide for integrating MobTech ShareSDK into HarmonyOS NEXT projects. Use when the user wants ShareSDK sharing or Huawei authorization in a HarmonyOS app, and needs help with ohpm dependencies, module.json5 permissions, AppKey/AppSecret setup, privacy compliance, or post-integration ShareSDK extension capability guidance.
tags:
- harmonyos
- harmonyos-next
- sharesdk
- mobtech
- sdk-integration
- social-share
- privacy
- arkts
---
# 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
- 新浪微博授权与分享：https://www.mob.com/wiki/detailed?wiki=722&id=14
- 微信授权与分享：https://www.mob.com/wiki/detailed?wiki=724&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 按你的要求采用“先完成基础接入，再在文档中说明后续扩展”的策略：
- 基础集成阶段只主动声明必需权限
- 不在 Excel 模板中提供“权限/可选能力”开关给开发者选择
- 不在基础集成阶段主动插入 `ZztCustomController` 控制逻辑
- 仅在集成完成后的项目说明文档中描述 `ShareSDK 扩展业务功能设置`，供后期调整
基础集成阶段默认只声明以下必需权限：
- `ohos.permission.INTERNET`
除 `INTERNET` 外，其它权限不主动写入 `module.json5`。如果用户后续需要启用扩展业务功能、设备标识、网络信息、位置或 WiFi 相关能力，再根据实际需求补充。
## 文档未明确的事项
以下内容在官方文档中未给出完整写法，执行时必须先检查实际工程和已安装依赖，不可凭空补全：
- `@zztsdk/zztcore` 和 `@zztsdk/sharesdk` 的 ArkTS 导入语句
- `params` 在 `plat.authorize(params)` 中的字段结构
- 是否必须修改 `oh-package.json5`、`build-profile.json5`、`app.json5`
- 项目中推荐放置初始化代码、分享代码、授权代码的具体文件路径
- 微博 `Scope` 的具体业务取值
- 微信小程序分享涉及的 `miniProgramUserName`、`miniProgramPath`、缩略图资源来源
如果用户要求你写这些部分，先扫描工程现状、已安装依赖和类型声明；若仍无法确认，明确告诉用户“官方文档未明确”。
## 6 步交互式集成工作流
所有写文件和改文件操作前，都必须先展示计划修改内容并等待用户确认。
### 步骤 1：启动流程
#### 1-1 询问项目路径
主动询问用户提供 HarmonyOS 项目根路径，例如：
```text
/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 工程，提示：
```text
路径验证失败，未识别到有效的 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`
- 是否启用微博授权/分享
- 如启用微博，则填写：
- 微博 `AppKey`
- `RedirectURI`
- `CallbackAbilityName`
- `Scope`（如项目需要）
- 是否启用微信授权/分享
- 如启用微信，则填写：
- 微信 `AppKey`
- 微信 `AppSecret`
等待用户回复“填好了”后再继续。
#### 2-3 校验规则
读取 `ShareSDK_HarmonyOS_Config.xlsx` 后，至少校验：
- `appKey`：必填，不能为空
- `appSecret`：必填，不能为空
- `bundleName`：必填，不能为空
- `apiVersion`：如填写，必须是整数且应 `>= 12`
- `enableHuaweiAuth`：必须可转换为 `true` / `false`
- `clientId`：当 `enableHuaweiAuth=true` 时必填
- `enableWeibo`：必须可转换为 `true` / `false`
- `weiboAppKey`：当 `enableWeibo=true` 时必填
- `weiboRedirectUrl`：当 `enableWeibo=true` 时必填
- `weiboCallbackAbilityName`：当 `enableWeibo=true` 时必填
- `enableWechat`：必须可转换为 `true` / `false`
- `wechatAppKey`：当 `enableWechat=true` 时必填
- `wechatAppSecret`：当 `enableWechat=true` 时必填
类型转换规则：
- `appKey`、`appSecret`、`clientId`、`bundleName` 一律按字符串处理
- `weiboAppKey`、`weiboRedirectUrl`、`weiboCallbackAbilityName`、`weiboScope`、`wechatAppKey`、`wechatAppSecret` 一律按字符串处理
- 开关字段统一转为 `true` / `false`
- `apiVersion` 统一转为整数
若校验失败：
- 列出全部问题
- 不修改用户项目
- 让用户修正 Excel 后重新回复“填好了”
### 步骤 3：完成依赖与配置修改
确认后再执行以下修改。
#### 3-1 依赖安装
官方文档给出的安装命令是：
```bash
ohpm install @zztsdk/zztcore
ohpm install @zztsdk/sharesdk
```
如果用户希望你代执行，应先说明将运行上述命令；如果项目已有依赖，则以实际工程为准，不重复破坏性修改。
#### 3-2 `module.json5` 修改
必须优先在 `entry` 模块的 `module.json5` 中处理。
官方文档明确要求：
- 增加 `requestPermissions`
- 至少包含 `ohos.permission.INTERNET`
本 skill 的默认策略是：基础集成阶段仅主动声明 `ohos.permission.INTERNET`，不把其它权限预置到 `module.json5` 中。
#### 3-3 华为 `client_id` 配置
仅当用户启用华为授权时，在 `module.json5` 的 `metadata` 中增加：
```json5
{
"name": "client_id",
"value": "用户填写的Client ID"
}
```
如工程已存在 `metadata`，应在原结构中合并，而不是覆盖。
#### 3-4 平台 `querySchemes` 配置
如果启用了对应平台能力，在 `entry` 模块 `module.json5` 的 `module.querySchemes` 中按需增量合并：
- 启用微博：增加 `sinaweibo`
- 启用微信：增加 `weixin`
示例：
```json5
{
"module": {
"querySchemes": [
"sinaweibo",
"weixin"
]
}
}
```
不要覆盖工程中原有的 `querySchemes`。
### 步骤 4：插入初始化与隐私授权代码
#### 4-1 初始化
在使用 SDK 功能前，需先调用：
```ts
ZztSDK.init(context, "您的AppKey", "您的AppSecret")
```
优先把初始化放在应用启动路径或用户功能入口前的稳定位置。
如果工程入口无法快速确认，先扫描以下位置：
- `entry/src/main/ets/entryability/EntryAbility.ets`
- `entry/src/main/ets/app.ets`
- 其他 `UIAbility` / `AppAbility` / 启动页文件
如果仍无法判断，向用户展示候选位置并让其确认。
#### 4-2 说明合规原因
向用户说明：
```text
根据 MobTech 隐私合规要求，使用 ShareSDK 需要在用户同意隐私政策后才能回传授权结果。
你需要在 App 中：
1. 首次启动时展示《隐私政策》弹窗
2. 用户点击“同意”按钮后，调用隐私授权代码
3. 用户点击“不同意”则不应调用
请告知我：用户点击隐私政策“同意”按钮的回调代码在哪个文件、哪个方法中？
例如：EntryAbility.ets 的 onPrivacyAgreed() 方法，或具体位置如 entry/src/main/ets/entryability/EntryAbility.ets:80
```
#### 4-3 询问回调位置
等待用户告知具体的文件路径和方法名。
#### 4-4 隐私授权回传
文档要求：只有在用户同意隐私政策后，才能调用：
```ts
ZztSDK.submitPolicyGrantResult(isGranted)
```
要求：
- 在用户点击隐私弹窗“同意”后调用
- 在用户拒绝前，不得调用
- 基础集成阶段默认不插入 `ZztCustomController` 代码
- 如果后续用户要控制扩展业务功能，再通过项目内说明文档引导其使用 `ZztCustomController` 或 `ZztSDK.updateZztCustomController(...)`
#### 4-5 展示并确认插入代码
展示要插入的代码：
```ts
// 用户同意隐私政策后调用
ZztSDK.submitPolicyGrantResult(true)
```
完整示例：
```ts
onPrivacyAgreed() {
// 用户点击同意按钮
// === ShareSDK 隐私授权 ===
ZztSDK.submitPolicyGrantResult(true)
// ========================
// 其他业务逻辑...
}
```
询问：
```text
以上代码将插入到 {文件} 的 {方法} 中，是否确认？
```
### 步骤 5：插入分享与授权示例
#### 5-1 收集分享与授权落点
主动询问用户：
```text
现在来配置分享和授权功能，请告诉我：
1. 希望在哪个位置执行分享？
- 例如：ArticlePage.ets 的分享按钮点击事件
- 或：SharePage.ets 的 onShareClick() 方法
2. 如需华为授权，希望在哪个位置执行授权？
- 例如：LoginPage.ets 的 onHuaweiLoginClick() 方法
3. 如启用了微博授权或分享，希望在哪个位置执行微博能力？
- 例如：LoginPage.ets 的 onWeiboLoginClick() 方法
- 例如：SharePage.ets 的 onShareToWeibo() 方法
4. 如启用了微信授权或分享，希望在哪个位置执行微信能力？
- 例如：LoginPage.ets 的 onWechatLoginClick() 方法
- 例如：SharePage.ets 的 onShareToWechat() 方法
5. 分享内容是什么？
- 文本内容：
- 标题（如有）：
- 链接 URL（如有）：
- 图片（如有）：
6. 分享方式：
- A. 使用系统分享能力
- B. 使用指定平台能力（微博 / 微信 / 微信朋友圈）
```
#### 5-2 设置 `UIAbilityContext`
在使用分享/授权 UI 前，先设置：
```ts
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 微博平台能力
如果启用了微博授权/分享，必须补充以下平台初始化：
- 在使用前调用 `setPlatformDevInfoAsync(mobShare.Platform.SinaWeibo, map)`
- `map` 至少包含：
- `mobShare.Platform_Info.APP_KEY`
- `mobShare.Platform_Info.REDIRECT_URL`
- `mobShare.Platform_Info.CALLBACK_ABILITY_NAME`
- 如项目需要，可额外传入 `Scope`
示例：
```ts
let map = new HashMap<string, Object>()
map.set(mobShare.Platform_Info.APP_KEY, "weibo_app_key")
map.set(mobShare.Platform_Info.REDIRECT_URL, "weibo_redirect_url")
map.set(mobShare.Platform_Info.CALLBACK_ABILITY_NAME, "EntryAbility")
let isSuccess = await mobShare.ShareSDK.getInstance().setPlatformDevInfoAsync(mobShare.Platform.SinaWeibo, map)
```
微博授权示例：
```ts
let plat = await mobShare.ShareSDK.getInstance().getPlatformAsync(mobShare.Platform.SinaWeibo)
plat.setPlatformActionListener(receive)
plat.authorize()
```
微博取用户信息示例：
```ts
let plat = await mobShare.ShareSDK.getInstance().getPlatformAsync(mobShare.Platform.SinaWeibo)
plat.setPlatformActionListener(receive)
plat.showUser()
```
微博分享示例能力范围：
- 文本分享
- 图片分享
图片分享时，官方文档明确说明目前只能分享沙盒路径图片。
#### 5-6 微信平台能力
如果启用了微信授权/分享，必须补充以下平台初始化：
- 在使用前调用 `setPlatformDevInfoAsync(mobShare.Platform.Wechat, map)`
- `map` 至少包含：
- `mobShare.Platform_Info.APP_KEY`
- `mobShare.Platform_Info.APP_SECRET`
示例：
```ts
let map = new HashMap<string, Object>()
map.set(mobShare.Platform_Info.APP_KEY, "wechat_app_key")
map.set(mobShare.Platform_Info.APP_SECRET, "wechat_app_secret")
let isSuccess = await mobShare.ShareSDK.getInstance().setPlatformDevInfoAsync(mobShare.Platform.Wechat, map)
```
微信授权示例：
```ts
let plat = await mobShare.ShareSDK.getInstance().getPlatformAsync(mobShare.Platform.Wechat)
plat.setPlatformActionListener(receive)
plat.authorize()
```
微信取用户信息示例：
```ts
let plat = await mobShare.ShareSDK.getInstance().getPlatformAsync(mobShare.Platform.Wechat)
plat.setPlatformActionListener(receive)
plat.showUser()
```
微信分享示例能力范围：
- 微信好友：文本、图片、网页、文件、视频、小程序分享、打开小程序
- 微信朋友圈：文本、图片
微信朋友圈分享时，按官方示例在分享参数中设置 `scene: 1`。
#### 5-7 第三方回调处理
如果启用了微博或微信授权/分享，需要在回呼 Ability 的 `onCreate` 和 `onNewWant` 中调用：
```ts
mobShare.ShareSDK.getInstance().handlerWant(want, this.context)
```
插入前必须先确认用户指定的回呼 Ability 文件与方法位置。
#### 5-8 展示并确认插入代码
在生成分享或授权代码后，必须先向用户展示将插入的代码和目标位置，再询问：
```text
以上是生成的 ShareSDK 代码，将插入到 {文件} 的 {方法} 中，是否确认？
```
### 步骤 6：补充项目内说明文档
完成集成后，在用户项目中生成一份 `SHARESDK_HARMONYOS_README.md`，至少包含：
- 已安装依赖
- 修改过的 `module.json5` 配置
- `appKey` / `appSecret` 来源
- 是否启用华为授权及 `client_id` 来源
- 隐私弹窗回调位置
- 基础集成阶段默认添加的权限清单（仅 `ohos.permission.INTERNET`）
- 已配置的平台能力：
- 华为授权
- 新浪微博授权/分享（如启用）
- 微信授权/分享（如启用）
- 分享与授权能力入口位置
- `querySchemes` 配置结果
- 第三方平台 `setPlatformDevInfoAsync(...)` 配置结果
- 回呼 Ability 中 `handlerWant(...)` 插入位置
- 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 信息
- 运营商信息
- 社交平台信息
- 厂商 / 设备 / 系统 / 屏幕信息
基础集成默认先完成最小必需权限接入；扩展能力、附加权限和数据采集控制放到后续调整阶段处理。
don't have the plugin yet? install it then click "run inline in claude" again.