[Android 从零到一] Android 深度链接与 App Links：从 URI Scheme 到可验证的应用跳转

Android 深度链接与 App Links：从 URI Scheme 到可验证的应用跳转

深度链接（Deep Link）是移动端产品常见的诉求：从网页、通知、分享卡片里点一个链接，直接打开 App 内的某个页面。但实现方式不止一种，不同方案的安全性和用户体验差异很大。本文从最基础的 URI Scheme 讲起，逐步过渡到 Android App Links 的完整实现与常见踩坑。

一、URI Scheme：最简单，也最脆弱

最早的做法是在 AndroidManifest.xml 里给 Activity 注册一个自定义 scheme：

xml 复制代码

<activity android:name=".DeepLinkActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="myapp" android:host="detail" />
    </intent-filter>
</activity>

这样 myapp://detail?id=123 就能拉起 App。

问题： 任何 App 都可以声明相同的 scheme。用户点击链接时，系统会弹出选择框；恶意 App 也可以劫持这个链接，造成安全隐患。对于支付、登录回调等敏感场景，URI Scheme 基本不可用。

二、App Links：基于域名验证的可信跳转

Android 6.0（API 23）引入了 App Links，核心思路是：

让 App 证明自己拥有某个域名，系统验证通过后，这个域名的 HTTP/HTTPS 链接就只会打开你的 App，不再弹选择框。

2.1 Manifest 配置

xml 复制代码

<activity android:name=".DeepLinkActivity">
    <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="example.com"
            android:pathPrefix="/detail" />
    </intent-filter>
</activity>

关键点：

android:autoVerify="true" 告诉系统在 App 安装时自动验证域名归属
scheme 必须是 https（或 http，但强烈推荐 https）
可以配置多个 <data> 标签，支持多路径

2.2 Digital Asset Links 文件

在你的服务器上放一个 JSON 文件，路径固定为：

arduino 复制代码

https://example.com/.well-known/assetlinks.json

内容如下：

json 复制代码

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.myapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:..."
      ]
    }
  }
]

获取签名指纹：

bash 复制代码

# debug keystore
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# release keystore
keytool -list -v -keystore /path/to/release.keystore

从输出中找 SHA256: 那行，格式化成冒号分隔的大写形式即可。

2.3 验证流程

App 安装后，系统会异步请求 assetlinks.json，对比包名和签名。验证成功后：

对应域名的 https 链接会直接打开 App，不弹选择框
验证失败时降级为普通 Intent，仍会弹选择框或打开浏览器

三、接收并解析深度链接

在目标 Activity 里：

kotlin 复制代码

class DeepLinkActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        handleIntent(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleIntent(intent)
    }

    private fun handleIntent(intent: Intent) {
        val uri: Uri? = intent.data
        if (uri == null) {
            // 正常启动，不是深度链接
            navigateToHome()
            return
        }

        val path = uri.path ?: ""
        val id = uri.getQueryParameter("id")

        when {
            path.startsWith("/detail") && id != null -> {
                navigateToDetail(id)
            }
            path.startsWith("/profile") -> {
                val userId = uri.lastPathSegment
                navigateToProfile(userId)
            }
            else -> navigateToHome()
        }
        finish() // DeepLinkActivity 只做路由，导航完就关掉
    }
}

注意 onNewIntent：当 Activity 以 singleTop 或 singleTask 启动模式运行时，重复点击同一链接不会重建 Activity，而是走 onNewIntent，务必处理。

如果项目用了 Jetpack Navigation，可以直接在 nav_graph.xml 里配置 deep link：

xml 复制代码

<fragment
    android:id="@+id/detailFragment"
    android:name="com.example.DetailFragment">
    <argument
        android:name="itemId"
        app:argType="string" />
    <deepLink
        app:uri="https://example.com/detail/{itemId}" />
</fragment>

然后在 AndroidManifest.xml 里用 <nav-graph> 自动生成 intent-filter：

xml 复制代码

<activity android:name=".MainActivity">
    <nav-graph android:value="@navigation/nav_graph" />
</activity>

Navigation 会自动解析 URI 参数，直接填充到 navArgs 里，省去手动解析的代码。

五、常见踩坑

5.1 验证一直不通过

文件路径问题： .well-known/ 目录在很多 Web 服务器上默认不返回隐藏目录，检查 Nginx/Apache 配置
Content-Type： 必须是 application/json，不能是 text/plain
重定向： assetlinks.json 不能有 HTTP 重定向，系统不会跟随
多签名： debug 和 release 的签名不同，开发阶段建议把两个指纹都加进去

验证工具：

bash 复制代码

# 在线验证
https://developers.google.com/digital-asset-links/tools/generator

# adb 强制重新验证（需要重新安装或清除验证缓存）
adb shell pm get-app-links --package com.example.myapp

5.2 Android 12 的变化

Android 12（API 31）收紧了未验证链接的处理：

如果 App Links 验证失败，链接不再默认打开 App，而是直接在浏览器中打开
同时引入了新的 API：DomainVerificationManager，可以查询验证状态

kotlin 复制代码

val manager = getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(packageName)
val unverified = userState?.hostToStateMap
    ?.filter { it.value == DomainVerificationUserState.DOMAIN_STATE_NONE }
    ?.keys
// 未验证的域名列表

5.3 LaunchMode 与返回栈

深度链接打开的 Activity 默认会被加入当前返回栈。如果想让深度链接打开一个全新的任务栈：

xml 复制代码

<activity
    android:name=".DeepLinkActivity"
    android:launchMode="singleTask"
    android:taskAffinity="" />

或在 Intent Flag 里处理：

kotlin 复制代码

intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP

5.4 测试深度链接

bash 复制代码

# 测试 URI Scheme
adb shell am start -W -a android.intent.action.VIEW \
    -d "myapp://detail?id=123" com.example.myapp

# 测试 App Links（https）
adb shell am start -W -a android.intent.action.VIEW \
    -d "https://example.com/detail?id=456" com.example.myapp

六、多域名与子路径策略

实际项目中往往有多个域名（生产、测试、国际化）需要处理：

xml 复制代码

<!-- 同一个 intent-filter 只能写一个 host -->
<intent-filter android:autoVerify="true">
    <data android:scheme="https" android:host="example.com" />
</intent-filter>
<intent-filter android:autoVerify="true">
    <data android:scheme="https" android:host="www.example.com" />
</intent-filter>
<intent-filter android:autoVerify="true">
    <data android:scheme="https" android:host="m.example.com" />
</intent-filter>

每个域名都需要单独放 assetlinks.json，或者用 include 指向同一个文件。Digital Asset Links 支持通过 include 复用：

json 复制代码

[{
  "include": "https://primary.example.com/.well-known/assetlinks.json"
}]

小结

方案	安全性	用户体验	适用场景
URI Scheme	低（可被劫持）	可能弹选择框	内部跳转、无安全需求
App Links（已验证）	高（域名绑定）	直接打开，无弹框	分享、通知、支付回调
App Links（未验证）	低	降级到浏览器	---

关键结论：

对外链接（分享、推广、邮件）优先用 App Links，完成域名验证
assetlinks.json 要在 CI/CD 里维护，发布新签名时同步更新指纹
Android 12+ 验证失败的代价更重，上线前务必用 adb shell pm get-app-links 确认状态
Navigation Component 的 <deepLink> 是减少样板代码的好方式，但要注意参数类型安全

[Android 从零到一] Android 深度链接与 App Links：从 URI Scheme 到可验证的应用跳转

Android 深度链接与 App Links：从 URI Scheme 到可验证的应用跳转

一、URI Scheme：最简单，也最脆弱

二、App Links：基于域名验证的可信跳转

2.1 Manifest 配置

2.2 Digital Asset Links 文件

2.3 验证流程

三、接收并解析深度链接

四、与 Navigation Component 集成

五、常见踩坑

5.1 验证一直不通过

5.2 Android 12 的变化

5.3 LaunchMode 与返回栈

5.4 测试深度链接

六、多域名与子路径策略

小结