Проверка ссылок на приложение

Если android:autoVerify="true" присутствует хотя бы в одном из фильтров интентов вашего приложения, то при его установке на устройство с Android 6.0 (уровень API 23) или более поздней версии система автоматически проверит хосты, связанные с URL в фильтрах интентов приложения. На устройствах с Android 12 и более поздними версиями ОС вы также можете запустить проверку вручную, чтобы протестировать ее логику.

Автоматическое подтверждение

Автоматическая проверка включает следующие этапы:

  1. Система проверяет все фильтры интентов, которые включают в себя следующее:
    • Действие: android.intent.action.VIEW
    • Категории: android.intent.category.BROWSABLE и android.intent.category.DEFAULT
    • Схема данных: http или https.
  2. Для каждого уникального имени хоста, указанного в фильтрах интентов, Android запрашивает у соответствующих сайтов файл протокола связи цифровых объектов по адресу https://hostname/.well-known/assetlinks.json.

После того как вы подтвердите список сайтов, которые нужно связать с приложением, и убедитесь, что размещенный файл JSON действителен, установите приложение на устройство. Подождите не менее 20 секунд, пока не завершится асинхронная проверка. Чтобы проверить, подтвердила ли система ваше приложение и задала ли правильные правила обработки ссылок, используйте следующую команду:

adb shell am start -a android.intent.action.VIEW \
    -c android.intent.category.BROWSABLE \
    -d "http://domain.name:optional_port"

Подтверждение вручную

Начиная с Android 12, вы можете вручную запустить проверку домена для приложения, установленного на устройстве. Это можно сделать независимо от того, поддерживает ли ваше приложение Android 12.

Подключитесь к интернету.

Чтобы выполнить проверку домена, тестовое устройство должно быть подключено к интернету.

Поддержка обновленного процесса подтверждения домена

Если ваше приложение предназначено для Android 12 или более поздней версии, система автоматически использует обновленный процесс подтверждения домена.

В противном случае вы можете включить обновленный процесс проверки вручную. Для этого введите в окне терминала следующую команду:

adb shell am compat enable 175408749 PACKAGE_NAME

Как сбросить статус ссылок на приложение для Android на устройстве

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

adb shell pm set-app-links --package PACKAGE_NAME 0 all

Эта команда возвращает устройство в состояние, в котором оно находилось до того, как пользователь выбрал приложения по умолчанию для доменов.

Запустите процесс подтверждения домена.

После сброса статуса ссылок на приложение для Android на устройстве можно выполнить проверку. Для этого выполните в окне терминала следующую команду:

adb shell pm verify-app-links --re-verify PACKAGE_NAME

Как посмотреть результаты проверки

Подождите, пока агент проверки завершит обработку запросов, и посмотрите результаты. Для этого выполните следующую команду:

adb shell pm get-app-links PACKAGE_NAME

Выходные данные этой команды выглядят примерно так:

com.example.pkg:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [***]
    Domain verification state:
      example.com: verified
      sub.example.com: legacy_failure
      example.net: verified
      example.org: 1026

Домены, которые успешно прошли проверку, имеют статус verified. Любой другой статус означает, что подтвердить домен не удалось. В частности, статус none означает, что агент по проверке, возможно, ещё не завершил процедуру.

Ниже перечислены возможные значения, которые может возвращать проверка домена:

none
Для этого домена ничего не записано. Подождите несколько минут, пока агент проверки не завершит запросы, связанные с подтверждением домена, а затем снова запустите процесс подтверждения домена.
verified
Домен успешно подтвержден для декларирующего приложения.
approved
Домен был одобрен принудительно, обычно с помощью команды оболочки.
denied
Домен был принудительно заблокирован, обычно с помощью команды оболочки.
migrated
Система сохранила результат предыдущего процесса, в котором использовалась устаревшая процедура подтверждения права собственности на домен.
restored
Домен был одобрен после того, как пользователь выполнил восстановление данных. Предполагается, что право собственности на домен уже подтверждено.
legacy_failure
Домен был отклонен устаревшим валидатором. Точная причина неизвестна.
system_configured
Домен был одобрен автоматически на основе конфигурации устройства.
Код ошибки 1024 или выше

Специальный код ошибки, относящийся к средству проверки устройства.

Убедитесь, что подключение к сети установлено, и запустите процесс подтверждения домена снова.

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

Другой способ получить одобрение для домена – попросить пользователя связать приложение с этим доменом.

Как проверить, одобрено ли приложение для домена

Прежде чем показывать пользователю запрос, проверьте, является ли ваше приложение обработчиком по умолчанию для доменов, указанных в элементах <intent-filter>. Запросить статус одобрения можно одним из следующих способов:

  • API DomainVerificationManager (во время выполнения).
  • Программа командной строки (на этапе тестирования).

DomainVerificationManager

В приведенном ниже фрагменте кода показано, как использовать DomainVerificationManager API:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val manager = context.getSystemService(DomainVerificationManager::class.java)
val userState = manager.getDomainVerificationUserState(context.packageName)

// Domains that have passed Android App Links verification.
val verifiedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_VERIFIED }

// Domains that haven't passed Android App Links verification but that the
// user has associated with an app.
val selectedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_SELECTED }

// All other domains.
val unapprovedDomains = userState?.hostToStateMap
    ?.filterValues { it == DomainVerificationUserState.DOMAIN_STATE_NONE }

Java

Context context = TODO("Your activity or fragment's Context");
DomainVerificationManager manager =
        context.getSystemService(DomainVerificationManager.class);
DomainVerificationUserState userState =
        manager.getDomainVerificationUserState(context.getPackageName());

Map<String, Integer> hostToStateMap = userState.getHostToStateMap();
List<String> verifiedDomains = new ArrayList<>();
List<String> selectedDomains = new ArrayList<>();
List<String> unapprovedDomains = new ArrayList<>();
for (String key : hostToStateMap.keySet()) {
    Integer stateValue = hostToStateMap.get(key);
    if (stateValue == DomainVerificationUserState.DOMAIN_STATE_VERIFIED) {
        // Domain has passed Android App Links verification.
        verifiedDomains.add(key);
    } else if (stateValue == DomainVerificationUserState.DOMAIN_STATE_SELECTED) {
        // Domain hasn't passed Android App Links verification, but the user
        // has associated it with an app.
        selectedDomains.add(key);
    } else {
        // All other domains.
        unapprovedDomains.add(key);
    }
}

Программа командной строки

При тестировании приложения во время разработки вы можете выполнить следующую команду, чтобы запросить статус подтверждения доменов, принадлежащих вашей организации:

adb shell pm get-app-links --user cur PACKAGE_NAME

В примере ниже приложение не прошло проверку для домена example.org, но пользователь 0 вручную одобрил его в системных настройках, и для этого домена не проверен ни один другой пакет.

com.example.pkg:
ID: ***
Signatures: [***]
Domain verification state:
  example.com: verified
  example.net: verified
  example.org: 1026
User 0:
  Verification link handling allowed: true
  Selection state:
    Enabled:
      example.org
    Disabled:
      example.com
      example.net

Вы также можете использовать команды оболочки, чтобы смоделировать процесс, в котором пользователь выбирает, какое приложение связано с данным доменом. Полное описание этих команд можно получить с помощью команды adb shell pm.

Укажите контекст запроса.

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

Отправка запроса

После того как пользователь поймет, что от него требуется, отправьте запрос. Для этого вызовите намерение, которое включает действие ACTION_APP_OPEN_BY_DEFAULT_SETTINGS и строку данных, соответствующую package:com.example.pkg для целевого приложения, как показано в следующем фрагменте кода:

Kotlin

val context: Context = TODO("Your activity or fragment's Context")
val intent = Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:${context.packageName}"))
context.startActivity(intent)

Java

Context context = TODO("Your activity or fragment's Context");
Intent intent = new Intent(Settings.ACTION_APP_OPEN_BY_DEFAULT_SETTINGS,
    Uri.parse("package:" + context.getPackageName()));
context.startActivity(intent);

Когда вызывается намерение, пользователи видят экран настроек Открывать по умолчанию. На этом экране есть переключатель Открывать поддерживаемые ссылки, как показано на рисунке 1.

Когда пользователь включит параметр Открывать поддерживаемые ссылки, в разделе Ссылки, которые нужно открывать в этом приложении появится набор флажков. С их помощью можно выбрать домены, которые будут связаны с вашим приложением. Чтобы добавить домены, нужно нажать Добавить ссылку, как показано на рисунке 2. Когда пользователи нажимают на ссылку в добавленном домене, она автоматически открывается в вашем приложении.

Если переключатель включен, в разделе внизу страницы появятся флажки и кнопка &quot;Добавить ссылку&quot;.
Рисунок 1. Экран системных настроек, на котором пользователи могут выбрать, какие ссылки по умолчанию открывать в вашем приложении.
Каждый флажок соответствует домену, который можно добавить. В диалоговом окне есть кнопки &quot;Отмена&quot; и &quot;Добавить&quot;.
Рисунок 2. диалоговое окно, в котором пользователи могут выбрать дополнительные домены для связи с приложением.

Открывать в приложении домены, которые оно не может проверить

Основной функцией вашего приложения может быть открытие ссылок в качестве стороннего приложения без возможности подтвердить обрабатываемые домены. В этом случае объясните пользователям, что при нажатии на веб-ссылку они не могут выбрать между собственным приложением и вашим (сторонним). Пользователям нужно вручную связать домены с вашим сторонним приложением.

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

Задержка обновления протокола связи цифровых объектов

Когда вы обновляете файл assetlinks.json на веб-сервере, время, необходимое для того, чтобы эти изменения отразились на устройствах конечных пользователей, зависит от версии ОС:

  • Android 15 (уровень API 35) и более поздние версии. Система периодически повторно проверяет домены в фоновом режиме. Изменения могут вступить в силу на всех устройствах конечных пользователей в течение семи дней из-за кеширования и запланированной повторной проверки.
  • Android 14 (уровень API 34) и более ранние версии. Система не выполняет периодическую фоновую повторную проверку. Обновления файла обычно применяются только при установке или обновлении приложения.

Обновления, связанные с тестированием

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