Appy

Диплинки

Что такое Associated Domains?

Коротко

Associated Domains — возможность (capability) и entitlement Apple со списком доменов, с которыми связано приложение. Каждая запись соединяет сервис и домен, например applinks:example.com. Вместе с файлом apple-app-site-association на этом домене она включает Universal Links, общие с сайтом пароли, Handoff и App Clip.

Краткий пересказ вChatGPTClaudePerplexity

Что входит в entitlement

Entitlement — это список строк вида service:domain. Сервисов у Apple четыре. applinks отвечает за Universal Links. webcredentials позволяет приложению пользоваться паролями, сохранёнными для сайта. activitycontinuation нужен для Handoff. appclips привязывает App Clip к домену.

Домен пишут без всего лишнего: без https://, без пути, без слеша в конце и, как сказано в технической заметке Apple, без номера порта. Каждый поддомен — отдельная запись. Для всех сервисов, кроме appclips, префикс *. охватывает все поддомены, например applinks:*.example.com.

Как он связан с файлом на домене

Entitlement — половина двусторонней проверки. Приложение заявляет права на домен, а домен подтверждает это, указывая ID приложения в своём файле apple-app-site-association (AASA). Если одной из половин нет, сервис остаётся выключенным, и iOS ничего не сообщает пользователю.

Когда приложение устанавливают, система загружает файл для каждого домена из списка. Начиная с iOS 14 этот запрос уходит не на ваш сервер, а в CDN, которым управляет Apple. По документации Apple, CDN запрашивает файл в течение 24 часов, а устройства проверяют обновления примерно раз в неделю.

Настройка и проверка

В Xcode откройте у таргета вкладку Signing & Capabilities, добавьте возможность Associated Domains и впишите по одной строке на домен. Заодно это включит функцию для App ID. Для App Clip одна и та же запись нужна и в таргете приложения, и в таргете App Clip.

Если сервер недоступен из публичного интернета, добавьте к записи ?mode=developer. Тогда устройства в режиме разработчика загружают файл напрямую, и пользоваться этим могут только сборки, подписанные профилем разработки. Второй режим, managed, предназначен для устройств под управлением MDM. Перед выпуском суффикс уберите: релизная сборка должна ходить через CDN, как телефоны всех остальных. В технической заметке Apple описана и быстрая проверка на устройстве: если в настройках разработчика включить Associated Domains Development, экран Diagnostics покажет, подходит ли конкретный адрес установленному приложению.

ПримерЗаписи в entitlement
applinks:example.com, webcredentials:example.com

Попробуйте здесь

Создайте файл для своего приложения

Укажите Team ID и bundle ID или имя пакета и отпечаток подписи. Получите готовый файл apple-app-site-association или assetlinks.json, который останется разместить на сервере.

Приложения

Добавьте каждое приложение, которое должно открывать ссылки этого домена. Каждое станет записью в appIDs.

  1. Приложение 1

    10 символов, в аккаунте Apple Developer в разделе Membership details.

    Из таргета приложения в Xcode, например com.example.app.

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

Правила проверяются сверху вниз, и срабатывает первое совпадение, поэтому ставьте исключения выше общих правил. * означает любое количество символов, ? ровно один.

  1. Правило 1

    пары имя=значение через &

Другие сервисы

Ваш файл

apple-app-site-association

Пример. Введите свои данные, и он заменится.

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app"
        ],
        "components": [
          {
            "/": "/*"
          }
        ]
      }
    ]
  }
}

Создаётся в вашем браузере. Никуда не отправляется.

Где разместить файл

Где будет лежать файл

  1. Загрузите его по адресу https://ваш-домен/.well-known/apple-app-site-association, без расширения .json.
  2. Отдавайте по HTTPS с действующим сертификатом и сразу с кодом 200, без редиректов.
  3. Отправляйте заголовок Content-Type: application/json.
  4. Повторите для каждого хоста в ссылках: example.com и www.example.com — разные хосты, и каждому нужны файл и запись applinks:.
  5. CDN Apple забирает новый файл в течение 24 часов. До этого тестируйте с ?mode=developer.
Проверить домен валидатором

Не хотите размещать файлы сами? Smart-ссылки бесплатны, а на Enterprise Appy отдаёт оба файла на домене ссылок вашего приложения.

Создать бесплатную ссылку
ПодробнееПолное руководство по Universal Links для iOS и AndroidКакое место запись Associated Domains занимает в полной настройке Universal Links и App Links, шаг за шагом.

Частые вопросы

Чем Associated Domains отличается от Universal Links?

Associated Domains — это механизм, а Universal Links — одна из функций, которые на нём построены. Тот же entitlement включает общие с сайтом пароли, Handoff и App Clip. Для самих Universal Links нужна запись applinks: и приложение в блоке applinks файла на вашем домене.

Можно ли указать в Associated Domains все поддомены сразу?

Да. Поставьте перед доменом *., чтобы охватить все его поддомены, например applinks:*.example.com, и разместите файл на корневом домене. Для сервиса appclips такой префикс запрещён. Сам корневой домен он не покрывает — для него нужна отдельная запись.

Почему запись в Associated Domains не работает?

Проверьте три самые частые причины. В записи есть схема, путь или порт. Домен в записи и хост, который отдаёт файл, не совпадают: например, example.com и www.example.com. Или файл отдаётся с редиректом либо заблокирован, и CDN Apple так и не получает копию.

  • Universal Links

    Universal Links — https-ссылки Apple, которые открывают установленное iOS-приложение напрямую, а не сайт. Они доступны начиная с iOS 9. Нужны entitlement Associated Domains в приложении, например applinks:example.com, и файл apple-app-site-association на домене. Если приложения нет, та же ссылка просто открывает сайт.

  • Файл apple-app-site-association (AASA)

    apple-app-site-association (AASA) — JSON-файл по адресу https://<домен>/.well-known/apple-app-site-association, который подтверждает, что домен связан с вашим приложением. В нём перечислены ID приложений (Team ID и bundle ID) и пути, которые должны открываться в приложении. Без этого файла Universal Links не работают, и ссылки домена просто открывают сайт.

  • App Clip

    App Clip — облегчённая версия iOS-приложения, которой можно пользоваться, не устанавливая приложение целиком. Его запускает вызов: App Clip Code, QR-код, NFC-метка, ссылка в «Сообщениях» или баннер в Safari. App Clip решает одну конкретную задачу, а потом может предложить полное приложение.

Все термины глоссария

Одна ссылка на App Store, Google Play и сайт

На бесплатном тарифе Appy — 4 ссылки с QR-кодами. Каждый телефон попадает в свой магазин: App Store, Google Play, AppGallery, Galaxy Store или GetApps, а компьютер — на сайт. Без рекламы и без банковской карты.