跳到主要内容
版本：v3

使用Universal Links和App Links实现深度链接

支持平台：iOS, Android

Universal Links（iOS）和App Links（Android）能够让用户直接跳转到原生应用内的特定内容（通常称为深度链接）。

当用户点击深度链接时，系统会直接将用户带入您的应用，无需先经过设备浏览器或网站。如果应用未安装，则会跳转到网站。这种机制非常适合为Web、iOS和Android构建的跨平台应用：提供无缝的移动体验，同时优雅地回退到网页版。

优势：

  • 安全性：使用您拥有的HTTPS域名链接，确保其他应用无法冒用您的链接
  • 无缝体验：同一个URL同时适用于网站和应用，确保用户总能获取所需内容
  • 提升参与度：链接可通过电子邮件客户端、搜索引擎结果等多种渠道打开

演示视频​

以下是实际效果示例。用户已安装原生应用，点击邮件中的链接后直接进入应用。首先是根链接（https://beerswift.app）跳转到应用首页，然后是深度链接（https://beerswift.app/tabs/tab3）直达Tab3页面。

准备工作​

  • 已完成初始配置的Capacitor应用
  • iOS开发需要加入Apple开发者计划

本文示例将使用https://beerswift.app作为Web应用链接。

使用Capacitor App API实现深度链接路由​

当用户点击深度链接打开原生应用时，移动操作系统不会自动知道路由到哪个页面。这需要通过Capacitor App API在应用启动时实现。

如果您的网站和应用路径不一致，需要实现更复杂的URL模式匹配（参考此指南）。如果使用相同代码库则非常简单，只需重定向到相同URL即可。以下示例假设两者路径一致。

Angular​

路由配置应放在app.component.ts中。首先导入Angular的NgZone和Router，以及Capacitor的App：

import { Component, NgZone } from '@angular/core';
import { Router } from '@angular/router';
import { App, URLOpenListenerEvent } from '@capacitor/app';

然后在构造函数中添加Router和NgZone：

constructor(private router: Router, private zone: NgZone) {
    this.initializeApp();
}

最后监听appUrlOpen事件，发现深度链接时进行重定向：

initializeApp() {
    App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => {
        this.zone.run(() => {
            // 示例URL：https://beerswift.app/tabs/tab2
            // slug = /tabs/tab2
            const slug = event.url.split(".app").pop();
            if (slug) {
                this.router.navigateByUrl(slug);
            }
            // 若无匹配项则不处理，由常规路由逻辑接管
        });
    });
}

React​

React有多种实现方式。一种方法是新建组件封装App API监听功能，然后添加到App.tsx中。首先创建AppUrlListener.tsx并导入React Router的useHistory钩子和Capacitor App API：

import React, { useEffect } from 'react';
import { useHistory } from 'react-router-dom';
import { App, URLOpenListenerEvent } from '@capacitor/app';

然后定义AppUrlListener组件，监听appUrlOpen事件并在发现深度链接时重定向：

const AppUrlListener: React.FC<any> = () => {
  let history = useHistory();
  useEffect(() => {
    App.addListener('appUrlOpen', (event: URLOpenListenerEvent) => {
      // 示例URL：https://beerswift.app/tabs/tab2
      // slug = /tabs/tab2
      const slug = event.url.split('.app').pop();
      if (slug) {
        history.push(slug);
      }
      // 若无匹配项则不处理，由常规路由逻辑接管
    });
  }, []);

  return null;
};

export default AppUrlListener;

在App.tsx中导入新组件：

import AppUrlListener from './pages/AppUrlListener';

然后将其添加到IonReactRouter内（确保History钩子可用）：

const App: React.FC = () => {
  return (
    <IonApp>
      <IonReactRouter>
        <AppUrlListener></AppUrlListener>
        <IonRouterOutlet>
          <Route path="/home" component={Home} exact={true} />
          <Route exact path="/" render={() => <Redirect to="/home" />} />
        </IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
};

Vue​

VueJS提供原生集成的Vue Router路由系统。要实现深度链接，首先在路由配置文件（通常是routes.js）中导入Capacitor的App以及Vue和VueRouter：

import { App, URLOpenListenerEvent } from '@capacitor/app';
import Vue from 'vue';
import VueRouter from 'vue-router';

然后用Vue Router配置路由（详见Vue Router入门指南）：

const router = new VueRouter({
  routes: [],
});

建议使用mode: history以避免处理#符号。

让Vue知晓您正在使用Vue Router并注册路由：

const VueApp = new Vue({
  router,
}).$mount('#app');

最后注册深度链接监听器，捕获appUrlOpen事件后交由Vue Router导航：

App.addListener('appUrlOpen', function (event: URLOpenListenerEvent) {
  // 示例URL：https://beerswift.app/tabs/tabs2
  // slug = /tabs/tabs2
  const slug = event.url.split('.app').pop();

  // 仅在有slug时跳转
  if (slug) {
    router.push({
      path: slug,
    });
  }
});

创建网站关联文件​

为了让苹果和谷歌允许深度链接打开应用，需要在网站的.well-known目录下创建双向关联文件（如：https://beerswift.app/.well-known/）。

请继续阅读iOS和Android的具体配置说明。

iOS配置​

iOS配置包括创建网站关联文件和在原生应用中注册域名。

必须加入Apple开发者计划。

创建网站关联文件​

首先登录Apple开发者网站，进入"Certificates, Identifiers, & Profiles"部分选择应用标识符。记下Team ID和Bundle ID，并在Capabilities中启用"Associated Domains"：

iOS标识符配置

然后创建网站关联文件apple-app-site-association（注意：虽是JSON文件但不要加扩展名）。

示例内容如下（替换TEAMID.BUNDLEID为您自己的ID）：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.BUNDLEID",
        "paths": ["*"]
      }
    ]
  }
}

将文件上传到HTTPS网站，然后用Apple的验证工具检查配置，URL格式应为：https://beerswift.app/.well-known/apple-app-site-association

添加关联域名​

最后在Xcode中配置应用识别传入链接。打开Signing & Capabilities，添加"Associated Domains"，域名格式为applinks:yourdomain.com：

Xcode关联域名

Android配置​

Android配置包括创建网站关联文件和配置Intent Filter。

创建网站关联文件​

需要提供Android证书的SHA256指纹。如果没有证书，先创建：

keytool -genkey -v -keystore KEY-NAME.keystore -alias ALIAS -keyalg RSA -keysize 2048 -validity 10000

使用keytool命令查看证书详情获取SHA256指纹：

keytool -list -v -keystore my-release-key.keystore

然后使用Google的Asset Links工具生成网站关联文件，填写域名、应用包名和SHA256指纹：

Android标识符配置

将生成的JSON保存为.well-known/assetlinks.json：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.netkosoft.beerswift",
      "sha256_cert_fingerprints": ["43:12:D4:27:D7:C4:14..."]
    }
  }
]

部署文件后点击"Test statement"验证配置。

添加Intent Filter​

最后在AndroidManifest.xml的<activity>元素中添加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="beerswift.app" />
</intent-filter>

完整Activity配置示例：

<activity
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale"
    android:name="com.netkosoft.beerswift.MainActivity"
    android:label="@string/title_activity_main"
    android:theme="@style/AppTheme.NoActionBarLaunch"
    android:launchMode="singleTask">

    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </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="beerswift.app" />
    </intent-filter>
</activity>

网站配置细节​

不同技术栈的网站配置方式各异：

Angular​

将关联文件放在src/.well-known，然后在angular.json的assets配置中添加：

{
  "glob": "**/*",
  "input": "src/.well-known",
  "output": ".well-known/"
}

构建后部署。

NuxtJS​

将文件放在static/.well-known目录，直接构建部署即可。

React​

将文件放在public/.well-known目录，直接构建部署。

WordPress​

参考此指南。

验证​

网站需要托管关联文件，但应用无需上架应用商店。连接设备部署原生应用后，点击网站链接测试是否能正确打开应用。

参考资源​

Contents

编辑此页