Capacitor项目中Android 13深度链接失效问题解析

问题背景

在移动应用开发中，深度链接(Deeplink)是一项重要功能，它允许用户通过点击网页链接直接打开应用中的特定页面。然而，在使用Capacitor框架开发的应用中，开发者报告了一个关键问题：在Android 13设备上，深度链接功能失效，点击网站链接只会打开浏览器而不是目标应用。

问题表现

该问题主要表现为：

• 在Android 10设备上深度链接工作正常
• 在Android 12及13设备上点击链接会直接跳转至浏览器
• 应用无法捕获到appUrlOpen事件

技术分析

Android 12+的深度链接机制变更

从Android 12开始，Google引入了更严格的深度链接验证机制，主要变化包括：

1. 应用ID匹配要求：Android现在要求网站域名必须与应用ID完全匹配。例如，如果网站是demo.shopmyl.ink，那么应用的包名必须是ink.shopmyl.demo的逆序形式。

2. 数字签名验证：系统会验证应用的签名证书指纹是否与assetlinks.json文件中声明的指纹一致。这意味着：

   • 开发版本必须使用与发布版本相同的签名证书
   • 调试版本默认无法通过验证，除非特别配置

3. 验证文件位置：assetlinks.json必须放置在网站的.well-known目录下，且必须能被正确访问。

Capacitor配置要点

在Capacitor项目中，确保深度链接正常工作需要注意：

1. AndroidManifest.xml配置：

<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="demo.shopmyl.ink" />
</intent-filter>

2. assetlinks.json文件内容示例：

[{
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
        "namespace": "android_app",
        "package_name": "ink.shopmyl.demo",
        "sha256_cert_fingerprints": ["你的应用签名SHA256指纹"]
    }
}]

解决方案

1. 检查应用ID匹配：

   • 确保capacitor.config.ts中的appId与网站域名逆序一致
   • 例如网站demo.shopmyl.ink对应应用ID应为ink.shopmyl.demo

2. 验证签名证书：

   • 使用发布签名证书进行测试
   • 获取正确的SHA256指纹并更新到assetlinks.json

3. 测试验证状态：

   • 使用adb命令验证深度链接配置：

   adb shell pm verify-app-links --package ink.shopmyl.demo
   

4. 处理调试环境：

   • 为调试构建配置专门的签名证书
   • 将调试证书指纹也添加到assetlinks.json

最佳实践建议

1. 统一开发和生产环境：尽可能保持开发和生产环境使用相同的签名配置。

2. 自动化验证：在CI/CD流程中加入深度链接验证步骤。

3. 渐进式降级：当深度链接验证失败时，可以考虑引导用户从应用内打开目标页面。

4. 全面测试：在多个Android版本上进行测试，特别是Android 12及以上版本。

总结

Android 12及更高版本对深度链接引入了更严格的安全验证机制，这要求开发者在Capacitor项目中特别注意应用ID、数字签名和验证文件的正确配置。通过理解这些机制变化并遵循正确的配置流程，可以确保深度链接功能在所有Android版本上正常工作。