微信内网页拉端适配指导文档

lewis_dys
3,005 阅读6分钟

开发流程

flowchart LR

    A(开始) --> B[申请AppID并配置鸿蒙应用信息]
    B-->C[绑定域名和移动应用]
    C-->D1[适配微信的UA标识]
    D1-->E1[接入微信开放标签]
    E1-->Z(结束)
    C-->D2[接入微信OpenSDK]
    D2-->E2[配置微信跳转aciton]
    E2-->E3[获取Web页面跳转的参数信息]
    E3-->Z

准备工作

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

参考申请你的 AppID 并配置鸿蒙应用信息以及提交审核进行配置。

绑定域名和移动应用

开发者可参考微信内网页跳转App功能，配置域名与所需跳转的移动应用，设置入口：微信开放平台-管理中心。

Web页面适配

适配微信的UA标识

微信UA标识示例如下：

Mozilla/5.0 (Phone; OpenHarmony 5.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36 ArkWeb/4.1.6.1 Mobile MicroMessenger/1.0.3.52(0xf3100334) Weixin NetType/4G Language/zh_CN MMWEBID/2965 MMWEBSDK/202412070032 XWEB/1140157

建议UA识别OpenHarmony+MicroMessenger，参考代码如下

const isHarmonyOS = (ua) => /OpenHarmony/i.test(ua);
const isMicroMessenger = (ua) => /MicroMessenger/.test(ua);

const ua = navigator.userAgent;

const result = isHarmonyOS(ua) && isMicroMessenger(ua); // 判别为HarmonyOS设备的微信拉端

接入微信开放标签

微信开放标签：微信公众平台面向网页开发者提供的扩展标签集合。通过使用微信开放标签，网页开发者可安全便捷地使用微信或系统的能力。

条件

  • 鸿蒙系统上的微信版本要求为：1.0.3.53 及以上。
  • JS接口文件：1.6.0以上 （例如：http://res.wx.qq.com/open/js/jweixin-1.6.0.js）。

有关JS接口文件与JS-SDK参考：developers.weixin.qq.com/doc/offiacc…

步骤

来源：开放标签说明文档-使用步骤。

绑定域名

登录微信公众平台进入“公众号设置”的“功能设置”里填写“JS接口安全域名”。

引入JS文件

在需要调用JS接口的页面引入如下JS文件：http://res.wx.qq.com/open/js/jweixin-1.6.0.js（支持https）

如需进一步提升服务稳定性，当上述资源不可访问时，可改访问：http://res2.wx.qq.com/open/js/jweixin-1.6.0.js （支持https）

备注：支持使用 AMD/CMD 标准模块加载方法加载

申请微信开放标签
wx.config({
  debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印
  appId: '', // 必填，公众号的唯一标识
  timestamp: , // 必填，生成签名的时间戳
  nonceStr: '', // 必填，生成签名的随机串
  signature: '',// 必填，签名
  jsApiList: [], // 必填，需要使用的JS接口列表
  openTagList: ['wx-open-launch-app'] // 可选，需要使用的开放标签列表，例如['wx-open-launch-app']
});
通过ready接口处理成功验证

config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异步操作，

  • 如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。

  • 对于用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中

wx.ready(function () {

});
通过error接口处理失败验证

config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。

wx.error(function (res) {
    
});
使用跳转app标签

原文参考：跳转App：wx-open-launch-app。可点击原文查看具体属性事件。

功能：用于在Web页面中提供一个可跳转指定App的按钮。

注意：

  • App必须接入微信OpenSDK，可参考HarmonyOS应用接入微信OpenSDK接入，也可参考下文目标应用本地配置。
  • appid为所需跳转的移动应用的AppID
  • 必须真机才能渲染该标签。
  • 文字链无法拉起该标签。
<wx-open-launch-app
  id="launch-btn"
  appid="your-appid"
  extinfo="your-extinfo"
>
  <script type="text/wxtag-template">
    <style>.btn { padding: 12px }</style>
    <button class="btn">App内查看</button>
  </script>
</wx-open-launch-app>
<script>
  var btn = document.getElementById('launch-btn');
  btn.addEventListener('launch', function (e) {
    console.log('success');
  });
  btn.addEventListener('error', function (e) {
    console.log('fail', e.detail);
  });
</script>

目标应用适配

参考来源：developers.weixin.qq.com/doc/oplatfo…

接入微信OpenSDK

修改应用中的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.7"
  }
}

注意：依赖的OpenSDK需不小于1.0.7，完成后点击Sync Now即可。

配置微信跳转action

在module.json5配置wxentity.action.open，建议拆出一个单独的配置项，参考代码如下：

"skills": [
  {
    "entities": [
      "entity.system.home"
    ],
    "actions": [
      "action.system.home"
    ]
  },
  // ...
  {
    "actions": [
      "wxentity.action.open"
    ],
    // ...
  }
]

获取Web页面跳转的参数信息

拉起目标应用之后，可以通过获取传递的参数信息，进而执行后续的业务逻辑（例如跳转详情页）。以下只以获取参数为例。

import * as wxopensdk from '@tencent/wechat_open_sdk'
import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit'

const APP_ID = ""

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

// WXApiEventHandler为微信数据的回调
class WXApiEventHandlerImpl implements wxopensdk.WXApiEventHandler {
  onReq(req: wxopensdk.BaseReq): void {
    if (req instanceof wxopensdk.LaunchFromWXReq) {
      // //获取开放标签传递的extinfo数据逻辑
      let messageExt = req.message?.messageExt
      //Handle...
    }
  }

  onResp(resp: wxopensdk.BaseResp): void {

  }
}

export const WXEventHandler = new WXApiEventHandlerImpl


// 在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)
  }
}

更多信息可参考：developers.weixin.qq.com/doc/oplatfo…

应用未安装情况下适配

该场景下，用户点击微信开放标签后，微信开放标签的error回调中返回"launch:fail"错误信息，可以在该回调中判断鸿蒙系统UA，并跳转鸿蒙应用市场下载页引导用户安装应用。

c4a31964abce13186328a2c0b26455e0_screenshot_20250401_101519.jpg

鸿蒙微信UA标识判断方式参考：适配微信的UA标识

参考代码如下：

const result = isHarmonyOS(ua) && isMicroMessenger(ua); // 判别为HarmonyOS设备的微信拉端

if(result) {
  // 跳转到应用市场
  location.href = 'https://appgallery.huawei.com/app/detail?id=xxx'; //id后的xxx需要替换为应用的BundleName
} else {
  // 处理其他端引导下载逻辑
}

常见问题

Q1：应用未安装、旧版本未适配微信拉起App等场景，使用微信开放标签无法拉起App，此时该如何处理？

A1：该场景下，用户点击微信开放标签后，微信开放标签的error回调中返回"launch:fail"错误信息，应用可以在获取到该信息时，引导用户通过应用市场获取应用最新版本。

Q2：应用已安装，点击微信开放标签后，提示“暂无可用打开方式”

A2：

1）检查module.json5中，确认已配置微信跳转action（wxentity.action.open）；
2）请单独配置一个skill对象，仅包含微信跳转action，避免与其他业务冲突，无法匹配。
详情查看：配置微信跳转action章节

avatar
文章
阅读
粉丝