Melakukan migrasi dari Dynamic Links ke App Links & Universal Links

Panduan migrasi ini berfokus pada penggunaan App Links dan Universal Links, yang secara opsional menggunakan Firebase Hosting untuk menghosting file asosiasi situs aplikasi Anda.

Migrasi ini menggantikan fitur Firebase Dynamic Links berikut:

Fitur Firebase Dynamic Links App Links/Universal Links
Mengarahkan pengguna ke toko yang benar untuk perangkat mereka dengan sekali klik pada link ★
Memberi pengguna kelanjutan perjalanan menggunakan deep link yang ditangguhkan setelah mendownload dan menginstal aplikasi ★
Memberikan pengalaman kontekstual kepada pengguna menggunakan konten yang menerapkan deep link dalam aplikasi Anda (jika sudah diinstal)
Menyediakan data analisis terkait peristiwa klik link dinamis
Menyediakan kemampuan untuk membuat URL link pendek

Jika Anda terus memerlukan fitur Firebase Dynamic Link lain untuk migrasi yang tidak didukung dalam panduan ini, pelajari skenario migrasi lainnya dalam dokumentasi FAQ Penghentian Penggunaan Dynamic Links.

Misalnya Anda memiliki Firebase Dynamic Link yang terlihat seperti ini:

Contoh Dynamic Link
Nama link Selamat datang di Example.com
Deep link https://example.web.app/welcome
Aplikasi Android com.example.android
Aplikasi Apple com.example.ios
Dynamic Link panjang https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Dynamic Link pendek https://example.page.link/m9Mm

Tujuan panduan migrasi ini adalah mengganti Firebase Dynamic Links seperti ini:

https://example.page.link/m9Mm

Dengan deep link App Link/Universal Link yang terlihat seperti ini:

https://your-project-domain.web.app/welcome

Perlu diperhatikan bahwa deep link App Link/Universal Link akan memberikan hal berikut kepada pengguna:

  • Deep link yang dapat diklik untuk membuka aplikasi Anda jika sudah diinstal
  • Kelanjutan perjalanan pengguna yang mengarahkan mereka ke bagian tertentu dari aplikasi Anda saat dibuka

Namun, deep link App Link/Universal Link tidak akan memberikan perilaku berikut kepada pengguna Anda (yang sebelumnya dilakukan oleh Firebase Dynamic Links):

  • Mengarahkan pengguna ke toko yang tepat untuk perangkat mereka guna mendownload dan menginstal aplikasi Anda
  • Memberikan kelanjutan perjalanan pengguna setelah mendownload, menginstal, dan membuka aplikasi untuk pertama kalinya

Perhatikan perbedaan perilaku dan fungsi App Link/Universal Links ini dibandingkan dengan Firebase Dynamic Links yang disebutkan dalam tabel di atas.

Sebelum memulai

Firebase Dynamic Links menggunakan App Links (di Android) dan Universal Links (di iOS) dalam implementasinya sendiri untuk menyediakan fungsi deep linking setelah aplikasi Anda diinstal.

Panduan ini membahas cara membuat App Links dan Universal Links Anda sendiri menggunakan Firebase Hosting untuk menggantikan bagian fungsi yang disediakan oleh Firebase Dynamic Links saat memigrasikan Firebase Dynamic Links Anda ke solusi migrasi App Links/Universal Links yang baru.

Anda akan memerlukan informasi berikut untuk menyelesaikan migrasi:

  • Firebase Dynamic Links yang ingin Anda migrasikan
  • Parameter URL deep link yang disertakan dalam link dinamis
  • Domain yang akan Anda gunakan untuk mengganti domain Firebase Dynamic Links sebelumnya (jika ada)

Anda dapat menggunakan panduan Mengekspor Metadata Dynamic Links untuk mengekspor metadata link yang ada dan mendapatkan informasi yang tercantum di atas.

Ringkasan langkah migrasi

  1. Siapkan domain baru (jika Anda belum memiliki domain yang ingin digunakan) untuk menghosting file konfigurasi App Link/Universal Link menggunakan Firebase Hosting.

  2. Buat dan hosting file konfigurasi App Link/Universal Link di domain hosting Anda.

  3. Buat App Links/Universal Links baru yang cocok dengan skema deep link yang digunakan di Firebase Dynamic Links Anda.

  4. Update kode aplikasi dan aplikasi Android/iOS Anda untuk menerima deep link.

  5. Uji integrasi App Links/Universal Links Anda.

  6. Ganti Firebase Dynamic Links yang dipublikasikan atau dibagikan dengan App Links dan Universal Links.

Langkah pertama akan umum digunakan untuk alur migrasi App Links atau Universal Link. Sisanya akan berbeda-beda tergantung platformnya. Jadi buka bagian panduan di bawah ini, bergantung pada platform yang ingin Anda migrasikan terlebih dahulu.

Memilih domain

Langkah pertama adalah memilih domain yang ingin digunakan untuk App Links/Universal Links Domain tersebut akan digunakan untuk link baru yang akan Anda bagikan kepada pengguna.

Jika Anda menggunakan Firebase Hosting, subdomain project dengan format your-project-domain.web.app atau your-project-domain.firebaseapp.com otomatis akan disediakan tanpa biaya. Jika mau, Anda dapat menggunakan domain kustom dengan atau tanpa Firebase Hosting untuk menghosting file konfigurasi App Link/Universal Link.

Menyiapkan Firebase Hosting

Selanjutnya, Anda harus menyiapkan dan mengonfigurasi instance Firebase Hosting.

Setelah selesai menyiapkan instance Firebase Hosting, Anda akan memiliki domain yang mirip dengan your-project-domain.web.app, atau domain kustom jika Anda lebih menyukainya.

Untuk menggunakan App Links, Anda harus menghosting file konfigurasi yang membantu menciptakan pengaitan aman antara domain yang digunakan dalam link dan aplikasi Anda. Untuk App Links, ini adalah file assetlinks.json.

Langkah-langkah untuk membuat dan menghosting file assetlinks.json

File assetlinks.json dapat digunakan untuk menyediakan daftar aplikasi resmi yang dapat menangani konten domain web yang akan kita gunakan untuk App Links. File assetlinks.json itu sendiri harus dihosting di root domain web di jalur: /.well-known.

Ikuti langkah-langkah di bawah untuk menyelesaikan konfigurasi ini:

  1. Buat folder .well-known di folder publik di direktori root Firebase Hosting Anda.

  2. Buat file bernama assetlinks.json pada folder .well-known.

  3. Salin konten berikut ke file assetlinks.json Anda dengan memperhatikan makna setiap kolom di bawah ini:

    [{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.android",
    "sha256_cert_fingerprints":
      ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
  }
}]
    • namespace - mengacu pada nama aplikasi yang ingin Anda berikan
    • package_name - mengacu pada applicationId yang dideklarasikan di file build.gradle aplikasi
    • sha256_cert_fingerprints - mengacu pada sidik jari SHA256 file keystore yang Anda gunakan untuk menandatangani aplikasi.

    Anda dapat menggunakan file debug.keystore yang digunakan oleh Android Studio untuk menghasilkan data sha256_cert_fingerprints untuk tujuan proses debug. Anda dapat menemukan file tersebut di /Users/<username>/.android/debug.keystore pada Mac dan Linux serta C:\Users\<username>\.android\debug.keystore di Windows.

    Dari keystore ini, Anda dapat mengambil nilai SHA256 menggunakan keytool.

    Baca bagian dokumentasi App Links ini untuk mengetahui petunjuk selengkapnya tentang cara menyelesaikan langkah ini.

    Atau, Anda juga dapat menggunakan Asisten App Links di Android Studio untuk membuat konten file assetlinks.json dan mengonfigurasi aplikasi Anda untuk menangani App Links.

  4. Update file firebase.json Anda untuk mengindeks file yang akan dihosting.

    "headers": [
  {
    "source": "/.well-known/assetlinks.json",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

  5. Setelah file assetlinks.json diterapkan, jalankan firebase deploy untuk menghosting perubahan.

    Perhatikan bahwa Anda harus menginstal Firebase CLI agar dapat menjalankan perintah deploy di atas.

    firebase deploy --only hosting

  6. Verifikasi file assetlinks.json dengan membuka https://your-project-domain.web.app/.well-known/assetlinks.json

Pada langkah ini, Anda akan membuat ulang deep link dari Firebase Dynamic Links menggunakan URL deep link reguler yang cocok dengan domain baru yang Anda buat untuk App Links Anda.

Misalnya, Anda memiliki Firebase Dynamic Link berikut:

Contoh Dynamic Link
Nama link Selamat datang di Example.com
Deep link https://example.web.app/welcome
Aplikasi Android com.example.android
Aplikasi Apple com.example.ios
Dynamic Link panjang https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Dynamic Link pendek https://example.page.link/m9Mm

Dalam hal ini, Anda akan mengekstrak parameter deep link, yaitu https://example.web.app/welcome dan akan menggunakannya sebagai parameter App Link untuk aplikasi Anda.

Anda perlu mengulangi proses ini untuk setiap Firebase Dynamic Link yang ingin dimigrasikan menggunakan App Links/Universal Links, dan mereplikasi skema deep linking yang Anda gunakan.

Misalnya, lihat kumpulan link singkat Firebase Dynamic Links, parameter deep link, dan nilai deep link yang dimigrasikan berikut ini:

Link pendek Parameter deep link Deep link yang dimigrasikan
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social https://example.com/friendinvite/?add=1 yourapp.web.app/friendinvite/?add=1

Selanjutnya, Anda harus mengganti instance Firebase Dynamic Links yang telah dipublikasikan atau dibagikan dengan deep link baru yang dimigrasikan, sehingga pengguna akan mengklik App Links tersebut, bukan Firebase Dynamic Links sebelumnya.

Langkah berikutnya setelah memilih domain, memilih skema deep linking, dan memigrasikan Firebase Dynamic Links ke App Links adalah mengupdate aplikasi Android dan kode aplikasi Anda untuk menerima deep link baru.

Sebaiknya pelajari dokumentasi App Links di sini selengkapnya atau panduan Android Studio tentang cara mengonfigurasi aplikasi Anda untuk menangani deep link. Namun demikian, langkah-langkah utamanya meliputi:

  1. Mengidentifikasi aktivitas yang harus menangani deep link masing-masing
  2. Menambahkan Filter Intent untuk aktivitas tersebut dalam file AndroidManifest.xml
  3. Menerima deep link di kode aplikasi aktivitas Anda

Misalnya, Anda ingin menggunakan MainActivity untuk menangani beberapa deep link. Untuk melakukannya, Anda harus menambahkan Filter Intent berikut ke MainActivity dalam file AndroidManifest.xml Anda:

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

Pada langkah ini, Anda akan menentukan bahwa MainActivity adalah tujuan untuk menangani deep link dari domain wxample.web.app dan yang menyertakan awalan jalur /welcome. Perhatikan bahwa Anda juga perlu menentukan atribut android:autoVerify="true", sehingga dapat menetapkan aplikasi sebagai pengendali default untuk jenis link ini.

Terakhir, Anda harus menambahkan kode di MainActivity untuk mengambil data deep link dan menggunakannya untuk mendorong pengalaman deep link di aplikasi Anda. Hal ini mirip dengan logika yang mungkin telah Anda kodekan di aplikasi Anda saat berintegrasi dengan Firebase Dynamic Links.

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

Anda dapat menguji App Links yang baru saja dibuat dengan menjalankan aplikasi Anda di perangkat fisik atau di Android Emulator.

Anda harus membuat link yang dapat diklik menggunakan domain yang dikonfigurasi untuk App Links Anda, lalu mengklik link tersebut untuk memastikannya membuka ke aplikasi Anda dan mengarahkan Anda ke aktivitas yang diinginkan.

Atau, Anda juga dapat menguji integrasi App Links menggunakan Asisten App Links di Android Studio, atau menggunakan perintah berikut untuk URL App Link yang telah dikonfigurasi guna memastikannya meluncurkan aktivitas yang cocok dengan benar:

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

Langkah terakhir proses migrasi adalah mengganti Firebase Dynamic Links Anda yang dipublikasikan atau dibagikan dengan App Links jika memungkinkan, dan terus menggunakan App Links untuk ke depannya.

Penyelesaian langkah ini akan bervariasi bergantung pada tempat dan cara Anda memublikasikan Firebase Dynamic Links. Namun, untuk membantu Anda mengetahui Fireabase Dynamic Links mana yang akan dimigrasikan, Anda dapat mengekspor metadata Firebase Dynamic Link yang ada. Baca panduan Mengekspor Metadata Dynamic Links.

Untuk menggunakan Universal Links, Anda harus menghosting file konfigurasi yang membantu membuat pengaitan aman antara domain yang digunakan dalam link dan aplikasi Anda. Untuk Universal Links, file yang dimaksud adalah file apple-app-site-association (juga dikenal sebagai file AASA).

Langkah-langkah untuk membuat dan menghosting file apple-app-site-association

Dengan file AASA, kita dapat menyediakan daftar aplikasi resmi yang dapat menangani konten domain web yang akan kita gunakan untuk Universal Links. File AASA itu sendiri harus dihosting di root domain web di jalur: /.well-known.

Ikuti langkah-langkah di bawah untuk menyelesaikan konfigurasi ini:

  1. Buat folder ".well-known" di bawah folder publik di direktori root Firebase Hosting Anda.

  2. Buat file bernama "apple-app-site-association" di folder "well-known".

  3. Salin konten berikut ke file apple-app-site-association, dengan memperhatikan makna setiap kolom di bawah ini:

    {
  "applinks": {
    "apps": [],
    "details": [
      {
        "appId": "$TEAM_ID.com.firebase.UniversalLinks",
        "paths": [
          "NOT /_/*",
          "/*"
        ]
      }
    ]
  }
}
    • $TEAM_ID.BundleId - nama aplikasi yang sepenuhnya memenuhi syarat yang diberi otorisasi untuk menangani link

  4. Update file firebase.json Anda untuk mengindeks file yang akan dihosting.

    "headers": [
  {
    "source": "/.well-known/apple-app-site-association",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

  5. Setelah file AASA berada di tempatnya, lakukan firebase deploy untuk menghosting perubahan.

  6. Verifikasi file AASA dengan membuka https://your-project-domain.web.app/.well-known/app-app-site-association

Pada langkah ini, Anda akan membuat ulang deep link dari Firebase Dynamic Links menggunakan URL deep link reguler yang cocok dengan domain baru yang Anda buat untuk Universal Links Anda.

Misalnya, Anda memiliki Firebase Dynamic Link berikut:

Contoh Dynamic Link
Nama link Selamat datang di Example.com
Deep link https://example.web.app/welcome
Aplikasi Android com.example.android
Aplikasi Apple com.example.ios
Dynamic Link panjang https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos
Dynamic Link pendek https://example.page.link/m9Mm

Dalam hal ini, Anda akan mengekstrak parameter deep link, yaitu https://example.web.app/welcome dan akan menggunakannya sebagai parameter Universal Link untuk aplikasi Anda.

Anda perlu mengulangi proses ini untuk setiap Firebase Dynamic Link yang ingin dimigrasikan menggunakan App Links/Universal Links, dan mereplikasi skema deep linking yang Anda gunakan.

Misalnya, lihat kumpulan link singkat Firebase Dynamic Links, parameter deep link, dan nilai deep link yang dimigrasikan berikut ini:

Link pendek Parameter deep link Deep link yang dimigrasikan
yourapp.page.link/welcome https://example.com/welcome yourapp.web.app/welcome
yourapp.page.link/c7sn https://example.com/main/?p=23&t=1 yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social https://example.com/friendinvite/?add=1 yourapp.web.app/friendinvite/?add=1

Selanjutnya, Anda harus mengganti instance Firebase Dynamic Links yang telah dipublikasikan atau dibagikan dengan deep link baru yang dimigrasikan, sehingga pengguna akan mengklik Universal Links tersebut, bukan Firebase Dynamic Links sebelumnya.

Langkah berikutnya setelah memilih domain, memilih skema deep linking, dan memigrasikan Firebase Dynamic Links ke Universal Links adalah mengupdate aplikasi iOS dan kode aplikasi Anda untuk menerima deep link baru.

Sebaiknya pelajari dokumentasi Universal Links di sini selengkapnya terkait cara mengonfigurasikan aplikasi Anda untuk menangani deep link. Namun demikian, langkah-langkah utamanya meliputi:

  1. Mengupdate konfigurasi project agar aplikasi Anda dapat menangani deep link dari domain yang baru dibuat

  2. Menerima deep link di kode aplikasi Anda

Guna mengupdate konfigurasi project agar aplikasi Anda dapat menangani deep link, Anda harus menambahkan Associated Domain tambahan ke project tersebut di xCode untuk domain yang akan digunakan untuk menghosting file apple-app-site-Association.

Hal ini dapat dilakukan dengan:

  1. Membuka Xcode
  2. Memilih project di file navigator
  3. Membuka tab Signing & Capabilities di project settings Anda
  4. Membuka bagian Associated Domains
  5. Mengklik tombol + untuk menambahkan domain tambahan ke project Anda dalam format "applinks:".

Terakhir, Anda harus mengupdate kode aplikasi agar dapat menerima deep link yang masuk.

Untuk melakukannya, update file AppDelegate.swift terlebih dahulu untuk merespons ke Universal Link dengan menambahkan kode berikut:

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

Kode di atas akan menggantikan metode callback Universal Link dan mencatat URL deep link ke dalam log jika ada.

Sekarang kita juga akan memanggil metode showReceivedUrl yang sama dari class SceneDelegate. Hal ini harus dilakukan karena jika aplikasi sudah terbuka pada saat pengguna mengklik link universal, callback link universal yang ada di dalam SceneDelegate akan menjadi callback yang dipanggil.

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

Anda dapat menguji Universal Links yang baru saja dibuat dengan menjalankan aplikasi Anda di simulator atau perangkat fisik.

Anda harus membuat link yang dapat diklik menggunakan domain yang dikonfigurasi untuk Universal Links Anda, lalu mengklik link tersebut untuk memastikannya terbuka ke aplikasi Anda dan mengarahkan Anda ke layar yang diinginkan di aplikasi.

Mendukung Smart App Banners

Sebaiknya gunakan Smart App Banners sebagai cara untuk memberikan pengalaman yang sama kepada pengguna seperti halnya pada Firebase Dynamic Links.

Dengan menggunakan Smart App Banners, pengguna akan diarahkan ke App Store untuk listingan aplikasi Anda jika aplikasi tersebut belum terinstal di perangkat mereka. Secara opsional, Anda juga dapat mengonfigurasi parameter untuk diteruskan ke aplikasi Anda setelah didownload dan diinstal agar pengguna dapat melanjutkan perjalanan mereka. Jika sudah terinstal, aplikasi Anda akan membuka penerusan di parameter ke aplikasi untuk membantu mengarahkan pengguna ke konten yang sesuai berdasarkan Smart App Banner yang diklik.

Langkah terakhir proses migrasi adalah mengganti Firebase Dynamic Links Anda yang dipublikasikan atau dibagikan dengan Universal Links jika memungkinkan, dan terus menggunakan Universal Links untuk ke depannya.

Penyelesaian langkah ini akan bervariasi bergantung pada tempat dan cara Anda memublikasikan Firebase Dynamic Links.

Untuk membantu Anda melacak Firebase Dynamic Links yang ada yang akan dimigrasikan, kami akan memublikasikan panduan tentang cara mengekspor metadata link pendek Anda dari Firebase Dynamic Links. Pelajari kembali dokumen FAQ Penghentian Penggunaan Dynamic Links kami untuk mengetahui informasi terbaru.