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 в този случай отваря приложението чрез опциите за стартиране.

Fallback към браузър (Browser Fallback)

Ако приложението не е инсталирано, iOS автоматично отваря Universal Link в Safari. Това е ключовата разлика от Custom URL Scheme: потребителят не вижда грешка. Fallback е стандартна уеб страница на същия домейн. Разработчикът може да постави на тази страница връзка към App Store, информация за продукта или алтернативно съдържание.

Важно: fallback не може да бъде персонализиран на ниво iOS. iOS просто отваря URL в Safari. За да показвате различно съдържание на потребители с инсталирано и неинсталирано приложение, използвайте Smart App Banner (meta таг за 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 се запази само за обратна съвместимост.