为应用链接添加 intent 过滤器

应用链接是使用 HTTP 或 HTTPS 架构的深层链接，并经 Android 验证与您的网站相关联。如需注册以处理应用链接，请按以下步骤操作：

  1. 在应用清单中添加一个或多个 intent 过滤器，以指定您的网站网域或网址。
  2. 将 autoVerify="true"attribute 添加到 intent 过滤器元素中。这会向系统发出信号，表明系统应尝试根据您网站的 assetlinks.json 配置验证架构和主机网域。
  3. 声明网站关联。

以下是包含架构、主机以及 autoVerify="true 的应用链接声明示例：

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <!-- Make sure you explicitly set android:autoVerify to "true". -->
    <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" />

        <!-- If a user clicks on a link that uses the "http" scheme, your
             app should be able to delegate that traffic to "https". -->
        <!-- Do not include other schemes, as this will prevent verification. -->
        <data android:scheme="http" />
        <data android:scheme="https" />

        <!-- Include one or more domains that should be verified. -->
        <data android:host="www.example.com" />
        <data android:host="*.example.com" />
    </intent-filter>
</activity>

代码要点

  • AutoVerify：应用链接必须设置 android:autoVerify="true" 属性。它会向系统发出信号，指示系统应尝试验证应用与 <data> 标记中指定的架构和网域之间的关联。建议您向要验证的每个 intent 过滤器添加 autoVerify="true。
  • 数据元素：每个 App Links intent 过滤器都必须包含一个或多个 <data> 元素，用于指定与可验证网站网域匹配的架构和主机格式。
  • 架构：intent 过滤器必须同时包含 http 和 https 架构的 <data> 元素。

  • 主机：您可以选择添加 <data> 元素，以匹配一个或多个主机。使用通配符 (*) 匹配多个子网域（例如 *.example.com）。系统会尝试根据您网站上的 assetlinks.json 文件验证每个主机。请注意，任何路径级路由都应由 assetlinks.json 文件处理（请参阅下面的“最佳实践”部分）。

  • 多个主机：如果您声明了多个主机网域，系统（在 Android 12 及更高版本中）会尝试验证每个网域。如果任何主机通过验证，该应用就会成为来自该已验证主机的链接的默认处理程序。在 Android 11 及更低版本中，即使只有一个主机无法验证，验证也会失败。

  • 多个 intent 过滤器：如果您打算声明唯一网址（例如 scheme 和 host 的特定组合），请务必创建单独的过滤器，因为同一 intent 过滤器中的多个 <data> 元素会合并在一起，以反映其组合属性的所有变体。

清单过滤规则注意事项

如果您要设置过滤器，以便在 Android 15 及更高版本中与动态应用链接搭配使用，请务必注意，在服务器端 assetlinks.json 文件中声明的动态规则无法扩展您在应用清单中静态声明的网址规则的范围。

因此，我们建议您采用以下方法：

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

通过这种理想配置，您可以根据需要在 assetlinks.json 文件中动态添加新的应用链接路径，并确保这些路径符合您在应用清单中设置的广泛范围。

支持多个主机的应用链接

系统必须能够根据该 intent 过滤器中相应网域上托管的 Digital Asset Links 文件，验证应用的网址 intent 过滤器的数据元素中指定的主机。如果验证失败，系统会默认采用其标准行为来解析 intent，如创建指向应用内容的深层链接中所述。不过，该应用仍可作为默认处理程序，处理应用的其他 intent 过滤器中定义的任何网址格式。

例如，如果 https://www.example.com/.well-known/assetlinks.json 处有 assetlinks.json 文件，但 https://www.example.net/.well-known/assetlinks.json 处没有，则具有以下 intent 过滤器的应用将仅通过 https://www.example.com 的验证：

<application>

  <activity android:name="MainActivity">
    <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="http" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
    </intent-filter>
  </activity>
  <activity android:name="SecondActivity">
    <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="https" />
     <data android:host="www.example.net" />
    </intent-filter>
  </activity>

</application>

支持多个子网域的应用链接

Digital Asset Links 协议会将 intent 过滤器中的子网域视为唯一的独立主机。因此，如果您的 intent 过滤器列出了具有不同子网域的多个主机，则必须在每个网域上发布有效的 assetlinks.json。 例如，以下 intent 过滤器包含 www.example.com 和 mobile.example.com 作为接受的 intent 网址主机。因此，必须在 https://www.example.com/.well-known/assetlinks.json 和 https://mobile.example.com/.well-known/assetlinks.json 上发布有效的 assetlinks.json。

<application>
  <activity android:name="MainActivity">
    <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" />
      <data android:scheme="https" />
      <data android:host="www.example.com" />
      <data android:host="mobile.example.com" />
    </intent-filter>
  </activity>
</application>

或者，如果您使用通配符（例如 *.example.com）声明主机名，则必须在根主机名 (example.com) 处发布 assetlinks.json 文件。例如，只要 assetlinks.json 文件发布在 https://example.com/.well-known/assetlinks.json，具有以下 intent 过滤器的应用就会通过 example.com 的任何子名称（例如 foo.example.com）的验证：

<application>
  <activity android:name="MainActivity">
    <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" />
      <data android:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

检查是否有多个应用与同一网域相关联

如果您发布了多个应用，其中每个应用都与同一网域相关联，则它们都可以成功地通过验证。不过，如果这些应用可以解析完全相同的网域主机和路径，就像一个应用的精简版和完整版一样，则只有最近安装的应用才能解析该网域的网络 intent。

在这种情况下，请检查用户设备上是否存在可能冲突的应用，前提是您具有必要的软件包可见性。然后，在应用中显示一个自定义选择器对话框，其中包含调用 queryIntentActivities 的结果。用户可以从对话框中显示的匹配应用列表中选择其首选应用。

动态应用链接功能（包括 assetlinks.json 中的高级匹配规则以及 <uri-relative-filter-group> 的使用）仅在 Android 15（API 级别 35）及更高版本中得到完全支持。

在 Android 14（API 级别 34）及更低版本中，系统只会考虑清单的 <data> 元素中声明的 scheme 和 host，以进行应用链接验证。assetlinks.json 中的路径特定规则、排除项和动态更新不会应用。

这意味着，如果您的清单仅指定 scheme 和 host，则在 Android 14 及更低版本上，您的应用可能会意外捕获已验证网域的所有路径，而不管您在 assetlinks.json 中为 Android 15 及更高版本定义的路径特定规则如何。

如果您打算在 Android 15 及更高版本中为更具体的路径使用动态应用链接，为防止应用在 Android 14 及更低版本中处理网域的所有链接，请在清单的 intent 过滤器中添加不匹配的路径。添加一个 <data> 元素，其 android:path 属性不太可能成为链接的有效路径。这可确保 intent 过滤器不会与较低版本上的所有路径匹配。

示例：

<activity
    android:name=".MainActivity"
    android:exported="true"
    ...>
    <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="http" />
        <data android:scheme="https" />
        <data android:host="www.example.com" />

        <!-- Add a non-matching path for backward compatibility -->
        <data android:path="/no_match_for_older_android_versions" />

        <uri-relative-filter-group android:allow="true">
          <data android:pathPattern="/.*"/>
        </uri-relative-filter-group>
    </intent-filter>
</activity>

通过添加 <data android:path="/no_match_for_older_android_versions" />，您可以确保在 Android 14 及更低版本上，此 intent 过滤器不会与任何传入链接匹配，同时仍允许根据 assetlinks.json 规则中的高级匹配规则，验证该网域是否可在 Android 15 及更高版本上与动态应用链接搭配使用。

如果您的清单中已有具有特定路径规则（例如 android:pathPrefix）的应用链接，并且您想在 Android 15 及更高版本上开始使用动态应用链接，则可以直接将 <uri-relative-filter-group> 元素安全地添加到现有 intent 过滤器中。

由于 Android 14 及更低版本会忽略 <uri-relative-filter-group> 元素，因此您现有的应用链接在搭载较低版本 Android 的设备上仍会像现在一样正常运行。

不过，您必须仔细考虑 Android 15 及更高版本如何评估“混合”配置：

  • 两层过滤：在 Android 15 及更高版本中，系统会将 intent 过滤器作为一个联合体进行评估。如果网址符合旧版静态 <data> 标记或 <uri-relative-filter-group> 中的宽泛规则，则会通过清单检查。网址通过此初始清单检查后，系统会应用 assetlinks.json 文件中定义的动态规则，作为第二层精细过滤。这意味着，服务器端 JSON 规则最终决定了哪些匹配的网址会实际打开应用。

混合配置示例：

<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" />
    <data android:host="www.example.com" />

    <!-- Legacy rule: Android 14 and lower use this. Android 15 and higher
         also use this. -->
    <data android:pathPrefix="/store" />

    <!--
      Dynamic rule: Android 14 and lower ignore this. Android 15 and higher
      evaluate this as a union between all paths and the configuration
      specified in the assetlinks.json file. Make sure to apply further
      refinements in the assetlinks.json file to prevent all URL paths from
      opening in the app.
    -->
    <uri-relative-filter-group android:allow="true">
        <data android:pathPrefix="/" />
    </uri-relative-filter-group>
</intent-filter>