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

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

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

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

<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 配置

<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 文件，路径固定为：

https://example.com/.well-known/assetlinks.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:..."
      ]
    }
  }
]

获取签名指纹：

# 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 里：

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，务必处理。

四、与 Navigation Component 集成

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

<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：

<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 的签名不同，开发阶段建议把两个指纹都加进去

验证工具：

# 在线验证
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，可以查询验证状态

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 默认会被加入当前返回栈。如果想让深度链接打开一个全新的任务栈：

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

或在 Intent Flag 里处理：

intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP

5.4 测试深度链接

# 测试 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

六、多域名与子路径策略

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

<!-- 同一个 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 复用：

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

小结

关键结论：

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