Universal Link — що це, принцип роботи та налаштування

Що таке Universal Link

Universal Link — це стандартне HTTPS-посилання виду https://example.com/page, яке при переході з iOS-пристрою відкриває встановлений додаток замість Safari. Головна відмінність від Custom URL Scheme: Universal Link не потребує реєстрації кастомної схеми (myapp://) — використовується звичайний домен. Це усуває проблему URL Scheme hijacking, коли будь-який додаток може зареєструвати ту саму схему.

Apple представила Universal Link на WWDC 2015 в рамках iOS 9. Механізм став частиною екосистеми Handoff та Spotlight: Universal Link працює не тільки в браузері, але й у результатах пошуку Spotlight, Mail, Messages та інших системних додатках. Крім того, Universal Link підтримується в watchOS та macOS — користувач може відкрити додаток на iPhone через посилання на Mac.

Ключова перевага: єдиний URL. Розробник не керує двома різними посиланнями (одним для вебу, іншим для додатка). Universal Link — це одне й те саме https-посилання. Якщо додаток встановлено — відкривається він. Якщо ні — те саме посилання відкривається в Safari як звичайна веб-сторінка. Це дає ідеальний fallback без втрати трафіку.

Як працює Universal Link

Механізм Universal Link складається з трьох етапів: перевірка асоціації, обробка посилання та fallback у браузер. Кожен етап критичний для коректної роботи. Якщо асоціацію не налаштовано, iOS обробляє посилання як звичайний перехід у Safari. Розглянемо кожен етап детально.

Перевірка асоціації (Association Verification)

При першому переході за посиланням iOS завантажує файл apple-app-site-association із сервера за адресою https://example.com/.well-known/apple-app-site-association. Файл містить JSON із ідентифікатором Team ID та Bundle ID додатка, а також список шляхів, які має відкривати додаток. iOS кешує цей файл та періодично перевіряє його актуальність (при оновленні додатка, перезавантаженні пристрою).

JSON-файл apple-app-site-association має бути доступним по HTTPS без редиректів. Сервер має віддавати Content-Type: application/json. Важливо: файл не має розширення .json — iOS шукає його строго за шляхом /.well-known/apple-app-site-association. Apple рекомендує також додати підтримку для Universal Link у CDN та перевірити, що файл не блокується robots.txt.

// apple-app-site-association — мінімальна конфігурація
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "TEAMID.com.example.app",
                "paths": ["/product/*", "/profile/*", "/search"]
            }
        ]
    }
}

appID формується як Team ID + Bundle ID (TEAMID.com.example.app). paths — масив шаблонів URL, які має обробляти додаток. Можна використовувати *, ? та нотацію NOT: ["NOT /admin/*", "/product/*"]. Шляхи перевіряються в порядку перерахування: перший збіг визначає поведінку. Якщо шлях не збігся — посилання відкривається в Safari.

Обробка посилання (Link Handling)

Після успішної верифікації асоціації iOS передає посилання додатку. Обробка виконується в AppDelegate через метод application(_:continue:restorationHandler:) для NSUserActivity, або в SceneDelegate через scene(_:continue:). Розробник отримує об'єкт NSUserActivity з типом NSUserActivityTypeBrowsingWeb, витягує URL та навігує на відповідний екран.

// Обробка Universal Link в AppDelegate
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping UIUserActivityRestorationHandler
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL
    else { return false }

    // Навігація на екран згідно з URL
    DeepLinkRouter.navigate(to: url)
    return true
}

DeepLinkRouter у прикладі вище — кастомний клас, який парсить URL та викликає відповідний координатор навігації. Для SwiftUI обробка виконується через метод onOpenURL або модифікатор environment(\.openURL). Важливо обробляти не тільки foreground-запуск, але й випадок, коли додаток не запущено (cold start): Universal Link у цьому випадку відкриває додаток через launch options.

Fallback у браузер (Browser Fallback)

Якщо додаток не встановлено, iOS автоматично відкриває Universal Link у Safari. Це ключова відмінність від Custom URL Scheme: користувач не бачить помилку. Fallback — це стандартна веб-сторінка того самого домену. Розробник може розмістити на цій сторінці посилання на App Store, інформацію про продукт або альтернативний контент.

Важливо: fallback не можна кастомізувати на рівні iOS. iOS просто відкриває URL у Safari. Щоб показувати різний контент для користувачів із встановленим та невстановленим додатком, використовуйте Smart App Banner (мета-тег для Safari, що пропонує відкрити додаток) або JavaScript-детекцію встановлення додатка. Apple також надає SKAdNetwork для атрибуції встановлень через Universal Link.

Universal Link vs Deep Link

Universal Link та традиційний Deep Link (Custom URL Scheme) вирішують одне завдання, але принципово різняться за архітектурою та безпекою. Custom URL Scheme — кастомний протокол (myapp://), який реєструється в Info.plist. Будь-який додаток може зареєструвати ту саму схему (myapp://), і iOS не може визначити, який із них «справжній». Це називається URL Scheme hijacking.

Universal Link вирішує проблему hijacking через верифікацію домену. Тільки власник домену може розмістити apple-app-site-association на своєму сервері, підтвердивши зв'язок із конкретним Bundle ID. Два додатки не можуть зареєструвати один Universal Link: якщо виникає конфлікт, iOS надає пріоритет додатку, встановленому останнім, або відкриває Safari.

Інша відмінність: Fallback. Custom URL Scheme не має fallback — якщо додаток не встановлено, браузер показує помилку. Universal Link відкриває сайт. Єдиний URL означає, що SEO-цінність посилання зберігається (посилання індексує Google), а користувач із будь-яким пристроєм отримує релевантний контент. Universal Link — еволюційний крок від deep link до unified link.

Налаштування Universal Link

Налаштування Universal Link включає серверну та клієнтську частини. Серверна — розміщення файлу apple-app-site-association за адресою https://domain/.well-known/apple-app-site-association. Клієнтська — реєстрація домену в Associated Domains у Xcode (Capabilities → Associated Domains → applinks:example.com). Після цього додаток автоматично отримує всі Universal Link для вказаного домену.

Кроки налаштування:

1. Створити apple-app-site-association із правильним appID (TeamID.BundleID) та paths
2. Розмістити файл на сервері за шляхом /.well-known/ без розширення .json
3. Перевірити доступність: curl https://domain/.well-known/apple-app-site-association
4. Додати домен в Associated Domains (Xcode Capabilities)
5. Реалізувати обробку через NSUserActivity (AppDelegate або SceneDelegate)
6. Протестувати на реальному пристрої (симулятор не перевіряє асоціацію)

Налагодження Universal Link — часта проблема iOS-розробників. Основні причини несправних посилань: файл apple-app-site-association недоступний по HTTPS, невірний appID, Content-Type не application/json, редирект із /.well-known шляху, кешування старої версії файлу (скидання через Settings → Developer → Associated Domains Development). Apple надає інструмент «Validation Checker» у Apple Developer Console для тестування асоціації.

Branch та інші MMP-платформи спрощують налаштування Universal Link: вони генерують apple-app-site-association автоматично та хостять його на своєму домені. Розробнику достатньо додати Branch домен в Associated Domains та інтегрувати SDK. Це особливо зручно для стартапів, які не мають власної серверної інфраструктури для хостингу AASA-файлу.

Обмеження та сумісність

Universal Link має кілька обмежень. Перше: файл apple-app-site-association має бути доступним строго по HTTPS (HTTP не підтримується). Друге: посилання має вести на той самий домен, який вказано в Associated Domains. Міждоменні Universal Link не працюють — для кожного домену потрібен окремий запис у Capabilities та окремий AASA-файл. Третє: Universal Link не працює в WKWebView — тільки в Safari та системних компонентах.

Сумісність: iOS 9.0+ (Universal Link), watchOS 6.0+ (Handoff Universal Link), macOS 10.15+ (Catalyst та Mac додатки). У старіших версіях iOS посилання відкривається в Safari. Це означає, що на iOS 8 (менше 1% пристроїв) Universal Link не спрацює. Рекомендується підтримувати й Custom URL Scheme як fallback для старих пристроїв, якщо аудиторія включає користувачів із застарілими версіями.

iOS 16+ зміни: Apple покращила обробку Universal Link для SwiftUI. З'явився новий модифікатор environment(\.openURL) із можливістю відкладеної обробки. iOS 16 також дозволяє відкривати Universal Link у додатку навіть через SFSafariViewController. Для користувачів iOS 16 рекомендується повністю переходити на SwiftUI-обробку Universal Link, залишивши AppDelegate-код тільки для зворотної сумісності.