Настройте ассоциации веб-сайтов и динамические правила

Для поддержки ссылок приложений необходимо создать JSON-файл ссылок цифровых активов с именем assetlinks.json и опубликовать его в общедоступном месте на вашем веб-сайте. Этот файл публично объявляет, какие приложения авторизованы для обработки ссылок для вашего домена, и устройства Android будут загружать этот файл с вашего сервера для проверки ваших диплинков.

Для динамических ссылок приложений в Android 15+ файл assetlinks.json также используется для определения конфигурации динамических правил , таких как сопоставления шаблонов для параметров пути, фрагмента и запроса. Устройства Android под управлением Android 15 (уровень API 35) и более поздних версий с установленными сервисами Google будут периодически извлекать файл и объединять динамическую конфигурацию со статической конфигурацией в манифесте приложения.

В этом руководстве описывается, как подготовить файл assetlinks.json и опубликовать его на сайте. При желании вы можете создать файл assetlinks.json с помощью инструмента Play Deep Links или помощника Android Studio App Links. Подробнее см. в разделе «Инструменты разработчика App Links» .

Объявить ассоциации веб-сайтов

Вам необходимо опубликовать JSON-файл со ссылками на цифровые ресурсы на своём веб-сайте, чтобы указать приложения Android, связанные с веб-сайтом, и проверить URL-адреса приложений. Для идентификации связанных приложений в JSON-файле используются следующие поля:

  • package_name : идентификатор приложения , объявленный в файле build.gradle приложения.
  • sha256_cert_fingerprints : SHA256-отпечатки сертификата подписи вашего приложения. Вы можете использовать следующую команду для генерации отпечатка с помощью Java keytool:

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

  • Это поле поддерживает несколько цифровых отпечатков, которые можно использовать для поддержки разных версий вашего приложения, например, отладочных и рабочих сборок. Если вы используете функцию Play App Signing для своего приложения, цифровой отпечаток сертификата, созданный при локальном запуске keytool обычно не будет совпадать с цифровым отпечатком сертификата на устройствах пользователей. Вы можете проверить, используете ли вы функцию Play App Signing для своего приложения, в своей учётной записи разработчика Play Console в разделе Release > Setup > App signing ; если да, то на той же странице вы также найдёте правильный фрагмент JSON-кода ссылок на цифровые активы для своего приложения.

Следующий пример файла assetlinks.json предоставляет права открытия ссылки приложению Android com.example :

[{
  "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 , а приложение app2 может объявить фильтр намерений для https://example.com/videos .

Свяжите несколько веб-сайтов с одним приложением

Несколько веб-сайтов могут объявить ассоциации с одним и тем же приложением в своих файлах 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 под управлением Android 15 (уровень API 35) или более поздней версии с установленными сервисами Google будут периодически загружать этот файл с вашего сервера и объединять конфигурацию динамических правил со статической конфигурацией в манифесте приложения. Ниже приведён пример файла 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 Links добавляет новое расширение связи Digital Asset Links, называемое dynamic_app_link_components , в котором вы настраиваете свои динамические правила.
  • Динамические правила могут включать сопоставление шаблонов для параметров пути, фрагмента и запроса.
  • Вы также можете отметить любой сопоставитель шаблонов как исключенный, чтобы соответствующие URL-адреса не открывали ваше приложение.
  • В этом примере показаны примеры сопоставителей для пути ( "/" ), фрагмента ( "#" ) и параметров запроса ( "?" ), а также исключенных сопоставителей ( "exclude" ).
  • Если какие-либо поля в файле некорректны или пусты, Android отменяет динамические правила, и устройство возвращается к правилам, статически определенным в манифесте приложения.

Динамические правила могут задавать только правила, применяемые в пределах доменов, указанных в файле манифеста вашего приложения. См. ниже.

Объявить динамические правила

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

  • Сопоставление путей
    • Ключ: "/"
    • Значение: отдельная строка, совпадающая с выражением для пути URL.
  • Сопоставление фрагментов
    • Ключ: "#"
    • Значение: отдельная строка, совпадающая с выражением для фрагмента URL.
  • Сопоставление параметров запроса
    • Ключ: "?"
    • Значение: Словарь для сопоставления пар ключ/значение в параметрах URL-запроса.
    • Например, словарь {" ?", {"dl": "*", "in_app":"true "} будет соответствовать строке запроса " ?in_app=true&dl=abc ".
    • Порядок пар «ключ/значение» в словаре не обязательно должен соответствовать порядку пар в строке запроса. Кроме того, словарю не требуется сопоставлять все пары «ключ/значение» в строке запроса, но для каждой записи словаря должно быть найдено совпадение.
    • Например, словарь также будет соответствовать строке запроса « ?lang=en&in_app=true&tz=pst&dl=abc », но не будет соответствовать строке запроса « ?lang=en&tz=pst&dl=abc ».
  • Исключено
    • Ключ: «исключить»
    • Значение: необязательное значение true/false для каждого правила, определенного в dynamic_app_link_components (см. пример).

В сопоставителях шаблонов можно использовать следующие специальные символы:

  • «*» соответствует нулю или более символам до тех пор, пока в совпадающей строке не будет найден символ после подстановочного знака в шаблоне.
  • "?" соответствует любому отдельному символу
  • «?*» соответствует 1 или более символам

Других ограничений по символам для значений нет.

Заказать динамические правила

Порядок объявления правил имеет значение. Android оценивает каждое правило по порядку, пока не найдёт совпадение.

В следующем примере показано, как порядок может влиять на обработку. Первое правило соответствует всем путям ("*"), но исключает совпадения (exclude: true), то есть оно исключает все URL-адреса из списка открываемых приложений. В этом случае второе правило, разрешающее "/path1", никогда не будет выполнено.

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

Однако в следующем примере правило "/path1" объявлено первым, поэтому оно будет обработано первым и откроет приложение для URL-адреса, соответствующего "/path1". Второе правило, запрещающее открывать приложение по всем URL-адресам, будет обработано вторым, но только в том случае, если первое правило не совпадёт с первым.

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

Правильно определяйте область действия динамических правил

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

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

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

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

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

Для правильной обработки правил объявляйте только один объект dynamic_app_link_components во всех операторах для данного сайта, отношения и приложения.

  • Найдите несколько операторов для одного и того же сайта, отношения и приложения, которые объявляют объект dynamic_app_link_components.
  • Найдите несколько объектов dynamic_app_link_components, объявленных в одном операторе.

В подобных случаях Android не гарантирует, какая именно конфигурация динамических правил будет использоваться.

Совместимость динамических правил с более ранними конфигурациями App Links

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

Устройства Android под управлением Android 14 (уровень API 34 или ниже) игнорируют новые поля расширения отношений для динамических правил, тогда как устройства под управлением Android 15 и более поздних версий объединят эти правила с правилами, определенными в манифесте.

Опубликовать файл проверки JSON

Вам необходимо опубликовать свой проверочный файл JSON по следующему адресу:

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

Убедитесь в следующем:

  • Файл assetlinks.json обслуживается с типом контента application/json .
  • Файл assetlinks.json должен быть доступен по HTTPS-соединению независимо от того, объявляют ли фильтры намерений вашего приложения HTTPS в качестве схемы данных.
  • Файл assetlinks.json должен быть доступен без каких-либо перенаправлений (без перенаправлений 301 или 302).
  • Если ваши ссылки на приложения поддерживают несколько доменов хостов, необходимо опубликовать файл assetlinks.json на каждом домене. См. раздел Поддержка ссылок на приложения для нескольких хостов .
  • Не публикуйте приложение с тестовыми URL-адресами в файле манифеста, которые могут быть недоступны для всех (например, доступны только через VPN). Обходной путь в таких случаях — настроить варианты сборки так, чтобы для dev-сборок генерировался отдельный файл манифеста.

См. следующие сопутствующие руководства: