Добавьте фильтры интентов для ссылок на приложение

Ссылки на приложения – это ссылки на контент, в которых используется схема HTTP или HTTPS и которые подтверждены Android как связанные с вашим сайтом. Чтобы зарегистрировать приложение для обработки ссылок на него, выполните следующие действия:

1. Добавьте в манифест приложения один или несколько фильтров интентов, которые указывают на домен или URL вашего сайта.
2. Добавьте autoVerify="true"attribute в элементы фильтра интентов. Это указывает системе, что нужно попытаться проверить схему и домены хоста на соответствие конфигурации 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>. Рекомендуем добавить autoVerify="true в каждый фильтр намерений, который вы хотите подтвердить.
• Элементы данных. Каждый фильтр интентов для ссылок на приложение должен содержать один или несколько элементов <data>, которые указывают схемы и форматы хостов, соответствующие подтвержденному домену вашего сайта.
• Схемы. Фильтр интентов должен включать элементы <data> для схем http и https.

• Хосты. Вы можете добавить элементы <data>, чтобы сопоставить один или несколько хостов. Используйте подстановочный знак (*), чтобы сопоставить несколько субдоменов (например, *.example.com). Система попытается проверить каждый хост по файлу assetlinks.json на вашем сайте. Обратите внимание, что любая маршрутизация на уровне пути должна обрабатываться файлом assetlinks.json (см. раздел с рекомендациями ниже).

• Несколько хостов. Если вы укажете несколько доменов хостов, система (в Android 12 и более поздних версиях) попытается проверить каждый из них. Если хотя бы один хост подтвержден, приложение становится обработчиком по умолчанию для ссылок с этого хоста. На устройствах с Android 11 и более ранними версиями ОС проверка не будет пройдена, если хотя бы один хост не подтвержден.

• Несколько фильтров интентов. Если вы хотите объявить уникальные URL (например, определенную комбинацию схемы и хоста), важно создать отдельные фильтры, поскольку несколько элементов <data> в одном фильтре интентов объединяются, чтобы учесть все варианты их комбинированных атрибутов.

Что нужно учитывать при работе с правилами фильтрации манифестов

Если вы настраиваете фильтры для динамических ссылок на приложение в Android 15 и более поздних версиях, помните, что динамические правила, объявленные в файле assetlinks.json на стороне сервера, не могут расширять область действия правил URL, которые вы статически объявляете в манифесте приложения.

Поэтому мы рекомендуем использовать следующий подход:

• В манифесте приложения задайте максимально широкую область, например указав только схему и домен.
• Для дальнейшей настройки, например маршрутизации на уровне пути, используйте правила файла assetlinks.json на стороне сервера.

При такой конфигурации вы сможете динамически добавлять новые пути ссылок на приложение в файл assetlinks.json, зная, что они будут соответствовать широкой области действия, заданной в манифесте приложения.

Поддержка ссылок на приложения для нескольких хостов

Система должна иметь возможность проверить хост, указанный в элементах данных фильтров интентов URL приложения, сопоставив его с файлами протокола связи цифровых объектов, размещенными в соответствующих веб-доменах в этом фильтре интентов. Если проверка не пройдена, система по умолчанию обрабатывает намерение стандартным способом, как описано в статье Создание ссылок на контент в приложении. Однако приложение по-прежнему можно подтвердить как обработчик по умолчанию для любого из шаблонов URL, определенных в других фильтрах интентов приложения.

Например, приложение со следующими фильтрами интентов пройдет проверку только для https://www.example.com, если файл assetlinks.json будет найден по адресу https://www.example.com/.well-known/assetlinks.json, но не https://www.example.net/.well-known/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="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 обрабатывает субдомены в фильтрах интентов как уникальные отдельные хосты. Если в фильтре интентов указано несколько хостов с разными субдоменами, необходимо опубликовать действительный файл assetlinks.json в каждом домене. Например, в следующем фильтре интентов в качестве допустимых хостов URL указаны www.example.com и mobile.example.com. Поэтому действительный файл assetlinks.json должен быть опубликован как по адресу https://www.example.com/.well-known/assetlinks.json, так и по адресу https://mobile.example.com/.well-known/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), то файл assetlinks.json нужно опубликовать в корневом имени хоста (example.com). Например, приложение со следующим фильтром интентов пройдет проверку для любого поддомена example.com (такого как foo.example.com), если файл assetlinks.json опубликован по адресу https://example.com/.well-known/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:host="*.example.com" />
    </intent-filter>
  </activity>
</application>

Проверьте, не связано ли несколько приложений с одним доменом

Если вы публикуете несколько приложений, связанных с одним доменом, то каждое из них может быть успешно подтверждено. Однако если приложения могут разрешать один и тот же хост и путь домена, как это может быть в случае с облегченной и полной версиями приложения, только приложение, которое было установлено последним, может разрешать веб-намерения для этого домена.

В таком случае проверьте, нет ли на устройстве пользователя конфликтующих приложений. Для этого у вас должна быть настроена видимость пакетов. Затем в приложении покажите диалоговое окно с результатами вызова queryIntentActivities. Пользователь может выбрать нужное приложение из списка подходящих приложений, которые появятся в диалоговом окне.

Обратная совместимость динамических ссылок на приложения для Android 14 и более ранних версий

Функции динамических ссылок на приложения, включая расширенные правила сопоставления в assetlinks.json и использование <uri-relative-filter-group>, полностью поддерживаются только на Android 15 (уровень API 35) и более поздних версиях.

В Android 14 (уровень API 34) и более ранних версиях система учитывает только атрибуты scheme и host, объявленные в элементах <data> манифеста для проверки ссылок на приложение. Правила, исключения и динамические обновления, заданные в файле assetlinks.json, не применяются.

Это означает, что если в манифесте указаны только scheme и host, приложение может неожиданно захватить все пути для подтвержденного домена на Android 14 и более ранних версиях, независимо от правил для конкретных путей, определенных в assetlinks.json для Android 15 и более поздних версий.

Резервная стратегия для более ранних версий Android, в которых не настроены ссылки на контент

Чтобы приложение не обрабатывало все ссылки для домена в Android 14 и более ранних версиях, когда вы планируете использовать динамические ссылки на приложение для более конкретных путей в Android 15 и более поздних версиях, добавьте несоответствующий путь в фильтр намерений манифеста. Добавьте элемент <data> с атрибутом android:path, который вряд ли когда-либо будет действительным путем для ваших ссылок. Это гарантирует, что фильтр интентов не будет соответствовать всем путям в более ранних версиях.

Пример:

<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 и более ранних версиях этот фильтр интентов не будет соответствовать никаким входящим ссылкам, но при этом домен по-прежнему можно будет проверить для использования с динамическими ссылками на приложения в Android 15 и более поздних версиях на основе расширенных правил сопоставления в ваших правилах assetlinks.json.

Перенос существующих ссылок на приложение

Если в манифесте уже есть ссылки на приложение с определенными правилами пути (например, android:pathPrefix) и вы хотите начать использовать динамические ссылки на приложение в Android 15 и более поздних версиях, вы можете добавить элемент <uri-relative-filter-group> непосредственно в существующие фильтры интентов.

Поскольку Android 14 и более ранние версии игнорируют элемент <uri-relative-filter-group>, существующие ссылки на приложение продолжат работать на устройствах с этими версиями Android так же, как и сейчас.

Однако вам следует внимательно изучить, как Android 15 и более поздние версии оценивают "смешанную" конфигурацию:

• Двухуровневая фильтрация. В Android 15 и более поздних версиях система оценивает фильтры интентов как объединение. URL проходит проверку манифеста, если он соответствует либо вашим устаревшим статическим тегам <data>, либо общим правилам в файле <uri-relative-filter-group>. Если URL проходит эту первоначальную проверку манифеста, система применяет динамические правила, определенные в файле assetlinks.json, в качестве второго уровня фильтрации. Это означает, что правила JSON на стороне сервера в конечном итоге определяют, какие из этих совпадающих URL-адресов фактически открывают приложение.

Пример гибридной конфигурации:

<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>