# 鸿蒙应用开发手册

注 1:接入 Open SDK 的开发者,请先认真阅读《微信 Open SDK 个人信息处理规则》《微信 Open SDK 开发者合规使用指南》,并确保对 OpenSDK 的接入使用情况符合上述指南中的相关要求。

注 2:SDK 更新日志可前往《微信 Open SDK for HarmonyOS Next 更新日志》查看。

基本信息

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

# 1、操作步骤

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

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

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

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

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

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

1)Bundle ID 指的是鸿蒙应用的包名,详情可查看 华为文档

2)Identifier 指的是鸿蒙应用的 appIdentifier,详情可查看 华为文档

注意事项

  • 对于 App 已上架 Android 或 iOS 应用市场的应用,在基础信息中,不可选择「未上架任何应用市场」。此选项意思是 Android、iOS 和鸿蒙都尚未上架应用市场,而未上架应用市场的应用使用微信能力则有如下的限制,因此开发者需谨慎操作
  • 对于 App 已上架 Android 或 iOS 应用市场的应用,需选择「已上架至少一个应用市场」,但需填写 App 备案号
  • 即,对于 Android 和 iOS 已上架的应用,在配置对应 Android 应用或 iOS 应用的配置中一定要选择「是」,配置对应的鸿蒙应用时,可以根据实际上架情况选择「是」或「否」

# 1.2 下载鸿蒙开发的 IDE

前往鸿蒙官网下载 DevEco Studio NEXT

# 1.3 配置 SDK 依赖

在 DevEco Studio NEXT 中打开你的项目,以 demo 工程 为示例:

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

{
  "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:用于跳转微信

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

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

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、常见问题

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

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

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

  • 出现该报错请检查 wxopensdk.WXAPIFactory.createWXAPI(APP_ID) 传的 APP_ID 是否传对了移动应用的 AppID(例如,经常有开发者这里的 AppID 传错了另外的移动应用 AppID 或者传了小程序的 AppID 等)
  • 如果确认 APP_ID 没传错,那么则是 identifier 不一致导致的。需要检查在微信开放平台移动应用配置的 Identifier 是否正确(应用启动微信时系统会传一个 appIdentifier 参数)
  • 开发者可以通过下方方式运行并自查
  • 开发者可自查确认是否在用 IDE 的方式自动生成的签名(这个签名和开发者账号有关,有可能生成出来的就会不一样)。如有测试需求,建议申请新的移动应用账号用于生成 debug 签名

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

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

开发者还需要实现 wxopensdk.WXApiEventHandleronReq 函数:

  /**
   * 从微信启动 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 数据