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 sudah dikenal di situs Anda. File ini secara publik menyatakan 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 Dynamic App Links 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 versi aplikasi Anda yang berbeda, seperti build produksi dan debug. Jika Anda menggunakan Penandatanganan Aplikasi Play untuk aplikasi Anda, sidik jari sertifikat yang dihasilkan dengan menjalankan keytool secara lokal biasanya tidak 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 untuk membuka 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 keterkaitan dengan aplikasi yang sama pada file assetlinks.json masing-masing. Daftar file berikut menunjukkan contoh cara mendeklarasikan keterkaitan example.com dan example.net dengan app1. Daftar pertama menunjukkan keterkaitan 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. Yang berbeda hanya lokasi tempat file-file ini dihosting (.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. Anda menentukan aturan dinamis di file assetlinks.json. Bagian 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

  • App Links Dinamis menambahkan ekstensi hubungan Digital Asset Links baru yang disebut dynamic_app_link_components, tempat Anda mengonfigurasi aturan dinamis.
  • Aturan dinamis dapat mencakup pencocok pola untuk parameter jalur, fragmen, dan kueri.
  • Anda juga dapat menandai pencocok pola sebagai dikecualikan, sehingga URL yang cocok tidak akan 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 Anda. Lihat di bawah ini.

Mendeklarasikan aturan dinamis

Link Aplikasi Dinamis mendukung ekstensi relasi dynamic_app_link_components baru, yang berisi 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
    • Kunci: "/"
    • Nilai: String tunggal, ekspresi pencocokan untuk jalur URL
  • Pencocokan fragmen
    • Kunci: "#"
    • Nilai: String tunggal, ekspresi yang cocok untuk fragmen URL
  • Pencocokan parameter kueri
    • Kunci: "?"
    • 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 nilai kunci dalam kamus tidak harus cocok dengan urutan pasangan dalam string kueri. Selain itu, kamus tidak perlu mencocokkan semua pasangan nilai kunci 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 dalam dynamic_app_link_components (lihat contoh).

Anda dapat menggunakan karakter khusus ini dalam pencocok pola:

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

Tidak ada batasan karakter lain untuk nilai.

Memesan aturan dinamis

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

Contoh berikut menunjukkan bagaimana pengurutan dapat memengaruhi penanganan. Aturan pertama mencocokkan 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}
]

Mencakup aturan dinamis dengan benar

Saat menentukan aturan sisi server untuk digunakan dengan Link Aplikasi Dinamis di Android 15 dan yang lebih tinggi, Anda harus menetapkan 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 Anda. 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 mendeklarasikan skema dan domain saja
  • Mengandalkan aturan dinamis sisi server untuk penyempurnaan lebih lanjut, seperti perutean tingkat jalur.

Dengan konfigurasi ideal ini, Anda 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.
  • Cari 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 lain.

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

Publikasikan 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 memublikasikan aplikasi dengan URL pengujian dalam file manifes yang mungkin tidak dapat diakses oleh publik (seperti yang hanya dapat diakses dengan VPN). Salah satu penyelesaian untuk kasus tersebut adalah mengonfigurasi varian build guna menghasilkan file manifes berbeda untuk build dev.

Lihat panduan terkait berikut: