Android URL 响应实战:从隐式 Intent 到 App Links(以 cw-omnibus URLHandler 示例项目为例)

原创2026-10-14 22:18:291,436 阅读
文章标签:示例工程教程

Android URL 响应实战:从隐式 Intent 到 App Links(以 cw-omnibus URLHandler 示例项目为例)

本指南基于开源仓库 cw-omnibus 中的 URLHandler 与 URLHandlerMNC 两个示例应用,系统讲解如何让 Android Activity 响应外部 URL:既包括通过 ACTION_VIEW 隐式 Intent 匹配 HTTP 链接与 MIME 类型(传统方案),也包括借助 autoVerify 与 assetlinks.json 实现 Android App Links 官方域名验证(现代方案)。读完本文,你将掌握三类 URL 响应场景的 Manifest 配置写法、Activity 内解析 Intent 数据的编码技巧,以及新旧两代方案的差异与取舍。

说明:本示例来自 The Busy Coder's Guide to Android Development 中关于 Responding to URLs 的章节;下述配置与代码均取自仓库当前实际源码,路径以仓库根目录为基准。

一、项目概览:URLHandler 与 URLHandlerMNC

cw-omnibus 仓库的 Introspection 分类下提供了两个姊妹示例:

项目目录 特点 对应 Manifest 文件
Introspection/URLHandler 早期版本,演示通过 Intent Filter 响应 PDF MIME、HTTP 链接与自定义 Action AndroidManifest.xml
Introspection/URLHandlerMNC MNC(Mars/6.0)之后版本,演示 android:autoVerify="true" + assetlinks.json 的官方 App Links 方案 AndroidManifest.xml、assetlinks.json

两个示例共享同一个包名 com.commonsware.android.urlhandler 和同一个 Activity 类名 URLHandler,但 Manifest 与 Java 实现各有侧重。其 Gradle 配置也略有差异:URLHandler 使用 compileSdkVersion 27(app/build.gradle),URLHandlerMNC 使用 compileSdkVersion 25(app/build.gradle);注意 MNC 版虽然 targetSdkVersion 仅为 19,但代码中已使用验证数字资产链接所需的核心机制。

二、核心概念:Activity 如何“响应 URL”

Android 应用响应 URL 的机制本质是 隐式 Intent(implicit intent):外部组件(浏览器、短信、邮件客户端或其他应用)发起带 ACTION_VIEW 的 Intent 并携带数据(URL 或 MIME 类型),系统在已安装应用中搜索 intent-filter 与之匹配的 Activity,将其拉起并交付数据。匹配的声明位于 AndroidManifest.xml 中 <activity> 节点下的 <intent-filter>。

匹配需要三层信息协同:

  • <action>:声明希望处理的动作,URL 场景下通常是 android.intent.action.VIEW;
  • <category>:声明匹配类别,URL 响应必须包含 android.intent.category.DEFAULT(使隐式 Intent 可送达),若希望浏览器等能发现该入口,还需添加 android.intent.category.BROWSABLE;
  • <data>:声明可接受的数据形态,可指定 scheme、host、path、mimeType 等。

匹配的歧义与优先级

当多个 Activity 匹配同一 URL 时,系统弹出“完成操作”选择器(Chooser)让用户挑选;用户可勾选“始终”以固定默认应用。这一“意图模糊(intent ambiguity)”正是 URL 响应的核心体验:想让应用成为某类链接的默认处理者,就要通过正确的 intent-filter 声明进入候选列表,再借助系统对话框或 App Links 验证成为默认。

三、传统方案:三个 intent-filter 各司其职(URLHandler)

URLHandler 的 AndroidManifest.xml 为同一个 URLHandler Activity 声明了四个 intent-filter:

1. 主入口 filter(MAIN + LAUNCHER)

<intent-filter>
  <action android:name="android.intent.action.MAIN"/>
  <category android:name="android.intent.category.LAUNCHER"/>
</intent-filter>

让应用在启动器中可见,点击图标后以 Intent.ACTION_MAIN 启动 Activity。这是绝大多数应用的标配声明。

2. 响应 PDF MIME 类型

<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:mimeType="application/pdf"/>
</intent-filter>

通过 mimeType 声明本 Activity 可打开 application/pdf 类型的文档。系统在用户点击 PDF 文件或链接时将其列入候选。注意:scheme 未指定时,系统会推断为 content: 和 file: 等文件类 scheme,因此该 filter 覆盖的是“内容类型”而非特定 URL 前缀。

3. 响应 HTTP 链接(host + path + scheme 组合)

<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:host="www.this-so-does-not-exist.com" android:path="/something" android:scheme="http"/>
</intent-filter>

这是“传统”URL 响应方式:通过 scheme="http"、host="www.this-so-does-not-exist.com"、path="/something" 三个属性组合,限定只有访问该主机特定路径的 http:// 链接才会匹配。示例故意使用一个并不存在的域名(www.this-so-does-not-exist.com),作为演示性的“伪深链”,避免与真实网站冲突。可匹配的完整 URL 形如:

http://www.this-so-does-not-exist.com/something

path 属性还可替换为 pathPrefix(前缀匹配)或 pathPattern(正则匹配),用于覆盖更广或更精确的 URL 形态。

4. 响应自定义 Action

<intent-filter>
  <action android:name="com.commonsware.android.MY_ACTION"/>
  <category android:name="android.intent.category.DEFAULT"/>
  <category android:name="android.intent.category.BROWSABLE"/>
</intent-filter>

该 filter 声明响应自定义 Action 字符串 com.commonsware.android.MY_ACTION,且不限定任何 data。它与 2、3 号 filter 相互独立,展示了“按动作匹配”而非“按数据匹配”的另一条路径——其他应用(或本应用)可以构造携带该 Action 的 Intent 直接触发本 Activity。

Activity 内解析 Intent 数据

URLHandler.java 在 onCreate() 中区分两种进入方式:

if (Intent.ACTION_MAIN.equals(getIntent().getAction())) {
  String intentUri=(new Intent("com.commonsware.android.MY_ACTION"))
                      .toUri(Intent.URI_INTENT_SCHEME)
                      .toString();
  uri.setText(intentUri);
  Log.w("URLHandler", intentUri);
}
else {
  Uri data=getIntent().getData();
  if (data==null) {
    uri.setText("Got com.commonsware.android.MY_ACTION Intent");
  }
  else {
    uri.setText(getIntent().getData().toString());
  }
}

逻辑要点:

  • 主入口进入(ACTION_MAIN):此时不会收到 URL 数据,代码反而利用 Intent.toUri(Intent.URI_INTENT_SCHEME) 把“构造出来的自定义 Intent”序列化成一条 intent-scheme URI 字符串,写入界面 TextView 并通过 Log.w 输出。这种“intent://”格式的 URI 可用于网页触发自定义 Intent(早期 WebView 到应用跳转的常见做法),核心价值在于演示 Intent.toUri() 的序列化能力:它会将 Action、Category、Data 等编码为一个可传播的字符串。
  • 隐式 Intent 进入(else 分支):通过 getIntent().getData() 取出 Uri。若为 null(例如通过 MY_ACTION filter 进入,未携带数据),显示提示文本;否则把完整 URI 展示在界面,验证 Activity 确实“接住”了外部链接。

界面布局 main.xml 是一个纵向 LinearLayout,上方 TextView(@id/uri)显示结果,下方按钮“Visit Sample Page”通过 android:onClick="visitSample" 绑定:

public void visitSample(View v) {
  startActivity(new Intent(Intent.ACTION_VIEW,
                           Uri.parse("https://commonsware.com/sample")));
}

点击后用 ACTION_VIEW 打开浏览器访问示例页面——从应用内部反向演示“URL 的发起端”。

四、现代方案:Android App Links 与 autoVerify(URLHandlerMNC)

从 Android 6.0(Marshmallow,代号 MNC)开始,平台引入 Android App Links:允许应用将自己验证为某 HTTPS 域名的默认处理者,点击链接时直接打开应用,不再弹出选择器。该机制由两部分组成:

  1. Manifest 中为 intent-filter 添加 android:autoVerify="true";
  2. 在目标域名的 /.well-known/assetlinks.json 路径放置数字资产链接文件,声明包名与签名指纹。

1. Manifest 声明(autoVerify)

URLHandlerMNC 的 AndroidManifest.xml 中,App Links 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:host="commonsware.com"
    android:scheme="https" />
</intent-filter>

与上一节传统写法对比:

对比项 传统方案(URLHandler) App Links(URLHandlerMNC)
匹配范围 http scheme + 具体 host/path https scheme + host(无 path 限制)
默认行为 弹出选择器让用户选择 验证通过后直达应用,无选择器
附加条件 无 必须部署 assetlinks.json 且校验签名
适用 API 所有版本 主要在 Android 6.0+ 生效

需要注意:autoVerify="true" 只能用于声明 https(或 http)scheme 的 filter,且 host 必须是应用确实要认领的域名。验证动作发生在应用安装/更新后,系统通过 HTTPS 访问域名下的 assetlinks.json 进行校验。

2. 服务器端 assetlinks.json

仓库中提供了 assetlinks.json,需部署在域名根路径 https://commonsware.com/.well-known/assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.commonsware.android.urlhandler",
      "sha256_cert_fingerprints": ["A9:99:84:D8:09:79:10:BB:96:56:85:73:69:32:15:07:F5:D1:4E:92:CA:32:AE:F9:E1:50:82:53:60:5B:CB:E3"]
    }
  }
]

字段含义:

  • relation:固定为 delegate_permission/common.handle_all_urls,表示“授予处理该域名全部 URL 的权限”;
  • target.namespace:固定为 android_app;
  • target.package_name:应用的包名,必须与 Manifest package="com.commonsware.android.urlhandler" 一致;
  • target.sha256_cert_fingerprints:应用签名证书的 SHA-256 指纹(格式为大写十六进制、冒号分隔)。仓库中的指纹是示例签名指纹,实际发布时需替换为你自己的签名证书指纹。

验证仅在 签名指纹、包名与域名三者完全匹配 时通过。调试期可用 adb 相关命令查看验证状态(文中不展开外部命令细节,以仓库证据为准)。

3. 新的 Activity 逻辑

URLHandlerMNC 的 URLHandler.java 与旧版明显不同:

if (Intent.ACTION_VIEW.equals(getIntent().getAction())) {
  findViewById(R.id.visit).setEnabled(false);
}

当以 ACTION_VIEW 进入(即来自链接)时,直接禁用界面上的“访问按钮”——因为应用本身已是该链接的默认处理者,无需再引导用户跳转浏览器。按钮回调则改为:

public void visitSample(View v) {
  startActivity(new Intent(Intent.ACTION_VIEW,
                           Uri.parse("https://commonsware.com/Android/")));
}

从按钮文本“Visit commonsware.com”与布局 main.xml 可见:该按钮只在以 MAIN 方式进入时可用,演示的是“从应用内部打开同一域名网页”的对照实验。这也从侧面说明了 App Links 的体验变化——同一域名,系统级直达 vs 浏览器打开,取决于应用是否被验证为默认处理者。

五、关键实现细节与易错点

1. BROWSABLE 类别的重要性

两个示例的所有 URL 相关 filter 都同时声明了 DEFAULT 与 BROWSABLE:

  • DEFAULT:隐式 Intent 解析的基本要求,缺了它 Activity 无法被隐式 Intent 找到;
  • BROWSABLE:允许浏览器等 Web 上下文将链接解析到该 Activity。若缺少该类别,浏览器中的 URL 点击可能不会将你的应用列为候选。

2. 传统 filter 的“越界”风险

在 App Links 验证机制出现之前,任何应用都可以声明任意域名的 scheme+host filter,用户一旦选择“始终”该应用就会劫持该域名链接。这也是 Android 在 6.0 引入 autoVerify 与 assetlinks.json 的动机:通过加密签名级校验,从系统层面杜绝未授权域名认领。传统方案在当前 Android 版本上对 https 链接已受到系统默认行为约束(多采用 App Links 判定),理解这一点有助于评估历史代码的迁移方向。

3. MIME 与 URL 的 filter 差异

  • 声明 mimeType 的 filter,系统按“内容类型”匹配文件打开场景;
  • 声明 scheme/host/path 的 filter,按 URL 结构匹配链接场景;
  • 两者可以共存于同一 Activity(如本例),入口逻辑通过 getIntent().getAction() 与 getIntent().getData() 区分来源。

4. 数据读取的统一入口

无论哪种 filter 进入,Activity 都应通过 getIntent().getData() 获取 Uri 再解析 scheme、host、path、query 等,避免直接拼接字符串;同时务必处理 getData() 返回 null 的情况(如自定义 Action 进入时),否则会触发 NullPointerException。

六、从本示例迁移到生产环境的建议

  • 替换 assetlinks.json 中的指纹:发布前用正式签名证书的 SHA-256 替换示例指纹,并部署到域名 /.well-known/assetlinks.json,确保可通过 HTTPS 公开访问;
  • 域名收敛到 https:生产环境优先使用 android:autoVerify="true" + https scheme,将 http 链接通过服务器 301/302 重定向到 https,避免双重处理;
  • 多域名场景:每个要认领的域名都需要在 assetlinks.json 中添加对应的 target 条目(或分别在各自域名下部署),同时 Manifest 中为每个域名声明一个带 autoVerify 的 filter;
  • 选择器兜底:即使验证失败或用户曾手动选择“始终浏览器”,应用仍可保留非 autoVerify 的 filter 作为候选,作为降级体验;
  • 深链参数解析:在本例基础上扩展时,可读取 Uri 的 getQueryParameter() 等接口获取深链参数,将 URL 映射为应用内页面路由。

七、小结

通过 URLHandler 与 URLHandlerMNC 两个示例的对照,可以完整看到 Android URL 响应能力的演进:从“声明式 intent-filter + 选择器”的传统深链,到“autoVerify + assetlinks.json 签名验证”的现代 App Links。前者胜在兼容性,后者胜在无选择器直达与安全可信的域名认领。无论采用哪种方案,核心代码路径都围绕 ACTION_VIEW 隐式 Intent、intent-filter 匹配与 getIntent().getData() 数据解析展开——掌握这一套组合,即可在自己的应用中实现从网页到应用的丝滑跳转。

登录后查看全文
cw-omnibus