Play App Signing Sonrası assetlinks.json SHA-256: TWA Tarayıcı Çubuğunu Düzeltin

Bu rehber tek bir onarımı ele alır: web siteniz ile Google Play'in dağıttığı derleme arasındaki ilişkilendirme. TWA'nın kendisini oluşturmayı veya Play'in uygulamayı incelemesini kapsamaz; bunların aşağıda bağlantısı verilen kendi rehberleri vardır. Burada alıntılanan her Google sayfası 16 Ekim 2026 tarihinde kontrol edildi ve kaynaklar sonda listelenmiştir.

Tarayıcı çubuğu neden yalnızca Play kurulumunda görünür

Chrome bir TWA'yı, kurulu uygulamayı imzalayan sertifikayı web sitenizin yayınladığı parmak izleriyle karşılaştırarak doğrular. Bu kontrol başarısız olduğunda Chrome'un TWA hızlı başlangıç rehberi, tarayıcının sitenizi bir Custom Tab olarak göstermeye geri döndüğünü söyler. Gördüğünüz adres çubuğu bu geri dönüştür.

Play App Signing ile genellikle iki sertifika vardır. Yüklediğiniz paketi yükleme anahtarınızla siz imzalarsınız, Google ise dağıttığı APK'ları uygulama imzalama anahtarıyla imzalar. Chrome'un web geliştiricileri için Android kavramları sayfası, uygulamanız Play Store'dan indirildiğinde ona karşılık gelen parmak izinin uygulama imzalama anahtarının parmak izi olduğunu söyler. Bu nedenle yalnızca yerel sertifikanızı listeleyen bir dosya masanızdaki cihazda geçer ve Play'den kurulan her telefonda başarısız olur.

İki anahtar her zaman farklı değildir. Android'in uygulama imzalama belgeleri, aynı anahtarın hem uygulama imzalama anahtarı hem de yükleme anahtarı olarak kullanıldığı kurulumları anlatır. Yani çözüm, hangisine sahip olduğunuzu varsaymak değil, gerçek sertifikaları karşılaştırmaktır.

Uygulama imzalama SHA-256'sını Play Console'da bulun

Google'ın kendi belgeleri şu anda aynı yer için iki farklı etiket veriyor. İkisi de uygulamanızın sol menüsündeki Protected with Play bölümünden başlar.

Bazı Google sayfaları da dahil olmak üzere eski rehberler hâlâ Release > Setup > App signing veya Setup > App integrity der. Yalnızca bu etiketleri buluyorsanız, aynı sayfaya eski adıyla bakıyorsunuz demektir.

Kendi elinizdeki bir anahtarın parmak izini okuyun

Yükleme anahtarınız veya bir debug anahtarı için Java'nın keytool aracı aynı biçimi yazdırır. Anahtar deposu dosyasını ve takma adı (alias) kendinizinkilerle değiştirin, ardından SHA256 etiketli satırı kopyalayın:

keytool -list -v -keystore my-upload-key.jks -alias upload

Çok sayıda uygulama yönetiyorsanız Google Play Developer API, Play'in oluşturduğu APK'ların sertifika hash değerini de döndürebilir (oluşturulan APK listesindeki certificateSha256Hash alanı). Tek bir düzeltme için Play Console'dan kopyalamak daha basittir.

Doğru bir assetlinks.json yazın ve sunun

Dosya, ifadelerden (statement) oluşan bir JSON dizisidir. Bir TWA için ilişki (relation) delegate_permission/common.handle_all_urls olur, hedef ise Android uygulamanızdır: android_app ad alanı, birebir uygulama kimliğiniz ve SHA-256 parmak izlerinden oluşan bir dizi. En sade dosya şöyle görünür:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

com.example.twa değerini uygulama kimliğinizle, her yer tutucuyu da iki nokta üst üste ile ayrılmış tam bir SHA-256 ile değiştirin. Yalnızca Play kurulumlarının doğrulanması gerekiyorsa ikinci girişi silin. Yalnızca katı JSON kullanın: yorum yok, sondaki virgül yok, SHA-1 değeri yok.

Google dosyanın nasıl sunulmasını ister

• Birebir konum. https://your-domain/.well-known/assetlinks.json, .well-known içindeki nokta dahil. example.com ve www.example.com farklı origin'lerdir; dosyayı uygulamanızın açtığı her birinde yayınlayın. /app/.well-known/ gibi bir alt dizindeki kopya sayılmaz.
• Doğrudan bir HTTP 200. Google'ın Digital Asset Links belgeleri şöyle der: “Sunucudan gelen HTTP 200 dışındaki her yanıt hata olarak değerlendirilir ve boş bir ifade listesiyle sonuçlanır.”
• Yönlendirme yok. 301 ve 302 yanıtları izlenmez. Buna http'den https'ye bir geçiş ve çıplak alan adından www'ye bir geçiş de dahildir.
• Geçerli bir sertifika zinciriyle HTTPS ve Content-Type: application/json başlığı. 200 ile yanıt veren bir giriş sayfası veya HTML hata sayfası geçerli bir dosya değildir.

Canlı yanıtı herhangi bir terminalden kontrol edin. İlk durum satırı 200 olmalı, içerik türü JSON olmalı ve öncesinde hiçbir 3xx bulunmamalıdır:

curl -sI https://example.com/.well-known/assetlinks.json

Birden fazla parmak izi, birden fazla uygulama

Android'in web sitesi ilişkilendirme rehberi parmak izi dizisi için şöyle der: “Bu alan birden fazla parmak izini destekler; bunlar, uygulamanızın debug ve üretim derlemeleri gibi farklı sürümlerini desteklemek için kullanılabilir.” Yükleme veya debug parmak izini yalnızca o web sitesinin gerçekten güvenmesini istediğiniz derlemeler için ekleyin. Ayrı bir debug paketi gibi farklı bir uygulama kimliğine sahip derleme, dizide kendi ifadesine ihtiyaç duyar.

TWA'yı Bubblewrap veya PWABuilder ile oluşturduysanız

Mevcut bir Bubblewrap projesinde Play'in parmak izini ekleyin ve dosyayı yeniden oluşturun:

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

Dosyayı oluşturmak, onu yayına almak demek değildir: yeni assetlinks.json dosyasını web sitenize yükleyin ve curl ile kontrol edin. bubblewrap validate PWA'nızı kalite ölçütlerine göre kontrol eder; imzalama ilişkilendirmesini kontrol etmez, bu yüzden oradan geçmek parmak izi hakkında hiçbir şey kanıtlamaz. PWABuilder'ın güncel talimatları da imzalama konusunda aynı noktaya değinir, “.aab dosyanızı yükledikten sonra Google Play uygulamanızı yeniden imzalar”, ve Play'in parmak izini oluşturulan dosyaya eklemenizi söyler. Parmak izi düzeltmesi uygulama ikili dosyasında değil, web sitenizde yapılan bir değişikliktir.

İlişkilendirmeyi doğrulayın, sonra Play kurulumunu test edin

İşin içinde dört katman vardır: web sitenizdeki dosya, Google'ın Digital Asset Links API'si, Android'in kendi bağlantı doğrulaması ve TWA'nızı başlatan tarayıcı. Bir katmanı geçmek bir sonrakini kanıtlamaz; bu yüzden bunları sırayla kontrol edin ve cihazda bitirin.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

Android Studio'nun App Links Assistant aracı (Tools > App Links Assistant), Android App Links ilişkilendirmesini ve manifest dosyanızı kontrol eder. Bunlar için faydalıdır, ancak TWA'nızın tam ekran açılıp açılmadığını söylemez; bunu yalnızca cihaz testi söyler.

İleri düzey: Android'in kendi doğrulama durumu

Android 12 ve üzerinde Android'in doğrulama rehberi, App Links için şu komutları belgeler. Paketi değiştirin, ilk ikisini çalıştırın, birkaç dakika bekleyin, ardından durumu okuyun:

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified, TWA'nızın tarayıcı arayüzü olmadan açılıp açılmadığını değil, Android'in alan adı doğrulamasını ifade eder. 1024 veya daha yüksek kodlar doğrulayıcıya özgü hatalardır, yanlış bir SHA-256'nın teşhisi değildir. TWA'nın kendisi için yukarıdaki Chrome günlüğünü kullanın.

Parmak izi eşleşiyor ama çubuk kalıyor

Görünür bir çubuk, SHA-256'nın yanlış olduğunu kanıtlamaz. Yukarıdaki kontrol linked: true döndürüyor ve çubuk hâlâ duruyorsa, şu nedenleri sırayla inceleyin.

Düzeltilen dosyanın etkili olması ne kadar sürer

Google, TWA'lar için tek bir bekleme süresi yayınlamaz, çünkü işin içinde birkaç önbellek vardır ve her birinin kendi kuralları bulunur:

• Sunucunuz veya CDN'iniz eski dosyayı sunmaya devam ediyor olabilir. Önbelleği temizleyin ve canlı yanıtı curl ile doğrulayın.
• Digital Asset Links API, her yanıtın ne kadar süre geçerli kalacağını maxAge alanında belirtir.
• Android App Links ayrı bir zamanlamaya sahiptir. Android'in doğrulama rehberi, Android 15 ve üzerinde değişikliklerin tüm cihazlara ulaşmasının yedi güne kadar sürebileceğini, Android 14 ve altında ise dosyanın genellikle uygulama kurulduğunda veya güncellendiğinde alındığını söyler.
• Tarayıcı kendi durumunu saklıyor olabilir. Bir geliştirici, Chrome'un verilerini temizledikten sonra sorunun çözüldüğünü bildirdi.

Yani önbelleği temizleyin, canlı dosyayı doğrulayın ve uygulamayı Google Play'den yeniden kurun. Bir test cihazında yeni bir kurulum veya tarayıcı verilerini temizlemek önbellekteki durumu devre dışı bırakmanıza yardımcı olabilir; bu bir teşhis adımıdır, her kullanıcıdan yapmasını isteyeceğiniz bir şey değildir. Sabit bir saat sayısına göre plan yapmayın.

Ret, inceleme ve kapalı test

Eksik veya yanlış bir assetlinks.json, tek başına bir ret nedeni olarak belgelenmemiştir. Belgelerin anlattığı şey, tarayıcı arayüzlü bir Custom Tab'e geri dönüştür. İnceleme ayrı bir konudur: Google Play'in işlevsellik politikası “Çöken, zorla kapanan, donan veya başka şekilde anormal çalışan uygulamalara izin vermiyoruz” der ve bu, ilişkilendirme durumunuz ne olursa olsun geçerlidir. Doğru bir parmak izi çubuğu düzeltir; incelemeyi sonuçlandırmaz. Bir ret aldıysanız, e-postada adı geçen politikadan başlayın.

Bazı eski makaleler, Chrome'un kalite kontrollerini geçemeyen bir TWA'yı çökerteceğini söyler. Chromium bu QualityEnforcer kodunu 4 Mayıs 2023'te kaldırdı; bu yüzden o tavsiyeyi bugünün tarayıcılarının bir tarifi olarak değil, tarihsel bir bilgi olarak değerlendirin.

Bir ret aldıysanız, bildirimdeki gerekçeden yola çıkın: Broken Functionality reddi rehberi en sık görülen işlevsellik bildirimini adım adım anlatır. TWA'nızı yalnızca bir tarayıcı çubuğu yüzünden WebView olarak yeniden oluşturmayın. Uygulamanız bir yapay zeka oluşturucusundan çıktıysa, vibe coding ile yapılan bir uygulamayı Google Play'de yayınlama rehberi projeden Play'e kadar tüm yolu kapsar.

Sıkça Sorulan Sorular

Sonuç

Play Console menü etiketleri bu sayfadaki en hızlı değişen bilgidir. Yukarıdaki yollar Console'unuzla artık eşleşmiyorsa, Protected with Play altında Play app signing sayfasını arayın veya Console'da app signing araması yapın.