移动端H5唤起APP实现方案

引言

​ 在移动端的开发中，用户体验是非常关键的一个环节。为了增强用户的便捷性，很多应用希望通过在H5页面上点击链接或按钮，直接将用户引导至APP特定页面，以实现无缝跳转。这种唤起APP的功能不仅简化了用户操作路径，也提升了业务转化率，例如通过营销页面直接跳转到购物APP的促销页面，或者从文章页引导至社交APP的讨论区。

​ 不同浏览器和平台对H5唤起APP的支持情况各异，尤其在微信内嵌浏览器中，出于安全和隐私保护的考虑，对直接唤起外部APP存在一定限制。因此，开发者通常根据需求选择适合的方案。比如，URL Scheme由于配置简单，常用于适配大部分浏览器环境下的跳转需求；而wx-open-launch-app标签则专为适配微信浏览器设计，可以确保H5页面在微信APP内也能成功唤起指定的APP。通过组合使用这些方法，开发者能够更灵活地实现跨浏览器和内嵌环境中的跳转。

URL Scheme

原理

​ URL Scheme是一种通过自定义协议实现的URL跳转方式，允许H5页面通过特定的链接直接打开指定的APP。其原理类似于网页中的HTTP或HTTPS链接，但采用了应用自定义的协议名称（例如myapp://）来识别和跳转。只要用户的设备上安装了支持该协议的APP，点击该链接时便会自动唤起该APP，并跳转到特定页面或执行某个功能。

​ 在H5页面中实现APP唤起，可以通过JavaScript中的window.location.href来跳转并触发URL Scheme。window.location.href可以动态设置页面地址，实现对自定义协议的跳转，从而打开对应的APP。当用户点击该链接时，浏览器会尝试通过URL Scheme协议查找并打开目标APP。

  • App 在安装时会向操作系统注册一个自定义 URL Scheme。例如上面的安装的应用就与myapp://相关联起来。

  • 当用户在浏览器中点击一个 URL Scheme（ 例如myapp://open?param=value），浏览器会将请求的 URL 发送给操作系统。

  • 操作系统接收到该请求后，会查看 URI 映射表，检查是否有应用程序已注册该 URL Scheme。

  • 如果系统发现有应用注册了该 Scheme，便会将控制权转交给对应的 App，同时将 URL 中的参数传递给它。

​

实现方案

安卓配置URL Scheme

在安卓应用中配置URL Scheme，需要在应用的AndroidManifest.xml文件中为对应的Activity添加意图过滤器（Intent Filter），这样Android系统可以识别并响应特定的URL Scheme请求。以下是配置步骤：

在目标<activity>中添加以下<intent-filter>配置，定义自定义的Scheme：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
<activity android:name=".YourActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
      
        <!--定义了一个分类，表示该Activity可以被浏览器或其他外部应用调用-->
        <category android:name="android.intent.category.BROWSABLE" />

        <data
            android:scheme="myapp"    <!-- 自定义Scheme名称 -->
            android:host="page"       <!-- 可选：定义Host部分 -->
            android:pathPrefix="/open" /> <!-- 可选：路径前缀 -->
    </intent-filter>
</activity>

android:pathPrefix="/open"：可选参数，用于匹配URL路径前缀。如果URL为myapp://page/open，则符合条件，可以打开该Activity。

​ 在URL Scheme中，host和path的使用可以帮助开发者更精确地控制请求的处理。host用于区分不同的功能模块，使得URL更具可读性和灵活性，例如myapp://login和myapp://profile可以分别指向不同的页面。path则用于细化请求，支持不同功能的实现，如myapp://page/open可以打开页面，而myapp://page/edit则用于编辑内容。**这种结构化的设计提升了应用的组织性、可扩展性和用户体验。

在H5页面中按钮点击跳转。

<button @click="openApp">打开APP</button> 

1
2
3
4
5
function openApp() {
    const urlScheme = 'myapp://page?param=value';
    // 使用 window.location.href 跳转
    window.location.href = urlScheme;
}

这里可以跳转到其他APP测试一下。以微信举例，微信的url scheme是weixin://

image-20250107145437373

异常情况

​ 如果用户的设备上没有安装目标应用或者某些浏览器（如微信内置浏览器）可能会阻止跳转，点击URL Scheme可能没有任何反应。

​ 由于没有错误提示，需要自己做出异常判断。解决方案一般采用定时重定向的方式。在跳转后设置一个延时重定向，例如3秒后未成功打开APP的话跳转到应用商店的下载页面，提示用户安装应用。

​ 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
openApp() {
     window.location = "weixin://";
     //超时未打开app,则跳转到应用商店
     let timeoutId = setTimeout(function () {
       window.location = 'https://sj.qq.com/appdetail/com.tencent.mm'
     }, 2000)

     document.addEventListener('visibilitychange', function () {
       if (document.visibilityState === 'hidden') {
         // 当页面变为不可见时（说明可能已经跳转到微信）
         // 清除定时器，防止跳转到应用商店
         clearTimeout(timeoutId);
       }
     });
   }

​

wx-open-launch-app

原理

wx-open-launch-app 是微信网页开发中提供的一个特殊组件，用于在微信内唤起外部应用。它允许开发者通过微信跳转到已安装的第三方应用。

工作流程：

  • 预先配置 appid：在微信开发者后台，公众号需要先配置目标应用的 appid 以及相关信息（如包名、签名等）。这样，微信可以验证调用的合法性，确保只会跳转到授权的应用，避免恶意跳转。
  • 唤起外部应用：用户点击 wx-open-launch-app 按钮后，微信会使用 appid 调用系统接口唤起相应的 App。如果目标 App 已安装，系统将直接打开该应用；如果未安装，用户可能会被提示下载。

配置要求：

  1. 关联跳转的 App： 首先，在微信开放平台的管理中心中，进入 公众号设置 - 接口信息 - 网页跳转移动应用 - 关联设置，绑定目标应用。具体配置规则可以参考 《微信内网页跳转 APP 功能》。该功能仅限 已认证的服务号 使用，个人主体的 订阅号 无法使用。

  2. 配置 JS 接口安全域名： 登录微信公众平台，进入“公众号设置” -> “功能设置”，填写 JS 接口安全域名。该配置确保 H5 页面可以在微信环境中安全调用特定的 JavaScript API，以防未经授权的页面滥用这些功能。

  3. 引入 JS 文件： 在需要调用微信 JS-SDK 接口的页面引入 JS 文件：

    1
    <script type="text/javascript" src="http://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>

    这允许开发者在 H5 页面中使用微信 JS-SDK 的各类 API。

  4. 配置 JS-SDK： 在安全域名下配置 JS-SDK 需要用到 JS-SDK 签名信息，以确保接口调用的合法性。具体的签名生成过程可以参考 JS-SDK 签名算法生成过程。

为什么需要配置 JS-SDK？

即使我们不直接使用 JS-API，微信开放标签仍然涉及敏感操作（如唤起外部 App 或小程序等）。这些操作必须经过微信的授权验证，而 JS-SDK 提供了身份验证流程，通过签名机制确认当前页面的合法性，确保只有经过授权的页面能够使用开放标签功能，防止滥用。

实现方案

在成功初始化 wx.config 后，可以在页面中使用 wx-open-launch-app 标签来实现目标应用的唤起。以下是 Vue.js 代码示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<template>
  <div class="wx-tag-container">
    <wx-open-launch-app
        appid="appid"
        :extinfo="extinfo"
        style="position:absolute;top:0;left:0;right:0;bottom:0;opacity: 0"
        @ready="handleReady"
        @launch="handleLaunch"
        @error="handleError"
    >
      <script type="text/wxtag-template">
        <button/>
      </script>
    </wx-open-launch-app>
    <button class="bt" @click="openApp">打开APP</button>
  </div>
</template>
  • appid：指定要启动的应用的微信 AppID，需根据目标应用填写。
  • extinfo：用于传递额外的信息，格式自定义，由跳转的应用自行解析处理。详细信息请参考文档 《App获取开放标签中的 extinfo 数据》。
  • <script type="text/wxtag-template">：
    • 这是微信专用的标签类型，用于指定微信开放组件的内部内容。
    • 微信会解析此内容并将其作为开放标签的一部分，而不会执行普通的 JavaScript 脚本。
    • 标签内容样式易受控制，因此通常使用 CSS 设置透明度 (opacity: 0) 并通过绝对定位将自定义按钮覆盖在 wx-open-launch-app 标签上，以便实现自定义样式和更好的用户交互体验。
  • 事件回调：
    • ready：标签准备就绪事件。
    • launch：跳转成功事件。
    • error：跳转失败事件，常见错误情况可以参考下面部分。

常见问题

error 事件的 errMsg 返回值说明如下：

errMsg 说明
“launch:fail” 当前场景不支持跳转，或 Android 上该应用未安装，或 iOS 上用户在弹窗上点击确认但该应用未安装。
“launch:fail_check fail” 校验 App 跳转权限失败，请确认是否正确绑定 AppID，且域名是否完全一致。

常见触发 “launch:fail” 的情况：

  1. 微信内分享的网页不能直接是链接文本：
    • 如果在微信中分享的网页是以文本链接形式提供的，可能会导致无法唤起应用。可以将网页保存为卡片分享或二维码形式。
  2. 本地测试时未签名的 APK：
    • 如果在安卓测试时，APK 未签名，微信开放标签（如 wx-open-launch-app）会依赖应用的签名进行校验。未签名的 APK 将无法通过微信的安全校验，导致唤起失败。确保 APK 使用合适的签名。

总结

  • URL Scheme 实现简单，但在微信环境中可能会受到限制，不适合用于直接在微信中调用外部应用。
  • 微信开放标签 仅能在微信浏览器内使用，适合微信生态中的应用唤起。其安全性较高，操作流程较为复杂，但可以有效避免 URL Scheme 可能遇到的安全性和跨平台问题。

通常情况下，可以通过判断客户端环境来采用双重方案，灵活选择 URL Scheme 或微信开放标签的方式进行应用唤起。