Реалізація Universal Links для iOS-додатку

Реалізація Universal Links для iOS-додатку

Universal Links — механізм, при якому посилання вида https://example.com/product/123 відкриває додаток напрямку на потрібному екрані, мінуючи браузер. Якщо додаток не встановлено — відкривається сайт. Ніяких кастомних схем (myapp://product/123), які не працюють у Safari та блокуються корпоративними MDM.

Як це працює та де ломається

AASA-файл. На сервері за адресою https://example.com/.well-known/apple-app-site-association повинен лежати JSON без розширення файлу, з заголовком Content-Type: application/json, доступний по HTTPS без редиректів. Apple парсить цей файл при встановленні додатку та кешує на CDN — оновлення може зайняти до 24 годин.

Найчастіша помилка: сервер відає файл з редиректом з http на https, або з 301 на www-версію домена. Apple не слідує редиректам при скачуванні AASA. Перевіримо через curl -v https://example.com/.well-known/apple-app-site-association — повинна вернути 200 з правильним Content-Type.

Формат для iOS 13+ (applinks з details):

{
  "applinks": {
    "details": [{
      "appIDs": ["TEAMID.com.example.app"],
      "components": [
        { "/": "/product/*", "comment": "Сторінки товарів" },
        { "/": "/order/*" }
      ]
    }]
  }
}

App Entitlements. У Entitlements.plist потрібен com.apple.developer.associated-domains з записом applinks:example.com. Забутий entitlement — додаток просто не отримує universal link callback.

Обробка в коді. В AppDelegate або SceneDelegate реалізуємо application(_:continue:restorationHandler:) (UIKit) або onOpenURL (SwiftUI). Отримуємо NSUserActivity з типом NSUserActivityTypeBrowsingWeb та webpageURL. Парсимо шлях, визначаємо потрібний екран, будуємо навігаційний стек.

Розбір URL повинен бути стійким: webpageURL може прийти з query-параметрами, фрагментами, у верхньому регістрі. Використовуємо URLComponents замість ручного розбору строк.

Тестування. У симуляторі universal links працюють через xcrun simctl openurl booted 'https://example.com/product/123'. На реальному пристрої — через Safari (довге натиснення на посилання → «Відкрити в додатку»). Xcode → Diagnostics не покаже проблему з AASA — потрібен swcutil на Mac та Console.app для логів swcd (Apple's universal links daemon).

Сценарії та edge cases

Associated Domains Alternate Mode. Для enterprise-додатків або staging-окружень додаємо applinks:example.com?mode=developer у entitlements. У developer mode iOS не кешує AASA та запрошує файл напрямку з сервера — зручно при розробці.

Кілька доменів. Додаток може обробляти кілька доменів — просто додаємо кілька записів у entitlements. AASA потрібен на кожному домені окремо.

Посилання з email-клієнтів. Gmail та Outlook у додатках на iOS обгортають посилання через свій redirect-сервіс. Universal link у цьому випадку не срабатує — Apple бачить redirect URL, а не цільовий. Це обмеження platform-side, не баг у реалізації.

Що входить у роботу

• Налаштування AASA-файлу на сервері з потрібними паттернами шляхів
• Entitlements та конфігурація у Xcode для всіх таргетів та схем (Debug, Release, Staging)
• Реалізація обробника в SceneDelegate / AppDelegate з роутингом на потрібні екрани
• Тестування на реальних пристроях та через симулятор
• Перевірка через Apple's validator (AASA Validator)

Строки

Реалізація з кількома паттернами шляхів та інтеграцією в існуючу навігацію: 1–2 дні. З підтримкою кількох доменів та кастомною логікою роутингу — 2–3 дні. Вартість розраховується індивідуально.