Mengonfigurasi keterkaitan situs dan aturan dinamis

Untuk mendukung Link Aplikasi, Anda harus membuat file JSON Digital Asset Links bernama assetlinks.json dan memublikasikannya di lokasi yang dikenal di situs Anda. File ini secara publik mendeklarasikan aplikasi mana yang diizinkan untuk menangani link untuk domain Anda, dan perangkat Android akan mengambil file ini dari server Anda untuk memverifikasi deep link Anda.

Untuk Link Aplikasi dinamis di Android 15+, file assetlinks.json juga merupakan tempat Anda menentukan konfigurasi aturan dinamis, seperti pencocok pola untuk parameter jalur, fragmen, dan kueri. Perangkat Android yang menjalankan Android 15 (level API 35) atau yang lebih baru yang telah menginstal layanan Google akan mengambil file secara berkala dan menggabungkan konfigurasi dinamis Anda dengan konfigurasi statis dalam manifes aplikasi.

Panduan ini menjelaskan cara menyiapkan file assetlinks.json dan memublikasikannya di situs Anda. Jika mau, Anda dapat membuat file assetlinks.json dari alat Deep Link Play atau Asisten Link Aplikasi Android Studio. Untuk mengetahui informasi selengkapnya, lihat Alat developer Link Aplikasi.

Mendeklarasikan pengaitan situs web

Anda harus memublikasikan file JSON Digital Asset Links di situs Anda untuk menunjukkan aplikasi Android yang terkait dengan situs dan memverifikasi intent URL aplikasi. File JSON menggunakan kolom berikut untuk mengidentifikasi aplikasi terkait:

  • package_name: ID aplikasi yang dideklarasikan dalam file build.gradle aplikasi.
  • sha256_cert_fingerprints: Sidik jari SHA256 dari sertifikat penandatanganan aplikasi Anda. Anda dapat menggunakan perintah berikut untuk membuat sidik jari menggunakan keytool Java:

keytool -list -v -keystore my-release-key.keystore

  • Kolom ini mendukung beberapa sidik jari, yang dapat digunakan untuk mendukung berbagai versi aplikasi Anda, seperti build debug dan produksi. Jika Anda menggunakan Penandatanganan Aplikasi Play untuk aplikasi Anda, sidik jari sertifikat yang dihasilkan dengan menjalankan keytool secara lokal biasanya tidak akan cocok dengan sidik jari yang ada di perangkat pengguna. Anda dapat memverifikasi apakah Anda menggunakan Penandatanganan Aplikasi Play untuk aplikasi Anda di akun developer Konsol Play di bagian Release > Setup > App signing; jika ya, Anda juga akan menemukan cuplikan JSON Digital Asset Links yang tepat untuk aplikasi Anda di halaman yang sama.

Contoh file assetlinks.json berikut memberikan hak pembukaan link ke aplikasi Android com.example:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Mengaitkan situs dengan beberapa aplikasi

Situs dapat mendeklarasikan pengaitan dengan beberapa aplikasi dalam file assetlinks.json yang sama. Daftar file berikut menunjukkan contoh file pernyataan yang mendeklarasikan pengaitan dengan dua aplikasi, secara terpisah, dan berada di https://www.example.com/.well-known/assetlinks.json:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.puppies.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
  },
  {
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.monkeys.app",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Aplikasi berbeda dapat menangani link untuk resource yang berbeda dengan host web yang sama. Misalnya, app1 dapat mendeklarasikan filter intent untuk https://example.com/articles, dan app2 dapat mendeklarasikan filter intent untuk https://example.com/videos.

Mengaitkan beberapa situs dengan satu aplikasi

Beberapa situs dapat mendeklarasikan pengaitan dengan aplikasi yang sama dalam file assetlinks.json masing-masing. Daftar file berikut menunjukkan contoh cara mendeklarasikan pengaitan example.com dan example.net dengan app1. Listingan pertama menunjukkan pengaitan example.com dengan app1:

https://www.example.com/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Daftar berikutnya menunjukkan keterkaitan example.net dengan app1. Hanya lokasi tempat file ini dihosting yang berbeda (.com dan .net):

https://www.example.net/.well-known/assetlinks.json

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mycompany.app1",
    "sha256_cert_fingerprints":
    ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
  }
}]

Mengonfigurasi aturan dinamis

Link Aplikasi Dinamis di Android 15+ memungkinkan Anda menggunakan aturan pencocokan deep link sisi server yang berfungsi bersama dengan aturan yang telah Anda tentukan secara statis dalam manifes aplikasi. File assetlinks.json adalah tempat Anda menentukan aturan dinamis. Informasi ini bersifat opsional untuk disertakan.

Perangkat Android yang menjalankan Android 15 (level API 35) atau yang lebih baru yang telah menginstal layanan Google akan mengambil file ini secara berkala dari server Anda dan menggabungkan konfigurasi aturan dinamis Anda dengan konfigurasi statis dalam manifes aplikasi. Berikut adalah contoh file assetlinks.json dengan aturan dinamis:

[
  {
    "relation": [
      "delegate_permission/common.handle_all_urls"
    ],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [...]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          {"?": {"dl": "*"}},
          {"#": "app"},
          {"/": "/products/*"},
          {"/": "/shoes", "?": {"in_app": "true"}},
          {"/": "*", "exclude": true}
        ]
      }
    }
  }
]

Poin penting tentang kode

  • Link Aplikasi Dinamis menambahkan ekstensi hubungan Digital Asset Links baru yang disebut dynamic_app_link_components, yang merupakan tempat Anda mengonfigurasi aturan dinamis.
  • Aturan dinamis dapat menyertakan pencocok pola untuk parameter jalur, fragmen, dan kueri.
  • Anda juga dapat menandai pencocok pola apa pun sebagai dikecualikan, sehingga URL yang cocok tidak membuka aplikasi Anda.
  • Contoh ini menunjukkan contoh pencocok untuk jalur ("/"), fragmen ("#"), dan parameter kueri ("?"), serta pencocok yang dikecualikan ("exclude")
  • Jika ada kolom dalam file yang salah format atau kosong, Android akan menghapus aturan dinamis dan perangkat akan kembali ke aturan yang ditentukan secara statis dalam manifes aplikasi.

Aturan dinamis hanya dapat menentukan aturan yang berlaku dalam cakupan domain yang Anda deklarasikan dalam file manifes aplikasi. Lihat bagian Mendeklarasikan aturan dinamis.

Mendeklarasikan aturan dinamis

Link Aplikasi Dinamis mendukung ekstensi relasi dynamic_app_link_components baru, yang menyimpan array objek aturan. Setiap aturan ditentukan menggunakan pencocok pola untuk jalur, fragmen, dan parameter kueri yang akan membuka aplikasi Anda. Pencocok juga dapat dikecualikan satu per satu sehingga tidak akan membuka aplikasi Anda. Semua ini bersifat opsional.

  • Pencocokan jalur
    • Tombol: "/"
    • Nilai: String tunggal, ekspresi pencocokan untuk jalur URL
  • Pencocokan fragmen
    • Tombol: "#"
    • Nilai: String tunggal, ekspresi yang cocok untuk fragmen URL
  • Pencocokan parameter kueri
    • Tombol: "?"
    • Nilai: Kamus untuk mencocokkan pasangan kunci/nilai dalam parameter kueri URL.
    • Misalnya, kamus {"?", {"dl": "*", "in_app":"true"} akan cocok dengan string kueri "?in_app=true&dl=abc".
    • Urutan pasangan kunci/nilai dalam kamus tidak perlu sama dengan urutan pasangan dalam string kueri. Selain itu, kamus tidak perlu mencocokkan semua key-value pair dalam string kueri, tetapi kecocokan harus ditemukan untuk setiap entri kamus.
    • Misalnya, kamus juga akan cocok dengan string kueri "?lang=en&in_app=true&tz=pst&dl=abc", tetapi tidak cocok dengan string kueri "?lang=en&tz=pst&dl=abc"
  • Dikecualikan
    • Kunci: "exclude"
    • Nilai: Nilai benar/salah opsional untuk setiap aturan yang ditentukan di dynamic_app_link_components (lihat contoh).

Anda dapat menggunakan karakter khusus berikut dalam pencocok pola:

  • "*" cocok dengan nol atau beberapa karakter hingga karakter setelah karakter pengganti dalam pola ditemukan dalam string yang cocok
  • "?" cocok dengan karakter tunggal apa pun
  • "?*" cocok dengan 1 karakter atau lebih

Tidak ada batasan karakter lain untuk nilai.

Aturan dinamis pesanan

Urutan deklarasi aturan itu penting. Android mengevaluasi setiap aturan secara berurutan hingga menemukan kecocokan.

Contoh berikut menunjukkan pengaruh pengurutan terhadap penanganan. Aturan pertama cocok dengan semua jalur ("*"), tetapi mengecualikan kecocokan (exclude: true), yang berarti aturan tersebut mengecualikan semua URL agar tidak membuka aplikasi. Dalam hal ini, aturan kedua yang mengizinkan "/path1" tidak akan pernah dievaluasi.

dynamic_app_link_components: [
  {"/": "*", "exclude": true},
  {"/": "/path1"}
]

Namun, dalam contoh berikutnya, aturan "/path1" dideklarasikan terlebih dahulu, sehingga akan dievaluasi terlebih dahulu dan akan membuka aplikasi untuk URL yang cocok dengan "/path1". Aturan kedua, yang mengecualikan semua URL agar tidak membuka aplikasi, akan dievaluasi kedua, tetapi hanya jika aturan pertama tidak cocok.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "*", "exclude": true}
]

Jika tidak ada kecocokan yang ditemukan dalam daftar komponen yang dideklarasikan, URL tidak akan membuka aplikasi. Dalam contoh berikut, tidak ada jalur yang cocok dengan "/path3" sehingga perangkat akan memperlakukan jalur ini sebagai dikecualikan.

dynamic_app_link_components: [
  {"/": "/path1"},
  {"/": "/path2"}
]

Perilaku ini penting jika Anda ingin dynamic_app_link_components hanya mengecualikan bagian URL tertentu, tetapi mengizinkan semua bagian lainnya. Dalam contoh berikut, menghilangkan aturan akhir untuk mengizinkan semua jalur yang tersisa akan berarti bahwa semua URL dikecualikan dari aplikasi.

dynamic_app_link_components: [
  {"/": "/path1", "exclude": true},
  {"/": "*"}
]

Menentukan cakupan aturan dinamis dengan benar

Saat menentukan aturan sisi server untuk digunakan dengan Link Aplikasi Dinamis di Android 15 dan yang lebih tinggi, penting untuk menentukan cakupannya dengan tepat, sehingga aturan tersebut berfungsi dengan dan melengkapi filter intent statis yang dideklarasikan dalam manifes aplikasi Anda.

Aturan dinamis yang dideklarasikan dalam file assetlinks.json hanya dapat menentukan aturan untuk host yang Anda deklarasikan dalam file AndroidManifest.xml aplikasi. Aturan dinamis tidak dapat memperluas cakupan aturan URL yang Anda deklarasikan secara statis dalam manifes aplikasi.

Oleh karena itu, sebaiknya gunakan pendekatan ini di seluruh aturan dinamis dan statis Anda:

  • Dalam manifes aplikasi, tetapkan aturan dengan cakupan seluas mungkin, seperti dengan hanya mendeklarasikan skema dan domain
  • Andalkan aturan dinamis sisi server untuk penyempurnaan lebih lanjut, seperti perutean tingkat jalur.

Dengan konfigurasi ideal ini, Anda akan dapat menambahkan jalur App Links baru secara dinamis dalam file assetlinks.json sesuai kebutuhan, dengan mengetahui bahwa jalur tersebut akan sesuai dengan cakupan luas yang telah Anda tetapkan dalam manifes aplikasi.

Untuk penanganan aturan yang tepat, deklarasikan hanya satu objek dynamic_app_link_components di seluruh pernyataan untuk situs, hubungan, dan aplikasi tertentu.

  • Cari beberapa pernyataan untuk situs, hubungan, dan aplikasi yang sama, yang mendeklarasikan objek dynamic_app_link_components.
  • Mencari beberapa objek dynamic_app_link_components yang dideklarasikan dalam satu pernyataan

Dalam kasus seperti ini, Android tidak menjamin konfigurasi aturan dinamis mana yang akan digunakan.

Kompatibilitas aturan dinamis dengan konfigurasi Link Aplikasi sebelumnya

Jika sudah mendukung Link Aplikasi, Anda dapat menambahkan dukungan untuk Link Aplikasi Dinamis langsung di file assetlinks.json yang ada. Kolom relasi untuk memverifikasi Link Aplikasi Anda tetap sama, dan Anda dapat menambahkan kolom ekstensi relasi baru untuk aturan dinamis tanpa perubahan lainnya.

Perangkat Android yang menjalankan Android 14 (level API 34 atau yang lebih lama) mengabaikan kolom ekstensi hubungan baru untuk aturan dinamis, sedangkan perangkat yang menjalankan Android 15 dan yang lebih baru akan menggabungkan aturan tersebut dengan aturan yang ditentukan manifes Anda.

Memublikasikan file verifikasi JSON

Anda harus memublikasikan file verifikasi JSON Anda di lokasi berikut:

https://domain.name/.well-known/assetlinks.json

Pastikan hal-hal berikut:

  • File assetlinks.json ditayangkan dengan jenis konten application/json.
  • File assetlinks.json harus dapat diakses melalui koneksi HTTPS, terlepas dari apakah filter intent aplikasi Anda mendeklarasikan HTTPS sebagai skema data.
  • File assetlinks.json harus dapat diakses tanpa pengalihan apa pun (tanpa pengalihan 301 atau 302).
  • Jika link aplikasi Anda mendukung beberapa domain host, Anda harus memublikasikan file assetlinks.json di setiap domain. Lihat Mendukung penautan aplikasi untuk beberapa host.
  • Jangan publikasikan aplikasi Anda dengan URL pengujian dalam file manifes yang mungkin tidak dapat diakses oleh publik (seperti URL yang hanya dapat diakses dengan VPN). Solusi dalam kasus tersebut adalah mengonfigurasi varian build untuk membuat file manifes yang berbeda untuk build pengembangan.

Lihat panduan terkait berikut: