H5 页面如何唤起 App？一篇搞定通用封装

大家好，我是 彭于晏（手动狗头 🐶），
今天不讲肌肉线条，咱们聊聊很多人做 H5 活动页都绕不开的一个老问题——

🧐「怎么从网页唤起我家的 App？」

比如你在活动页点个“打开App”，
如果用户已经安装，就要直接拉起App，
如果没安装，就要跳转下载页。

看似简单，其实坑挺多，我们来一步步搞定它 ✍️

---

🧠 1. 唤起 App 的基本原理

唤起App的核心就是——Scheme URL协议（有时也叫 URL Scheme / Deeplink）：

myapp://open/home

当用户设备上安装了注册这个 scheme 的 App，浏览器访问这个 URL 时，就会唤起 App。

如果没装 App，浏览器会啥都没反应，所以我们要判断“唤起失败”然后跳转下载页。

---

🧪 2. 最简单的实现

<button id="openBtn">打开App</button>
<script>
  function openApp() {
    const scheme = "myapp://open/home";
    const downloadUrl = "https://www.example.com/download";
    const start = Date.now();

    window.location.href = scheme;

    setTimeout(() => {
      if (Date.now() - start < 2000) {
        // 说明 App 没被唤起
        window.location.href = downloadUrl;
      }
    }, 1500);
  }

  document.querySelector("#openBtn").addEventListener("click", openApp);
</script>

📌 逻辑解释：

• 跳转 scheme → 如果用户有App会唤起。
• 启个定时器 → 如果 2s 内浏览器没被挂到后台（说明没唤起），就去下载页。

---

⚡ 3. 进阶：React + 自定义 Hook 封装

上面那个逻辑只是个最简demo，在实际项目里，我们可以封装成一个 Hook 来调用（比如在 React 项目中）：

import { Toast } from "@/app/components/Toast";
import { useAppSelector } from "@/store/hooks";

export default function useCallApp() {
  const { table: { data: { data: { download_url } = {} } = {} } = {} } =
    useAppSelector((state) => state.share);

  const handleClick = () => {
    let schemeUrl = "";

    // 解析 URL 参数，拼接唤起地址
    try {
      const search = new URLSearchParams(window.location.search);
      const params = search.get("u");
      const decodedStr = atob(params || "");
      const obj = JSON.parse(decodedStr);
      const { news_id, base_id } = obj;

      schemeUrl = `hahahub://feeds?id=${news_id}${
        base_id ? "&base_id=" + base_id : ""
      }`;
    } catch (error) {
      // 解析失败就不拼 scheme
    }

    const handleFail = () => {
      if (download_url) {
        window.open(download_url);
      } else {
        Toast.center(
          "Friends can only be invited after the app is put on the shelves. The app is currently under review."
        );
      }
    };

    const iframe = document.createElement("iframe");
    iframe.style.display = "none";
    iframe.src = schemeUrl;

    document.body.appendChild(iframe);

    setTimeout(() => {
      // 如果 2 秒后页面还在前台，说明没唤起成功
      if (!document.hidden) {
        handleFail();
      }
    }, 2000);
  };

  return handleClick;
}

使用时只要：

const openApp = useCallApp();

<button onClick={openApp}>打开App</button>

📌 小技巧：

• iframe.src 方式唤起 App，比 window.location.href 更温和，不会影响浏览器历史栈。
• document.hidden 检测当前页是否被挂后台，可以大致判断是否唤起成功。

---

📲 4. 实际开发注意事项

• 安卓/iOS 机制不同，在安卓里 scheme:// 大部分浏览器都支持，在iOS里 :contentReference[oaicite:8]{index=8} 支持较好，但 :contentReference[oaicite:9]{index=9}、:contentReference[oaicite:10]{index=10} 等内置浏览器需要做兼容。
• 下载地址建议放应用商店链接，比如 App Store / Google Play，而不是 APK 直链。
• URL参数要Base64编码，防止中文或特殊字符导致 scheme 拼接错误。

---

📚 5. 总结

• scheme:// 是唤起 App 的关键。
• 可以通过 iframe + 定时器兜底跳转下载页。
• 建议在项目中封装成 Hook 或工具函数统一调用。
• 移动端浏览器环境差异较大，要做好兼容测试。

---

👋 我是彭于晏，希望大家的 H5 活动页都能顺利拉起自家 App，让唤起率一路飙升 📈！