SHA-256 assetlinks.json Setelah Play App Signing: Hilangkan Bilah Browser di TWA

Panduan ini membahas satu perbaikan: asosiasi antara situs Anda dan build yang dikirimkan Google Play. Panduan ini tidak membahas cara membuat TWA itu sendiri atau peninjauan aplikasi oleh Play, yang masing-masing memiliki panduan tersendiri dengan link di bawah. Setiap halaman Google yang dikutip di sini diperiksa pada 16 Oktober 2026, dan sumbernya tercantum di bagian akhir.

Mengapa bilah browser hanya muncul pada instalasi dari Play

Chrome memverifikasi TWA dengan membandingkan sertifikat yang menandatangani aplikasi terinstal dengan sidik jari yang dipublikasikan situs Anda. Jika pemeriksaan itu gagal, TWA quick start dari Chrome menyebutkan bahwa browser beralih menampilkan situs Anda sebagai Custom Tab. Peralihan itulah bilah alamat yang Anda lihat.

Dengan Play App Signing, biasanya ada dua sertifikat. Anda menandatangani bundle yang Anda upload dengan kunci upload, dan Google menandatangani APK yang dikirimkannya dengan kunci penandatanganan aplikasi. Halaman Android concepts for web developers dari Chrome menyebutkan bahwa sidik jari kunci penandatanganan aplikasi adalah sidik jari yang sesuai dengan aplikasi Anda saat diunduh dari Play Store. Karena itu, file yang hanya mencantumkan sertifikat lokal Anda akan lolos di meja Anda dan gagal di setiap ponsel yang menginstal dari Play.

Kedua kunci itu tidak selalu berbeda. Dokumentasi penandatanganan aplikasi Android menjelaskan konfigurasi di mana kunci yang sama berfungsi sebagai kunci penandatanganan aplikasi sekaligus kunci upload. Jadi, perbaikannya adalah membandingkan sertifikat yang sebenarnya, bukan menebak mana yang Anda miliki.

Temukan SHA-256 penandatanganan aplikasi di Play Console

Dokumentasi Google sendiri saat ini memberikan dua label untuk tempat yang sama. Keduanya dimulai dari Protected with Play di menu kiri aplikasi Anda.

Panduan lama, termasuk beberapa halaman Google, masih menyebut Release > Setup > App signing atau Setup > App integrity. Jika Anda hanya menemukan label tersebut, yang Anda cari adalah halaman yang sama dengan nama lamanya.

Membaca sidik jari kunci yang Anda pegang sendiri

Untuk kunci upload atau kunci debug, keytool dari Java mencetak format yang sama. Ganti file keystore dan alias dengan milik Anda, lalu salin baris berlabel SHA256:

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

Jika Anda mengelola banyak aplikasi, Google Play Developer API juga dapat mengembalikan hash sertifikat dari APK yang dibuat Play (kolom certificateSha256Hash pada daftar generated APKs). Untuk satu perbaikan saja, menyalin dari Play Console lebih sederhana.

Tulis dan sajikan assetlinks.json yang benar

File ini berupa array JSON berisi pernyataan (statement). Untuk TWA, relasinya adalah delegate_permission/common.handle_all_urls, dan targetnya adalah aplikasi Android Anda: namespace android_app, application ID Anda yang persis, dan array sidik jari SHA-256. File minimal terlihat seperti ini:

[
  {
    "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"
      ]
    }
  }
]

Ganti com.example.twa dengan application ID Anda dan setiap placeholder dengan SHA-256 lengkap yang dipisahkan titik dua. Hapus entri kedua jika Anda hanya membutuhkan instalasi dari Play untuk terverifikasi. Hanya JSON yang ketat: tanpa komentar, tanpa koma di akhir, tanpa nilai SHA-1.

Cara Google mewajibkan file disajikan

• Lokasi yang persis. https://your-domain/.well-known/assetlinks.json, dengan titik pada .well-known. example.com dan www.example.com adalah origin yang berbeda; publikasikan file di setiap origin yang dibuka aplikasi Anda. Salinan di subdirektori seperti /app/.well-known/ tidak dihitung.
• HTTP 200 secara langsung. Dokumentasi Digital Asset Links dari Google menyatakan: “Respons apa pun dari server selain HTTP 200 dianggap sebagai error, dan akan menghasilkan daftar pernyataan yang kosong.”
• Tanpa redirect. Respons 301 dan 302 tidak diikuti. Termasuk lompatan dari http ke https dan dari domain tanpa www ke www.
• HTTPS dengan rantai sertifikat yang valid, dan header Content-Type: application/json. Halaman login atau halaman error HTML yang merespons dengan 200 bukan file yang valid.

Periksa respons langsungnya dari terminal mana pun. Baris status pertama harus 200 dan content type harus JSON, tanpa 3xx sebelumnya:

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

Lebih dari satu sidik jari, lebih dari satu aplikasi

Panduan asosiasi situs dari Android menyebutkan tentang array sidik jari: “Kolom ini mendukung beberapa sidik jari, yang dapat digunakan untuk mendukung berbagai versi aplikasi Anda, seperti build debug dan produksi.” Tambahkan sidik jari upload atau debug hanya untuk build yang memang ingin Anda percayakan pada situs tersebut. Build dengan application ID yang berbeda, seperti package debug terpisah, membutuhkan pernyataan tersendiri di dalam array.

Jika Anda membuat TWA dengan Bubblewrap atau PWABuilder

Pada proyek Bubblewrap yang sudah ada, tambahkan sidik jari Play lalu buat ulang file-nya:

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

Membuat file tidak sama dengan menerapkannya: upload assetlinks.json yang baru ke situs Anda dan periksa dengan curl. bubblewrap validate memeriksa PWA Anda terhadap kriteria kualitas; perintah ini tidak memeriksa asosiasi penandatanganan, jadi lolos di sana tidak membuktikan apa pun tentang sidik jari. Instruksi PWABuilder saat ini menyampaikan hal yang sama tentang penandatanganan, “Setelah Anda mengupload file .aab, Google Play menandatangani ulang aplikasi Anda”, dan meminta Anda menambahkan sidik jari Play ke file yang dihasilkan. Koreksi sidik jari adalah perubahan pada situs Anda, bukan pada biner aplikasi.

Verifikasi asosiasinya, lalu uji instalasi dari Play

Ada empat lapisan yang terlibat: file di situs Anda, Digital Asset Links API dari Google, verifikasi link milik Android sendiri, dan browser yang meluncurkan TWA Anda. Lolos di satu lapisan tidak membuktikan lapisan berikutnya, jadi periksa secara berurutan dan akhiri di perangkat.

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

App Links Assistant di Android Studio (Tools > App Links Assistant) memeriksa asosiasi Android App Links dan manifest Anda. Alat ini berguna untuk keduanya, tetapi tidak memberi tahu apakah TWA Anda terbuka dalam layar penuh; hanya pengujian di perangkat yang bisa.

Lanjutan: status verifikasi milik Android sendiri

Pada Android 12 dan yang lebih tinggi, panduan verifikasi Android mendokumentasikan perintah berikut untuk App Links. Ganti package-nya, jalankan dua perintah pertama, tunggu beberapa menit, lalu baca statusnya:

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 menggambarkan verifikasi domain Android, bukan apakah TWA Anda terbuka tanpa UI browser. Kode 1024 atau lebih tinggi adalah error khusus verifier, bukan diagnosis SHA-256 yang salah. Untuk TWA itu sendiri, gunakan log Chrome di atas.

Sidik jari cocok, tetapi bilah tetap ada

Bilah yang terlihat tidak membuktikan SHA-256-nya salah. Jika pemeriksaan di atas mengembalikan linked: true dan bilah masih ada, periksa penyebab berikut satu per satu.

Berapa lama sampai file yang diperbaiki berlaku

Google tidak memublikasikan satu waktu tunggu pasti untuk TWA, karena ada beberapa cache yang terlibat dan masing-masing memiliki aturannya sendiri:

• Server atau CDN Anda mungkin masih menyajikan file lama. Kosongkan cache-nya (purge) dan pastikan respons langsungnya dengan curl.
• Digital Asset Links API menyatakan berapa lama setiap respons tetap valid melalui kolom maxAge.
• Android App Links memiliki waktu tersendiri. Panduan verifikasi Android menyebutkan bahwa pada Android 15 dan yang lebih tinggi, perubahan dapat memerlukan waktu hingga tujuh hari untuk mencapai semua perangkat, dan pada Android 14 dan yang lebih rendah, file biasanya diambil saat aplikasi diinstal atau diperbarui.
• Browser mungkin menyimpan status sendiri. Seorang developer melaporkan berhasil setelah menghapus data Chrome.

Jadi, kosongkan cache, pastikan file yang aktif sudah benar, lalu instal ulang dari Google Play. Pada perangkat uji, instalasi baru atau menghapus data browser dapat menyingkirkan kemungkinan status yang tersimpan di cache; itu langkah diagnostik, bukan sesuatu yang perlu diminta dari setiap pengguna. Jangan membuat rencana berdasarkan jumlah jam yang pasti.

Penolakan, peninjauan, dan pengujian tertutup

assetlinks.json yang tidak ada atau salah tidak terdokumentasi sebagai penyebab penolakan dengan sendirinya. Yang dijelaskan dokumentasi adalah peralihan ke Custom Tab dengan UI browser. Peninjauan adalah persoalan terpisah: kebijakan fungsionalitas Google Play menyatakan “Kami tidak mengizinkan aplikasi yang mengalami error, menutup paksa, macet, atau berfungsi secara tidak normal,” dan ketentuan itu berlaku apa pun status asosiasi Anda. Sidik jari yang benar menghilangkan bilah; itu tidak menyelesaikan peninjauan. Jika Anda menerima penolakan, mulailah dari kebijakan yang disebutkan dalam email.

Beberapa artikel lama menyebutkan bahwa Chrome akan membuat TWA crash jika gagal dalam pemeriksaan kualitasnya. Chromium menghapus kode QualityEnforcer tersebut pada 4 Mei 2023, jadi anggaplah saran itu sebagai sejarah, bukan gambaran tentang browser saat ini.

Jika Anda menerima penolakan, mulailah dari alasan yang tercantum dalam pemberitahuan: penolakan Broken Functionality membahas pemberitahuan fungsionalitas yang paling umum. Jangan membangun ulang TWA Anda sebagai WebView hanya karena bilah browser. Jika aplikasi Anda dibuat dengan AI builder, memublikasikan aplikasi vibe-coded di Google Play membahas rute lengkap dari proyek hingga Play.

Pertanyaan yang Sering Diajukan

Kesimpulan

Label menu Play Console adalah fakta yang paling cepat berubah di halaman ini. Jika rute di atas tidak lagi sesuai dengan Console Anda, cari Play app signing di bawah Protected with Play, atau cari "app signing" di Console.