Android URL 响应实战:从隐式 Intent 到 App Links(以 cw-omnibus URLHandler 示例项目为例)
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_ACTIONfilter 进入,未携带数据),显示提示文本;否则把完整 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 域名的默认处理者,点击链接时直接打开应用,不再弹出选择器。该机制由两部分组成:
- Manifest 中为 intent-filter 添加
android:autoVerify="true"; - 在目标域名的
/.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"+httpsscheme,将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() 数据解析展开——掌握这一套组合,即可在自己的应用中实现从网页到应用的丝滑跳转。