Universal Link ve App Link Hata Kodları: Ne Anlama Geliyorlar?

Önce gerçekten bozuk olduğundan emin olun

“Universal Links çalışmıyor” şikâyetlerinin çoğu, aslında tam da Apple’ın tasarladığı gibi davranan linkler. Apple’ın TN3155 teknik notu, uygulamanın kapalı kalması gereken durumları sıralıyor: Safari’nin adres çubuğuna yazılan ya da yapıştırılan bir URL doğrudan navigasyon sayılır, bu yüzden tarayıcıda kalır. Bulunduğunuz sayfayla aynı alan adına giden bir link de tarayıcıda kalır. Başka uygulamaların içindekiler dahil üçüncü taraf tarayıcılar ise bir linki uygulamanıza devredip devretmeyeceğine kendisi karar verir.

Bu yüzden tek bir dosyaya dokunmadan önce dürüst bir test yapın. Linki iPhone’daki Notlar’a yapıştırın ve üzerine uzun basın. Yapılandırma doğruysa menü, linki tarayıcının yanı sıra uygulamanızda açmayı da önerir. Kullanıcının orada yaptığı seçim o alan adı için varsayılan olur; dün çalışan bir linkin bugün Safari’yi açmasının sessiz nedenlerinden biri de bu.

Notlar’da uygulama seçeneği çıkmıyorsa ilişkilendirmede bir sorun var demektir; ne olduğunu da hata kodu söyler.

Kestirme yol: Appy’nin ücretsiz doğrulayıcısı

Terminali açmadan önce alan adınızı Appy’nin Universal Link doğrulayıcısına yapıştırın. Doğrulayıcı apple-app-site-association dosyanızı kendi sunucunuzdan ve Apple’ın CDN’inden ayrı ayrı çeker; Apple’daki dosyanın sizinkiyle aynı olup olmadığını anında görürsünüz. Android’in assetlinks.json dosyanızdan ne okuduğunu da Google’ın Digital Asset Links API’sine sorar. Ücretsiz, kayıt gerektirmez ve geliştiricilerinize gönderebileceğiniz tek bir sonuç sayfası verir.

Sorun dosyaların kendisindeyse Appy’nin AASA ve assetlinks.json oluşturucusu ikisini de Team ID, bundle ID ve SHA-256 parmak izinizden hazırlar. Rehberin geri kalanı her hatayı tek tek açıklıyor; doğrulayıcı bir hata işaretlediğinde neyi düzelteceğinizi tam olarak bilirsiniz.

Apple’ın CDN’inde ne olduğuna bakın

iOS 14’ten beri telefonlar apple-app-site-association dosyanızı hiçbir zaman sizin sunucunuzdan indirmiyor. Dosyayı Apple’ın CDN’inden alıyorlar, CDN de onu sizden çekiyor. Yani ilk soru “dosyam doğru mu?” değil, “Apple’da ne var?” olmalı.

curl -sD - "https://app-site-association.cdn-apple.com/a/v1/links.example.com" -o /dev/null

HTTP/1.1 404 Not Found
Apple-Failure-Reason: SWCERR00101 Bad HTTP Response: 404 Not Found
Cache-Control: max-age=3600,public

curl -v -A "AASA-Bot/1.0" https://links.example.com/.well-known/apple-app-site-association

SWCERR kodları ve çözümleri

Apple bu kodların bir listesini yayımlamıyor. Aşağıdakiler, Apple’ın CDN’inin Apple-Failure-Reason başlığında döndürdüğü mesajlar; her biri Apple Developer Forums başlıklarında ya da CDN’e kendi yaptığımız isteklerde doğrulandı.

Yolları swcutil ile kontrol edin

Dosya Apple’a ulaştıktan sonraki soru, linkinizin onunla eşleşip eşleşmediği. Mac’te swcutil, dosyanın yerel bir kopyasını gerçek bir URL’e karşı test eder; Apple mühendislerinin developer mode yerine önerdiği kontrol de bu.

sudo swcutil dl -d links.example.com

sudo swcutil verify -d links.example.com -j ./apple-app-site-association -u https://links.example.com/promo

{ s = applinks, a = ABCD123.com.example.app, d = links.example.com }:
Pattern "https://links.example.com/promo" matched.

Telefonun kendisi ne düşünüyor?

Developer Mode açıkken Ayarlar › Geliştirici › Universal Links altında bir Diagnostics ekranı bulunur: tam bir URL yazdığınızda yüklü bir uygulamanın onu sahiplenip sahiplenmediğini söyler. Resmin tamamı için bir sysdiagnose alın ve swcutil_show.txt dosyasını açın. Uygulama ID’nizi aratın ve üç satırı okuyun.

Site/Fmwk Approval satırında approved yazmalı. Unspecified ya da denied, telefonun o uygulama ve alan adı için onaylanmış bir dosyayı hiç almadığı anlamına gelir: entitlement’ı, herkese açık erişimi ve Team ID önekini kontrol edin. User Approval, kişinin bu alan adı için tarayıcıyı seçip seçmediğini gösterir. Last Checked ve Next Check, Apple’ın dosyanızı en son ne zaman indirdiğini gösterir.

“Düzelttim ama hiçbir şey değişmedi” anlarının çoğunu bu son nokta açıklıyor. Uygulama yüklendikten sonra telefon dosyayı kabaca haftada bir kontrol eder. Bir düzeltmeyi hemen test etmek için uygulamayı yeniden yükleyin. Staging için applinks girdisine ?mode=developer ekleyin: CDN’i atlar, ama yalnızca geliştirme imzalı build’lerde ve bu modu açtığınız cihazlarda.

Akılda tutmaya değer rakamlar

Apple’ın CDN’inin testlerimizde sağlam bir dosyayı tuttuğu süre

6 sa

Apple’ın CDN’inin testlerimizde sağlam bir dosyayı tuttuğu süre

bir hatayı tuttuğu süre

1 sa

bir hatayı tuttuğu süre

bir iPhone’un yüklemeden sonra dosyayı yeniden kontrol etme sıklığı

~1 hafta

bir iPhone’un yüklemeden sonra dosyayı yeniden kontrol etme sıklığı

Android’de doğrulamaya bakmadan önce beklemeniz gereken en kısa süre

20 sn

Android’de doğrulamaya bakmadan önce beklemeniz gereken en kısa süre

Android App Links: pm get-app-links’in bildirdiği durumlar

Android’de arada bir CDN yok. Cihazdaki doğrulayıcı https://<host>/.well-known/assetlinks.json dosyasını kendisi indirir ve Android 12’den beri doğrulanmamış bir link artık seçim ekranı göstermez: doğrudan tarayıcıda açılır. Eksik bir parmak izinin tıpkı “link çalışıyor, sadece uygulamamda değil” gibi görünmesinin nedeni bu.

Android 12, birden fazla host’un nasıl değerlendirildiğini de değiştirdi. Artık her host ayrı ayrı doğrulanıyor; Android 11 ve öncesinde doğrulamayı geçemeyen tek bir host hepsini düşürür. Android 15’te ise assetlinks.json’daki bir değişikliğin tüm cihazlara ulaşması yedi güne kadar sürebilir.

Doğrulamayı bilgisayarınızdan yeniden çalıştırın

adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app
adb shell pm get-app-links com.example.app

example.com: verified
sub.example.com: legacy_failure
example.org: 1026

Her durum ne anlama geliyor?

Bilgisayarınızda doğru, Play Store’da yanlış olan parmak izi

En yaygın Android hatasının barındırmayla hiçbir ilgisi yok. Play App Signing kullanıyorsanız Google uygulamanızı kendi uygulama imzalama anahtarıyla yeniden imzalar. Upload anahtarınızdan keytool ile aldığınız SHA-256, kullanıcıların telefonlarındaki değil; bu yüzden yerel build’iniz geçerken release build başarısız olur.

Parmak izini bunun yerine Play Console › Release › Setup › App signing ekranından kopyalayın. sha256_cert_fingerprints dizisi birden fazla değer alabilir; debug anahtarınızı da büyük harflerle orada tutun. Ve unutmayın: example.com’dan www.example.com’a ya da http’den https’e bir yönlendirme, Android’in linklerinizin hiçbirini doğrulamayacağı anlamına gelir.

Google’ın dosyanızdan ne okuduğunu görün

curl "https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://example.com&relation=delegate_permission/common.handle_all_urls"

Siz düzeltirken kampanyalarınız çalışmaya devam etsin

Bozuk ilişkilendirme dosyaları size yükleme kaybettirmemeli. Bir Appy linki her planda her telefonu doğru mağazaya gönderir, Huawei AppGallery dahil. Pro’da ise önce uygulamanızı dener; uygulaması zaten yüklü olan kişi doğrudan uygulamanıza gelir. AASA dosyası, SDK ya da yeni bir sürüm gerekmez. Universal Links yeniden çalıştığında aynı Appy linkini kullanmaya devam edin: basılı kodlar ve gönderiler değişmez.

Bunları da okuyun

• Universal Link doğrulayıcıAASA dosyanızı hem sunucunuzda hem Apple’ın CDN’inde, assetlinks.json’u da aynı anda kontrol eder.
• AASA ve assetlinks.json oluşturucuTeam ID, bundle ID ve SHA-256 değerlerinizden iki dosyayı da hazırlar.
• Universal Links uygulama yerine Safari’yi açıyorAynı alan adı kuralından kullanıcı tercihine, davranıştan kaynaklanan nedenler.
• Android App Links doğrulanmıyorAndroid tarafının daha ayrıntılı bir incelemesi.

Hata kodlarıyla ilgili sorular