Universal Link — nedir, çalışma prensibi ve kurulumu

Universal Link Nedir

Universal Link, bir iOS cihazında dokunulduğunda Safari yerine yüklü uygulamayı açan https://example.com/page gibi standart bir HTTPS bağlantısıdır. Custom URL Scheme'den temel farkı: Universal Link, özel bir şema (myapp://) kaydı gerektirmez — normal bir alan adı kullanır. Bu, herhangi bir uygulamanın aynı şemayı kaydedebildiği URL Şeması Gasplama (URL Scheme hijacking) sorununu ortadan kaldırır.

Apple, Universal Link'i WWDC 2015'te iOS 9'un bir parçası olarak tanıttı. Mekanizma, Handoff ve Spotlight ekosisteminin bir parçası haline geldi: Universal Link yalnızca tarayıcıda değil, aynı zamanda Spotlight arama sonuçlarında, Mail, Messages ve diğer sistem uygulamalarında da çalışır. Ayrıca Universal Link, watchOS ve macOS'ta da desteklenir — kullanıcı Mac'teki bir bağlantı aracılığıyla iPhone'da bir uygulamayı açabilir.

Temel avantaj: Tekil URL. Geliştirici iki farklı bağlantıyı (biri web için, diğeri uygulama için) yönetmez. Universal Link aynı https bağlantısıdır. Uygulama yüklüyse — uygulama açılır. Değilse — aynı bağlantı Safari'de normal bir web sayfası olarak açılır. Bu, trafik kaybı olmadan ideal bir yedekleme (fallback) sağlar.

Universal Link Nasıl Çalışır

Universal Link mekanizması üç aşamadan oluşur: ilişkilendirme doğrulaması, bağlantı işleme ve tarayıcı yedeklemesi. Her aşama doğru çalışma için kritiktir. İlişkilendirme yapılandırılmamışsa, iOS bağlantıyı Safari'ye normal bir yönlendirme olarak işler. Her aşamayı ayrıntılı olarak inceleyelim.

İlişkilendirme Doğrulaması (Association Verification)

Bir bağlantıya ilk dokunulduğunda, iOS sunucudan https://example.com/.well-known/apple-app-site-association adresindeki apple-app-site-association dosyasını indirir. Dosya, uygulamanın Team ID ve Bundle ID'sini içeren JSON'u ve uygulamanın açması gereken yolların bir listesini içerir. iOS bu dosyayı önbelleğe alır ve periyodik olarak güncelliğini kontrol eder (uygulama güncellemesi, cihaz yeniden başlatmasında).

JSON dosyası apple-app-site-association, yönlendirme olmadan HTTPS üzerinden erişilebilir olmalıdır. Sunucu Content-Type: application/json döndürmelidir. Önemli: dosyanın .json uzantısı yoktur — iOS onu kesinlikle /.well-known/apple-app-site-association konumunda arar. Apple ayrıca CDN'de Universal Link desteği eklenmesini ve dosyanın robots.txt tarafından engellenmediğinin kontrol edilmesini önerir.

// apple-app-site-association — minimum yapılandırma
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "TEAMID.com.example.app",
                "paths": ["/product/*", "/profile/*", "/search"]
            }
        ]
    }
}

appID, Team ID + Bundle ID (TEAMID.com.example.app) olarak oluşturulur. paths, uygulamanın işlemesi gereken URL kalıplarının bir dizisidir. *, ? ve NOT gösterimi kullanılabilir: ["NOT /admin/*", "/product/*"]. Yollar sıralama sırasına göre kontrol edilir: ilk eşleşme davranışı belirler. Yol eşleşmezse — bağlantı Safari'de açılır.

Bağlantı İşleme (Link Handling)

Başarılı ilişkilendirme doğrulamasından sonra, iOS bağlantıyı uygulamaya iletir. İşleme, NSUserActivity için AppDelegate'te application(_:continue:restorationHandler:) yöntemi veya SceneDelegate'te scene(_:continue:) aracılığıyla gerçekleştirilir. Geliştirici, NSUserActivityTypeBrowsingWeb türünde bir NSUserActivity nesnesi alır, URL'yi çıkarır ve ilgili ekrana gider.

// AppDelegate'te Universal Link işleme
func application(
    _ application: UIApplication,
    continue userActivity: NSUserActivity,
    restorationHandler: @escaping UIUserActivityRestorationHandler
) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL
    else { return false }

    // URL'ye göre ekrana git
    DeepLinkRouter.navigate(to: url)
    return true
}

Yukarıdaki örnekte DeepLinkRouter, URL'yi ayrıştıran ve ilgili navigasyon koordinatörünü çağıran özel bir sınıftır. SwiftUI için işleme, onOpenURL yöntemi veya environment(\.openURL) değiştiricisi aracılığıyla yapılır. Yalnızca ön plan başlatmayı değil, aynı zamanda uygulamanın çalışmadığı durumu (soğuk başlatma) da işlemek önemlidir: bu durumda Universal Link, başlatma seçenekleri aracılığıyla uygulamayı açar.

Tarayıcı Yedeklemesi (Browser Fallback)

Uygulama yüklü değilse, iOS otomatik olarak Universal Link'i Safari'de açar. Bu, Custom URL Scheme'den temel bir farktır: kullanıcı bir hata görmez. Yedekleme, aynı alanın standart web sayfasıdır. Geliştirici bu sayfaya App Store bağlantısı, ürün bilgileri veya alternatif içerik yerleştirebilir.

Önemli: yedekleme iOS düzeyinde özelleştirilemez. iOS yalnızca Safari'de URL'yi açar. Uygulaması yüklü ve yüklü olmayan kullanıcılar için farklı içerik göstermek için Smart App Banner (uygulamayı açmayı öneren Safari meta etiketi) veya JavaScript kurulum algılamasını kullanın. Apple ayrıca Universal Link aracılığıyla kurulum atıfı için SKAdNetwork sağlar.

Universal Link vs Deep Link

Universal Link ve geleneksel Deep Link (Custom URL Scheme) aynı sorunu çözer, ancak mimari ve güvenlik açısından temelde farklılık gösterir. Custom URL Scheme, Info.plist'te kayıtlı özel bir protokoldür (myapp://). Herhangi bir uygulama aynı şemayı (myapp://) kaydedebilir ve iOS hangisinin “gerçek” olduğunu belirleyemez. Buna URL Şeması Gasplama denir.

Universal Link, alan doğrulaması yoluyla gasplama sorununu çözer. Yalnızca alan sahibi, sunucusuna apple-app-site-association yerleştirerek belirli bir Bundle ID ile bağlantıyı onaylayabilir. İki uygulama aynı Universal Link'i kaydedemez: bir çakışma olursa, iOS en son yüklenen uygulamaya öncelik verir veya Safari'yi açar.

Başka bir fark: Yedekleme. Custom URL Scheme'nin yedeklemesi yoktur — uygulama yüklü değilse tarayıcı bir hata gösterir. Universal Link web sitesini açar. Tekil URL, bağlantının SEO değerinin korunduğu (Google bağlantıyı indeksler) ve herhangi bir cihazdaki kullanıcının ilgili içeriği aldığı anlamına gelir. Universal Link, deep link'ten birleşik linke evrimsel bir adımdır.

Universal Link Kurulumu

Kurulum, sunucu tarafı ve istemci tarafı olmak üzere iki kısımdan oluşur. Sunucu tarafı — apple-app-site-association dosyasını https://domain/.well-known/apple-app-site-association konumuna yerleştirmek. İstemci tarafı — Xcode'da Associated Domains'e alan adını kaydetmek (Capabilities → Associated Domains → applinks:example.com). Bundan sonra uygulama, belirtilen alan için tüm Universal Link'leri otomatik olarak alır.

Kurulum adımları:

1. Oluşturun — doğru appID (TeamID.BundleID) ve paths ile apple-app-site-association oluşturun
2. Yerleştirin — dosyayı sunucuda .json uzantısı olmadan /.well-known/ konumuna yerleştirin
3. Doğrulayın — curl https://domain/.well-known/apple-app-site-association ile erişilebilirliği kontrol edin
4. Ekleyin — Xcode Capabilities'de Associated Domains'e alan adını ekleyin
5. Uygulayın — NSUserActivity (AppDelegate veya SceneDelegate) aracılığıyla işlemeyi uygulayın
6. Test edin — gerçek bir cihazda test edin (simülatör ilişkilendirmeyi doğrulamaz)

Hata ayıklama, iOS geliştiricileri için yaygın bir baş ağrısıdır. Çalışmayan bağlantıların ana nedenleri: apple-app-site-association dosyasına HTTPS üzerinden erişilemiyor, yanlış appID, Content-Type application/json değil, /.well-known yolundan yönlendirme, eski sürümün önbelleğe alınması (Settings → Developer → Associated Domains Development ile sıfırlama). Apple, ilişkilendirmeyi test etmek için Apple Developer Console'da Validation Checker aracı sağlar.

Branch ve diğer MMP platformları Universal Link kurulumunu basitleştirir: apple-app-site-association'ı otomatik olarak oluşturur ve kendi alanlarında barındırır. Geliştiricinin yalnızca Branch alanını Associated Domains'e eklemesi ve SDK'yı entegre etmesi yeterlidir. Bu, özellikle AASA dosyasını barındırmak için kendi sunucu altyapısı olmayan startuplar için uygundur.

Sınırlamalar ve Uyumluluk

Universal Link'in birkaç sınırlaması vardır. Birincisi: apple-app-site-association dosyası kesinlikle HTTPS üzerinden erişilebilir olmalıdır (HTTP desteklenmez). İkincisi: bağlantı, Associated Domains'de belirtilen aynı alan adını göstermelidir. Çapraz alan Universal Link'leri çalışmaz — her alan için Capabilities'de ayrı bir giriş ve ayrı bir AASA dosyası gerekir. Üçüncüsü: Universal Link WKWebView'de çalışmaz — yalnızca Safari ve sistem bileşenlerinde çalışır.

Uyumluluk: iOS 9.0+ (Universal Link), watchOS 6.0+ (Handoff Universal Link), macOS 10.15+ (Catalyst ve Mac uygulamaları). Daha eski iOS sürümlerinde bağlantı Safari'de açılır. Bu, iOS 8'de (cihazların %1'inden azı) Universal Link'in çalışmayacağı anlamına gelir. Hedef kitleniz eski sürüm kullanıcılarını içeriyorsa, eski cihazlar için yedek olarak Custom URL Scheme'in de desteklenmesi önerilir.

iOS 16+ değişiklikleri: Apple, SwiftUI için Universal Link işlemeyi iyileştirdi. Gecikmeli işleme kapasitesine sahip yeni bir environment(\.openURL) değiştiricisi tanıtıldı. iOS 16, SFSafariViewController aracılığıyla bile uygulamada Universal Link'lerin açılmasına izin verir. iOS 16 kullanıcıları için tamamen SwiftUI Universal Link işlemeye geçilmesi ve AppDelegate kodunun yalnızca geriye dönük uyumluluk için tutulması önerilir.