# 鸿蒙应用开发手册

**注 1：接入 Open SDK 的开发者，请先认真阅读[《微信 Open SDK 个人信息处理规则》](https://support.weixin.qq.com/cgi-bin/mmsupportacctnodeweb-bin/pages/RYiYJkLOrQwu0nb8)及[《微信 Open SDK 开发者合规使用指南》](/doc/oplatform/Mobile_App/agreement/sdk)，并确保对 OpenSDK 的接入使用情况符合上述指南中的相关要求。**

**注 2：SDK 更新日志请前往[《微信 Open SDK for HarmonyOS Next 更新日志》](/doc/oplatform/Mobile_App/Downloads/HarmonyOS_Resource)查看。**

**基本信息**

| 项目 | 内容 |
| :--- | :--- |
| SDK 名称 | 微信 Open SDK for HarmonyOS Next |
| SDK 版本号 | 1.0.14 |
| SDK 介绍 | 微信 Open SDK 是一款为开发者开发运营的 APP 提供实现分享与收藏、微信登录和微信支付功能的相关能力的软件开发工具包 |
| 开发者 | 深圳市腾讯计算机系统有限公司 |
| 个人信息处理规则 | [查看](https://support.weixin.qq.com/cgi-bin/mmsupportacctnodeweb-bin/pages/RYiYJkLOrQwu0nb8) |

## 1、操作步骤

### 1.1 申请 AppID 并配置鸿蒙应用信息

1）前往 [微信开放平台](https://open.weixin.qq.com/)，在「管理中心 - 移动应用」创建移动应用账号，并且在「平台信息」板块中填入鸿蒙应用所需的 Bundle ID 和 identifier 信息（如下图），然后提交审核，待审核通过即可获得相应权限。

2）如已有移动应用，则可在「管理中心 - 移动应用 - 详情 - 开发配置」中点击「编辑」进入修改开发信息的页面，继续在「平台信息」板块中填入鸿蒙应用所需的 Bundle ID 和 identifier 信息，然后提交审核，等待审核通过即可。

**操作路径**

- 前往「[微信开放平台](https://open.weixin.qq.com/) - 管理中心 - 移动应用」，即可创建移动应用账号
- 前往「[微信开放平台](https://open.weixin.qq.com/) - 管理中心 - 移动应用 - 详情 - 开发配置 - 编辑」，即可修改开发信息

鸿蒙应用未上架所需填写的信息如下：

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202410081920455.png)

鸿蒙应用已上架所需填写的信息如下：

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202412091717742.png)

**关于「鸿蒙应用」中的 Bundle ID、Identifier 以及应用下载地址的说明**

1）Bundle ID 指的是鸿蒙应用的包名，详情可查看 [华为文档](https://developer.huawei.com/consumer/cn/doc/app/agc-help-createharmonyapp-0000001945392297)

2）Identifier 指的是鸿蒙应用的 `appIdentifier`，详情可查看 [华为文档](https://developer.huawei.com/consumer/cn/doc/harmonyos-references-V5/js-apis-bundlemanager-bundleinfo-V5)

**注意事项**

- 对于 App 已上架 Android 或 iOS 应用市场的应用，在基础信息中，不可选择「未上架任何应用市场」。此选项意思是 Android、iOS 和鸿蒙都尚未上架应用市场，而未上架应用市场的应用使用微信能力则有如下的限制，因此开发者需谨慎操作

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202410171057005.png)

- 对于 App 已上架 Android 或 iOS 应用市场的应用，需选择「已上架至少一个应用市场」，但需填写 App 备案号

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202410152044197.png)

- 即，对于 Android 和 iOS 已上架的应用，在配置对应 Android 应用或 iOS 应用的配置中一定要选择「是」，配置对应的鸿蒙应用时，可以根据实际上架情况选择「是」或「否」

### 1.2 下载鸿蒙开发的 IDE

前往鸿蒙官网下载 [DevEco Studio NEXT](https://developer.huawei.com/consumer/cn/download/)。

### 1.3 配置 SDK 依赖

在 DevEco Studio NEXT 中打开你的项目，以 [demo 工程](https://dldir1.qq.com/WechatWebDev/opensdk/ohos/OpenSDK-1.0.0.zip) 为示例：

修改项目中的 `oh-package.json5` 文件，在 `dependencies` 中加入微信 OpenSDK 的依赖项：

```json
{
  "name": "demo",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
   "dependencies": {
    "@tencent/wechat_open_sdk": "1.0.0"
  }
}
```

### 1.4 配置 queryscheme

在开发者的 App module 的 `module.json5` 里加入下方 scheme 声明：

- `weixin`：用于判断微信是否安装，开发者可通过 `WXApi.isWXAppInstalled()` 判断微信是否已安装
- `wxopensdk`：用于跳转微信

![](https://res.wx.qq.com/op_res/rVGiho7i7dGqXJTB35115dSzISA8Etd7mMwtVhroIe9PW_jUJsDxc7DxTBYehJPXvpTejM6x-I0ssx7kuNTA-A)

### 1.5 在代码中使用开发工具包

以跳转微信获取登录授权为例：

```typescript
import * as wxopensdk from '@tencent/wechat_open_sdk';

// WXApi 是第三方 app 和微信通信的 openApi 接口，其实例通过 WXAPIFactory 获取
// 需要传入应用申请到的 AppID（指的是移动应用 AppID，不要填小程序 AppID）
export const WXApi = wxopensdk.WXAPIFactory.createWXAPI(APP_ID)

// WXApiEventHandler 为微信数据的回调
class WXApiEventHandlerImpl implements wxopensdk.WXApiEventHandler {
  private onReqCallbacks: Map<OnWXReq, OnWXReq> = new Map
  private onRespCallbacks: Map<OnWXResp, OnWXResp> = new Map

  registerOnWXReqCallback(on: OnWXReq) {
    this.onReqCallbacks.set(on, on)
  }
  unregisterOnWXReqCallback(on: OnWXReq) {
    this.onReqCallbacks.delete(on)
  }

  registerOnWXRespCallback(on: OnWXResp) {
    this.onRespCallbacks.set(on, on)
  }
  unregisterOnWXRespCallback(on: OnWXResp) {
    this.onRespCallbacks.delete(on)
  }

  onReq(req: wxopensdk.BaseReq): void {
    Log.i(kTag, "onReq:%s", JSON.stringify(req))
    this.onReqCallbacks.forEach((on) => {
      on(req)
    })
  }

  onResp(resp: wxopensdk.BaseResp): void {
    Log.i(kTag, "onResp:%s", JSON.stringify(resp))
    this.onRespCallbacks.forEach((on) => {
      on(resp)
    })
  }
}
export const WXEventHandler = new WXApiEventHandlerImpl

let req = new wxopensdk.SendAuthReq
req.isOption1 = false
req.nonAutomatic = true
req.scope = 'snsapi_userinfo'
req.state = 'none'
req.transaction = 'test123'

// 向微信发送登录请求:
//   context 为 ohos 内置类，app 间跳转需依赖该类，开发者可在 Component 中获取
//   finished 为跳转微信的结果：true 表示跳转成功；false 表示跳转失败，可能是因为微信未安装
let finished = await this.wxApi.sendReq(context: common.UIAbilityContext, req)

// 在 EntryAbility 中响应来自微信的回调
export default class EntryAbility extends UIAbility {
  onCreate(want: Want, _launchParam: AbilityConstant.LaunchParam): void {
    this.handleWeChatCallIfNeed(want)
  }

  onNewWant(want: Want, _launchParam: AbilityConstant.LaunchParam): void {
    this.handleWeChatCallIfNeed(want)
  }

  private handleWeChatCallIfNeed(want: Want) {
    WXApi.handleWant(want, WXEventHandler)
  }
}
```

至此，你已经能使用微信鸿蒙 Next 开发工具包的 API 内容了。如果想更详细了解每个 API 函数的用法，可自行下载阅读微信 SDK Sample Demo 源码。

## 2、常见问题

- 查看 SDK 版本信息：可前往 [OpenSDK 的仓库](https://ohpm.openharmony.cn/#/cn/detail/@tencent%2Fwechat_open_sdk) 查看
- SDK Sample Demo 下载：点击下载 [OpenSDK-1.0.0.zip](https://dldir1.qq.com/WechatWebDev/opensdk/ohos/OpenSDK-1.0.0.zip)

### 2.1 微信登录失败：由于应用 Bundle ID 信息校验不通过，无法使用微信登录

- 出现该报错原因是你的移动应用配置了鸿蒙的开发信息后，提交审核尚未审核通过（即审核中或者审核驳回），重新提交待审核通过即可
- 如果状态已经是审核通过但仍出现该报错，请检查 `appid` + `identifier` + `bundleId` 是否匹配（可在「微信开放平台 - 管理中心 - 移动应用 - 详情 - 开发配置」查看）

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202410161900499.png)

### 2.2 第三方应用信息校验失败

- 出现该报错请检查 `wxopensdk.WXAPIFactory.createWXAPI(APP_ID)` 传的 `APP_ID` 是否传对了移动应用的 AppID（例如，经常有开发者这里的 AppID 传错了另外的移动应用 AppID 或者传了小程序的 AppID 等）

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2F202505191901830.png)

- 如果确认 `APP_ID` 没传错，那么则是 identifier 不一致导致的。需要检查在微信开放平台移动应用配置的 Identifier 是否正确（应用启动微信时系统会传一个 `appIdentifier` 参数）
- 开发者可以通过下方方式运行并自查
- 开发者可自查确认是否在用 IDE 的方式自动生成的签名（这个签名和开发者账号有关，有可能生成出来的就会不一样）。如有测试需求，建议申请新的移动应用账号用于生成 debug 签名

![](https://testchu-7gy8occc8dcc14c3-1304825656.tcloudbaseapp.com/img%2Fmelody%2Fe1d6bf69e09f09053427830da6379375_compress.png)

### 2.3 微信拉起 App 时，App 如何接收来自微信的数据

开发者需要先配置和微信约定的 action `wxentity.action.open`：

![](https://res.wx.qq.com/op_res/hKFk6oDBu26nl31iXMNq2rXLNsYd2h2dXmPSL17kEj_jMgL9w3JClvwJixJCZt_rNZiA6MHHWP00e6U9TXHSRQ)

开发者还需要实现 `wxopensdk.WXApiEventHandler` 的 `onReq` 函数：

```typescript
  /**
   * 从微信启动 App
   *
   * @param req
   */
  onReq(req: wxopensdk.BaseReq): void {
    if (req instanceof wxopensdk.LaunchFromWXReq) {
      // 获取开放标签传递的 extinfo 数据逻辑
      let messageExt = req.message?.messageExt
      // Handle...
    }
  }
```

也可以参考 [App 获取开放标签 `<wx-open-launch-app>` 中的 extinfo 数据](/doc/service/guide/h5/opentag.md#App%E4%BE%A6%E8%8E%B7%E5%8F%96%E5%BC%80%E6%94%BE%E6%A0%87%E7%AD%BE%E4%BC%A0%E9%80%92%E7%9A%84extinfo%E6%95%B0%E6%8D%AE)。