配置网站关联性和动态规则

如需支持应用链接，您必须创建一个Digital Asset Links JSON 文件，名为assetlinks.json，并将其发布到您网站上的一个众所周知的位置。此文件会公开声明哪些应用有权处理您网域的链接，Android 设备将从您的服务器检索此文件以验证您的深层链接。

对于 Android 15 及更高版本中的动态应用链接，您还可以在 assetlinks.json 文件中定义动态规则配置，例如路径、网址片段和查询参数的模式匹配器。搭载 Android 15（API 级别 35）或更高版本且已安装 Google 服务的 Android 设备会定期检索该文件，并将您的动态配置与应用清单中的静态配置合并。

本指南介绍了如何准备 assetlinks.json 文件并将其发布到您的网站上。如果您愿意，也可以使用 Play 深层链接工具或 Android Studio App Links Assistant 生成 assetlinks.json 文件。如需了解详情，请参阅应用链接开发者工具。

声明网站关联性

您必须在网站上发布 Digital Asset Links JSON 文件，以指示与网站相关联的 Android 应用并验证应用的网址 intent。JSON 文件使用下列字段标识关联的应用：

package_name：在应用的应用 ID 声明在应用的 build.gradle 文件中。
sha256_cert_fingerprints：应用的签名证书的 SHA256 指纹。您可以使用 Java 密钥工具，通过以下命令生成该指纹：

keytool -list -v -keystore my-release-key.keystore

此字段支持多个指纹，这些指纹可用于支持不同版本的应用，例如调试版 build 和正式版 build。如果您的应用使用的是 Play 应用签名，则在本地运行 keytool 生成的证书指纹通常与用户设备上的证书指纹不匹配。您可以在 Play 管理中心开发者账号的“发布”>“设置”>“应用签名”下验证您的应用是否使用的是 Play 应用签名；如果是，您还可以在同一页面上找到适用于您的应用的正确 Digital Asset Links JSON 代码段。Release > Setup > App signing

以下 assetlinks.json 示例文件可为 com.example Android 应用授予链接打开权限：

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

将网站与多个应用相关联

网站可以在同一 assetlinks.json 文件内声明与多个应用的关联性。以下文件清单展示了一个声明示例文件，该文件分别声明了与两个应用的关联，并且位于 https://www.example.com/.well-known/assetlinks.json 中：

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

不同的应用可以处理同一网站托管下的不同资源对应的链接。例如，app1 可能声明了一个对应于 https://example.com/articles 的 intent 过滤器，而 app2 可能声明了一个对应于 https://example.com/videos 的 intent 过滤器。

将多个网站与同一应用相关联

多个网站可在各自的 assetlinks.json 文件中声明与同一应用的关联性。以下文件清单展示了如何声明 example.com 和 example.net 与 app1 的关联性。第一个清单展示了 example.com 与 app1 的关联：

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

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

下一个列表展示了 example.net 与 app1 的关联。只有这些文件的托管位置不同（.com 和 .net）：

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

配置动态规则

Android 15 及更高版本中的动态应用链接可让您使用服务器端深层链接匹配规则，这些规则可与您在应用清单中静态定义的规则协同工作。您可以在 assetlinks.json 文件中定义动态规则。您可以选择是否添加此文件。

搭载 Android 15（API 级别 35）或更高版本且已安装 Google 服务的 Android 设备会定期从您的服务器检索此文件，并将您的动态规则配置与应用清单中的静态配置合并。以下是包含动态规则的 assetlinks.json 文件示例：

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

代码要点

动态应用链接添加了一个名为 dynamic_app_link_components 的新 Digital Asset Links 关系扩展，您可以在其中配置动态规则。
动态规则可以包含路径、网址片段和查询参数的模式匹配器。
您还可以将任何模式匹配器标记为排除项，这样匹配的网址就不会打开您的应用。
此示例展示了路径 ("/")、网址片段 ("#")、和查询参数 ("?") 的匹配器示例，以及排除的匹配器 ("exclude")
如果文件中的任何字段格式有误或为空，Android 会舍弃动态规则，设备会回退到应用清单中静态定义的规则。

动态规则只能指定适用于您在应用清单文件中声明的网域范围内的规则。请参阅下文。

声明动态规则

动态应用链接支持新的 dynamic_app_link_components 关系扩展，该扩展包含一个规则对象数组。每条规则都是使用路径、网址片段和查询参数的模式匹配器定义的，这些匹配器将打开您的应用。匹配器也可以单独排除，这样它们就不会打开您的应用。所有这些都是可选的。

路径匹配
- 键："/"
- 值：单个字符串，网址路径的匹配表达式
网址片段匹配
- 键："#"
- 值：单个字符串，网址片段的匹配表达式
查询参数匹配
- 键："?"
- 值：用于匹配网址查询参数中的键值对的字典。
- 例如，字典 {"?", {"dl": "*", "in_app":"true"} 将匹配查询字符串 "?in_app=true&dl=abc"。
- 字典中键值对的顺序不需要与查询字符串中键值对的顺序一致。此外，字典不需要匹配查询字符串中的所有键值对，但必须为每个字典条目找到匹配项。
- 例如，该字典还会匹配查询字符串 "?lang=en&in_app=true&tz=pst&dl=abc"，但不匹配查询字符串 "?lang=en&tz=pst&dl=abc"
已排除
- 键："exclude"
- 值：为 dynamic_app_link_components 中定义的每条规则提供的可选 true/false 值（请参阅示例）。

您可以在模式匹配器中使用以下特殊字符：

"*" 匹配零个或多个字符，直到在匹配字符串中找到模式中通配符后的字符
"?" 匹配任何单个字符
"?*" 匹配 1 个或多个字符

对于值，没有其他字符限制。

对动态规则排序

规则的声明顺序很重要。Android 会按顺序评估每条规则，直到找到匹配项。

以下示例展示了排序如何影响处理。第一条规则匹配所有路径（“*”），但排除匹配项（exclude: true），这意味着它会排除所有网址打开应用。在这种情况下，允许“/path1”的第二条规则永远不会被评估。

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

不过，在下一个示例中，“/path1”规则首先声明，因此它将首先被评估，并将为与“/path1”匹配的网址打开应用。排除所有网址打开应用的第二条规则将第二个被评估，但仅当第一条规则不是匹配项时才会如此。

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

如果在声明的组件列表中未找到匹配项，则网址不会打开应用。在以下示例中，没有路径与“/path3”匹配，因此设备会将此路径视为排除项。

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

如果您希望 dynamic_app_link_components 仅排除某些网址部分，但允许所有其他部分，则此行为非常重要。在以下示例中，省略允许所有剩余路径的最后一条规则意味着所有网址都将从应用中排除。

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

正确限定动态规则的范围

在定义服务器端规则以用于 Android 15 及更高版本中的动态应用链接时，请务必适当地限定规则的范围，以便它们能够与应用清单中声明的静态 intent 过滤器协同工作并对其进行补充。

在 assetlinks.json 文件中声明的动态规则只能为在应用的 AndroidManifest.xml 文件中声明的主机指定规则。动态规则无法扩大您在应用清单中静态声明的网址规则的范围 。

因此，我们建议您在动态规则和静态规则中采用以下方法：

在应用清单中，设置范围尽可能广泛的规则，例如仅声明架构和网域
依靠服务器端动态规则进行进一步优化，例如路径级路由。

通过这种理想的配置，您将能够根据需要在 assetlinks.json 文件中动态添加新的应用链接路径，并且知道它们将适合您在应用清单中设置的广泛范围。

仅声明一次 dynamic_app_link_components

为了正确处理您的规则，请针对给定的网站、关系和应用，在语句中仅声明一个 dynamic_app_link_components 对象。

查找针对同一网站、关系和应用的多个语句，这些语句声明了 dynamic_app_link_components 对象。
查找在单个语句中声明的多个 dynamic_app_link_components 对象

在这些情况下，Android 不保证将使用哪个动态规则配置。

动态规则与之前的应用链接配置的兼容性

如果您已支持应用链接，则可以直接在现有的 assetlinks.json 文件中添加对动态应用链接的支持。用于验证应用链接的关系字段保持不变，您可以添加新的关系扩展字段以用于动态规则，而无需进行任何其他更改。

搭载 Android 14（API 级别 34 或更低版本）的 Android 设备会忽略动态规则的新关系扩展字段，而搭载 Android 15 及更高版本的设备会将这些规则与清单定义的规则合并。

发布 JSON 验证文件

您必须在以下位置发布 JSON 验证文件：

https://domain.name/.well-known/assetlinks.json

请确保以下几点：

使用内容类型 application/json 发布 assetlinks.json 文件。
无论应用的 intent 过滤器是否将数据架构声明为 HTTPS，都必须可通过 HTTPS 连接访问 assetlinks.json 文件。
assetlinks.json 文件必须无需重定向即可访问（无 301 或 302 重定向）。
如果您的应用链接支持多个主机网域，则必须在每个网域上分别发布 assetlinks.json 文件。请参阅支持多个主机的应用链接。
请勿发布清单文件中的测试网址无法供公众访问的应用（例如，任何只可通过 VPN 访问的应用）。作为这种情况下的应急措施，您可以配置编译变体以针对开发编译版本生成不同的清单文件。

请参阅以下相关指南：