网页唤起 Android App 调试笔记（App Links）

在最近的项目中，我遇到了 网页访问特定 URL 应该唤起 Android App，但实际只打开网页 的问题。通过调试和排查，整理出以下经验和步骤。

#1. 项目与环境信息（脱敏处理）

• 网站域名：https://[your-domain].com

• 唤起页面：/device-contract

• Android App 包名：com.example.app

• intent-filter 配置示例：

复制<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="https"
        android:host="[your-domain].com"
        android:pathPrefix="/device-contract" />
</intent-filter>

• assetlinks.json 已上线，包含 App 的 SHA256 签名指纹

#2. 问题现象

• 用户访问 /device-contract 页面时，网页打开了，但 App 没有唤起

• 尝试在网页中使用：

  • window.location.href

  • 第三方库如 callapp-lib

• 均未能触发 App 唤起

#3. 分析原因

通过对比和调试，可能原因包括：

1. assetlinks.json 与 App 的 SHA256 不匹配

   • Android 系统会验证 assetlinks.json 是否与安装的 App 匹配

2. App Links 未通过系统验证

   • Android 12+ 要求 autoVerify，未验证成功不会自动唤起

3. 安装顺序问题

   • App 在 assetlinks.json 上线前安装，可能无法通过验证

4. 浏览器限制

   • 某些浏览器或内置 WebView 不支持自动 App Links

   • 微信、QQ、支付宝内置浏览器需要 fallback

#4. 调试流程

#4.1 安装 adb

在 Mac 上使用 Homebrew 安装：

复制brew install android-platform-tools

#4.2 查看设备是否连接

复制adb devices

#4.3 检查 App Links 状态

复制adb shell pm get-app-links com.example.app

输出示例：

复制com.example.app:
  Domain verification state:
    [your-domain].com: verified

verified 表示 Android 已通过 assetlinks.json 验证，可以自动唤起 App。

#4.4 测试唤起

使用 adb 直接触发 URL：

复制adb shell am start -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE \
  -d "https://[your-domain].com/device-contract?gpid=123"

• 如果 App 弹出 → 系统配置正确

• 如果未弹出 → 需要检查浏览器或 assetlinks.json 配置

#5. 网页端处理建议

• 支持 App Links 的浏览器 → 网页无需操作，系统自动唤起 App

• 不支持的浏览器 → 提供 fallback：

复制<a href="exampleapp://device-contract?gpid=123">打开 App</a>

• 页面示例（Next.js）：

复制import { useEffect } from "react";

const DeviceContractPage = () => {
  useEffect(() => {
    const timeout = setTimeout(() => {
      window.location.href = "exampleapp://device-contract" + window.location.search;
    }, 500);
    return () => clearTimeout(timeout);
  }, []);

  return (
    <div style={{ textAlign: "center", marginTop: "100px" }}>
      <h2>正在启动 App…</h2>
      <p>如果没有自动打开，请点击下面按钮</p>
      <a
        href={"exampleapp://device-contract" + window.location.search}
        style={{
          display: "inline-block",
          padding: "10px 20px",
          backgroundColor: "#4CAF50",
          color: "#fff",
          borderRadius: "6px",
          textDecoration: "none",
          marginTop: "20px",
        }}
      >
        打开 App
      </a>
    </div>
  );
};

export default DeviceContractPage;

#6. 总结

1. 系统验证是核心

   • adb shell pm get-app-links 检查是否 verified

   • assetlinks.json 必须包含正确的 SHA256 签名

2. 网页端无需 JS 强行跳转

   • App Links 自动唤起由系统处理

   • JS 仅作为 fallback 或不支持 App Links 的浏览器处理

3. 浏览器兼容性

   • 内置浏览器（微信/支付宝/QQ）通常不支持 → 提供 scheme fallback

4. 调试流程清晰

   • adb 查看 App Links → 直接 adb 测试 URL → 确认网页 fallback