Arsitektur Aplikasi 13 mnt bacaIntermediate

Deep Linking .NET MAUI 2026: Universal & App Links

Panduan lengkap deep linking .NET MAUI: konfigurasi Android App Links (assetlinks.json), iOS Universal Links (AASA), routing Shell, dan migrasi dari Firebase Dynamic Links yang sudah dihentikan. Termasuk trik debugging dari produksi.

David O'ReillyReviewed by Marcus Chen, Sep 2026
Deep Linking .NET MAUI 2026: iOS & Android

Diperbarui: 2 September 2026

Deep linking di .NET MAUI adalah mekanisme yang memungkinkan URL http/https membuka halaman spesifik di dalam aplikasi native Android dan iOS, menggunakan App Links di Android (via assetlinks.json) dan Universal Links di iOS (via apple-app-site-association). Sejak .NET 9, MAUI menyederhanakan pemetaan URI ke rute Shell, tetapi konfigurasi platform-native tetap wajib. Apple dan Google memverifikasi kepemilikan domain sebelum mengarahkan tautan langsung ke aplikasi Anda. Artikel ini membedah setiap file konfigurasi, kode C# yang dibutuhkan, dan trik debugging yang tidak Anda temukan di dokumentasi resmi.

  • App Links Android memerlukan assetlinks.json di /.well-known/ dan intent filter android:autoVerify="true" di MainActivity. Verifikasi menggunakan fingerprint SHA-256 dari signing key produksi.
  • Universal Links iOS memerlukan file apple-app-site-association tanpa ekstensi, disajikan sebagai application/json tanpa redirect, dan capability Associated Domains dengan prefix applinks:.
  • Firebase Dynamic Links resmi mati pada 25 Agustus 2025, jadi semua aplikasi wajib beralih ke App Links/Universal Links atau alternatif pihak ketiga seperti Branch atau AppsFlyer.
  • .NET MAUI menangani deep link melalui override OnAppLinkRequestReceived di App.xaml.cs, kemudian mem-parsing URI dan memanggil Shell.Current.GoToAsync dengan parameter query.
  • Testing deep link tidak sama seperti klik link biasa. Di Android gunakan adb shell am start dan di iOS gunakan xcrun simctl openurl agar mem-bypass cache verifikasi Safari.
  • Custom URL scheme (myapp://) tetap berguna sebagai fallback OAuth callback, tetapi tidak lagi direkomendasikan sebagai skema utama karena tidak bisa diverifikasi kepemilikan domain-nya.

Apa itu deep linking di .NET MAUI?

Deep linking adalah proses membuka layar tertentu di dalam aplikasi mobile lewat sebuah URL, alih-alih hanya membuka layar beranda. Di ekosistem .NET MAUI, ada tiga jenis tautan yang saling berbeda perilaku sistem operasinya: App Links untuk Android (URL https:// yang diverifikasi Google Play), Universal Links untuk iOS (URL https:// yang diverifikasi Apple), dan Custom URL Scheme seperti myapp://profile/42 yang tidak memerlukan domain sama sekali.

Yang membuat topik ini menyakitkan adalah kenyataan bahwa MAUI cuma mengurus lapisan tipis di atas API native. Anda tetap harus mengedit Info.plist, mengelola capability Associated Domains di Xcode, meng-host file di root domain HTTPS Anda, dan menghitung SHA-256 dari sertifikat penandatanganan release. Saya sudah mengirim tiga aplikasi produksi dengan alur ini di MAUI, dan setiap kali ada satu langkah kecil (biasanya redirect di CDN) yang membuat verifikasi gagal secara diam-diam. Sebelum menulis kode C#, pahami dulu bahwa yang menentukan apakah link Anda membuka aplikasi bukanlah kode Anda, melainkan konfigurasi server dan manifest.

Di .NET 9 dan .NET 10, tim MAUI merapikan Microsoft.Maui.ApplicationModel.AppActions dan menambahkan callback OnAppLinkRequestReceived di kelas App Anda. API ini berlaku sama untuk App Links dan Universal Links, cukup subscribe sekali dan Anda menerima objek Uri lintas platform.

Sebelum menulis satu baris kode, tentukan dulu jenis tautan yang Anda butuhkan. Ketiga jenis ini punya trade-off berbeda pada verifikasi, UX pengguna, dan dukungan browser. Tabel berikut merangkum apa yang penting untuk aplikasi produksi.

AspekApp Links (Android)Universal Links (iOS)Custom URL Scheme
Format URLhttps://domain.com/pathhttps://domain.com/pathmyapp://path
Wajib domain HTTPS?Ya, dengan file assetlinks.jsonYa, dengan file apple-app-site-associationTidak
Verifikasi kepemilikanOtomatis oleh Play/Android saat installOtomatis oleh iOS saat installTidak ada, bisa di-hijack aplikasi lain
Fallback jika app tidak adaBuka di browser (URL asli)Buka di Safari (URL asli)Error atau "no app can handle this URL"
Dukungan OS minimumAndroid 6.0 (API 23)iOS 9+Semua versi
Cocok untuk OAuth callback?Ya, tetapi butuh setup domainYa, tetapi butuh setup domainYa, pilihan default Microsoft Identity
Kelemahan utamaButuh SHA-256 signing key produksi yang benarCache AASA 8 jam pada iOS 14+, sulit debugRawan bentrok dengan app lain

Aturan praktisnya di 2026: gunakan App Links dan Universal Links sebagai jalur utama untuk deep link marketing, email, dan sharing. Sisakan Custom URL Scheme untuk OAuth 2.0 redirect, pola yang direkomendasikan Microsoft Identity Web dan yang saya bahas di panduan autentikasi dan keamanan .NET MAUI.

Android App Links diverifikasi Google saat aplikasi dipasang. Sistem mengunduh file https://yourdomain.com/.well-known/assetlinks.json, memeriksa SHA-256 signing key di dalamnya, dan hanya kemudian menandai domain Anda sebagai "trusted". Kalau verifikasi gagal, Android akan menampilkan disambiguation dialog dan user diminta memilih browser atau aplikasi Anda setiap kali. Honestly, ini pengalaman UX yang sangat jelek jadi hindari dengan segala cara.

1. Ambil SHA-256 dari signing key produksi

Ini bukan debug key. Signing key produksi Anda adalah keystore yang digunakan untuk build Play Store release. Jalankan:

keytool -list -v -keystore /path/to/release.keystore -alias my_alias
# atau untuk Play App Signing (rekomendasi Google):
# Ambil SHA-256 dari Play Console -> Setup -> App integrity -> App signing key certificate

Kolom yang Anda butuhkan adalah SHA256:, 32 pasang hex dipisah titik dua.

2. Buat file assetlinks.json

Host file ini persis di https://yourdomain.com/.well-known/assetlinks.json, disajikan sebagai application/json, TANPA redirect (bahkan HTTPS→HTTPS), dan status HTTP 200:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.mobiletechlead.demo",
    "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"
    ]
  }
}]

3. Tambah intent filter di MainActivity

Di file Platforms/Android/MainActivity.cs, tambahkan attribute IntentFilter:

[Activity(Theme = "@style/Maui.SplashTheme", MainLauncher = true, ...)]
[IntentFilter(
    new[] { Android.Content.Intent.ActionView },
    Categories = new[] {
        Android.Content.Intent.CategoryDefault,
        Android.Content.Intent.CategoryBrowsable
    },
    DataScheme = "https",
    DataHost = "yourdomain.com",
    DataPathPrefix = "/app",
    AutoVerify = true)]
public class MainActivity : MauiAppCompatActivity { }

AutoVerify = true adalah kunci. Tanpa ini, Android tidak akan pernah mengunduh assetlinks.json dan Anda akan selamanya melihat disambiguation dialog. Verifikasi ulang dengan adb shell pm get-app-links com.mobiletechlead.demo, status "verified" berarti sukses.

iOS Universal Links secara konseptual mirip App Links, perbedaannya di detail. Yang bikin frustasi: iOS meng-cache file AASA sampai 8 jam (iOS 14+) atau bahkan hingga aplikasi di-reinstall. Bug pada file AASA Anda hari ini baru terlihat besok pagi.

1. Buat file apple-app-site-association

Host file tanpa ekstensi (bukan .json) di https://yourdomain.com/.well-known/apple-app-site-association, disajikan sebagai application/json, tanpa redirect, dan HTTPS yang valid (self-signed cert ditolak):

{
  "applinks": {
    "details": [{
      "appIDs": ["ABCD123456.com.mobiletechlead.demo"],
      "components": [
        { "/": "/app/*", "comment": "Buka semua path /app/*" },
        { "/": "/promo/*", "?": { "utm_source": "email" }, "comment": "Match query" }
      ]
    }]
  }
}

ABCD123456 adalah Team ID Anda dari Apple Developer portal, dan com.mobiletechlead.demo adalah Bundle ID iOS Anda.

2. Aktifkan Associated Domains capability

Edit Platforms/iOS/Entitlements.plist dan tambahkan:

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:yourdomain.com</string>
    <string>applinks:www.yourdomain.com</string>
</array>

Pastikan Anda memiliki App ID di Apple Developer portal dengan capability "Associated Domains" enabled. Kalau tidak, Xcode akan menolak provisioning profile dengan pesan yang tidak informatif.

3. Mode "alternate mode" untuk debugging

Setelah menghabiskan berapa sore mengulang siklus Delete App → Reboot → Install, saya sangat merekomendasikan menggunakan mode ?mode=developer di entitlement selama development. Dokumentasi Apple Supporting Associated Domains menjelaskan bagaimana developer mode mem-bypass cache. Sangat berguna, tetapi jangan lupa cabut sebelum submit ke App Store, atau reviewer akan bounce build Anda.

Setelah kedua platform Anda setup, kode C#-nya justru relatif ringkas. .NET MAUI memaparkan event OnAppLinkRequestReceived di class App, dan event ini dipanggil untuk App Links Android maupun Universal Links iOS. Berikut pattern lengkap yang saya gunakan di produksi:

// File: App.xaml.cs
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        MainPage = new AppShell();
    }

    protected override async void OnAppLinkRequestReceived(Uri uri)
    {
        base.OnAppLinkRequestReceived(uri);

        // Contoh URI: https://mobiletechlead.com/app/product/42?ref=email
        if (uri.Host.EndsWith("mobiletechlead.com", StringComparison.OrdinalIgnoreCase))
        {
            var segments = uri.AbsolutePath.Trim('/').Split('/');

            if (segments.Length >= 2 && segments[0] == "app")
            {
                var route = segments[1] switch
                {
                    "product" when segments.Length >= 3 => $"//products/details?id={segments[2]}",
                    "promo"                              => $"//promo?{uri.Query.TrimStart('?')}",
                    _                                    => "//home"
                };

                await Shell.Current.GoToAsync(route);
            }
        }
    }
}

Beberapa hal yang tidak terlihat dari kode tetapi penting:

  • Cold start vs warm start: kalau aplikasi belum berjalan, iOS/Android akan meluncurkan aplikasi dan callback dipanggil setelah App selesai konstruksi. Pastikan Shell Anda sudah ter-initialize sebelum memanggil GoToAsync.
  • Threading: callback dipanggil di UI thread, aman untuk navigasi, tetapi hindari operasi I/O blocking di sini.
  • Parameter aman: selalu validasi panjang segments. URL malformed dari serangan phishing bisa membuat aplikasi Anda crash kalau Anda mengasumsikan struktur.

Routing Shell & passing parameter dari deep link

.NET MAUI Shell mendukung query string style parameter yang diterjemahkan menjadi properti pada halaman tujuan. Kombinasikan dengan [QueryProperty] attribute agar clean, seperti yang saya jelaskan di arsitektur .NET MAUI dengan Shell Navigation.

Registrasi route

// AppShell.xaml.cs
public AppShell()
{
    InitializeComponent();
    Routing.RegisterRoute("products/details", typeof(ProductDetailsPage));
    Routing.RegisterRoute("promo", typeof(PromoPage));
}

Terima parameter di ViewModel

[QueryProperty(nameof(ProductId), "id")]
[QueryProperty(nameof(Referrer), "ref")]
public partial class ProductDetailsViewModel : ObservableObject
{
    [ObservableProperty]
    private string _productId;

    [ObservableProperty]
    private string _referrer;

    partial void OnProductIdChanged(string value)
    {
        // Load produk saat parameter tiba dari deep link
        _ = LoadProductAsync(value);
    }
}

Pola ini memisahkan parsing URI (di App.xaml.cs) dari domain logic (di ViewModel), sehingga Anda bisa unit-test rute mapping tanpa perlu menjalankan aplikasi.

Menguji deep link dengan mengetik URL di browser sering tidak berhasil. Safari punya cache tersendiri, dan Chrome Android akan menampilkan intent picker. Cara "resmi" yang saya pakai setiap hari:

Android via adb

# Simulasi user click Universal Link
adb shell am start -a android.intent.action.VIEW \
  -c android.intent.category.BROWSABLE \
  -d "https://mobiletechlead.com/app/product/42?ref=test" \
  com.mobiletechlead.demo

# Cek status verifikasi App Links
adb shell pm get-app-links com.mobiletechlead.demo

# Trigger ulang verifikasi App Links (Android 12+)
adb shell pm verify-app-links --re-verify com.mobiletechlead.demo

iOS via xcrun (simulator)

# Wajib gunakan URL https, bukan custom scheme
xcrun simctl openurl booted "https://mobiletechlead.com/app/product/42?ref=test"

iOS via Notes app (device fisik)

Trik lama yang masih terbaik. Buka aplikasi Notes iOS di device Anda, ketik URL, tap link. Karena Notes bukan aplikasi Anda, iOS akan menghormati Universal Link dan membuka aplikasi Anda. Chrome/Safari tidak selalu berperilaku sama. Saya bahkan pernah hit bug di mana Safari mengembalikan HTTP 200 dari AASA tetapi tetap menolak buka aplikasi. Beralih ke Notes membuktikan bahwa file AASA saya sebenarnya sudah benar.

Google resmi mematikan Firebase Dynamic Links pada 25 Agustus 2025. Semua tautan yang di-generate lewat FDL sekarang hanya mengembalikan HTTP 404 atau redirect ke halaman deprecation. Kalau aplikasi MAUI atau Xamarin.Forms Anda masih pakai FDL, Anda punya tiga jalur migrasi:

  1. Migrasi penuh ke App Links + Universal Links, rekomendasi Google sendiri di FAQ deprecation FDL. Ini yang saya rekomendasikan kalau Anda tidak butuh deferred deep linking (kasus di mana user tap link, lalu install app dari store, dan setelah pertama kali dibuka aplikasi langsung navigasi ke konten yang tepat).
  2. Branch.io, AppsFlyer, atau Adjust. Ketiganya menawarkan deferred deep linking dan attribution. Berbayar, tetapi tidak perlu Anda maintain infrastruktur redirect sendiri.
  3. Bangun sendiri: redirect endpoint di server Anda yang membaca User-Agent, mengarahkan ke Play Store/App Store kalau app belum terinstall, dan mem-preserve context via cookie/fingerprint agar diambil saat pertama kali aplikasi launch.

Untuk aplikasi produksi yang saya dampingi migrasi, jalur 1 cukup untuk 80% use case. Deferred deep linking sering di-overengineer. Kalau UTM tracking Anda sudah ada di email/marketing, App Links normal dengan query param sudah menangkap semua yang Anda butuhkan.

Setelah puluhan sesi debugging, saya menyusun checklist urutan yang paling sering menjadi biang kerok. Jalani dari atas ke bawah.

Android: App Links tidak trigger

  1. Cek autoVerify=true di intent filter. Kalau tidak ada, Android tidak akan pernah mendownload assetlinks.json.
  2. Cek SHA-256, apakah Anda menggunakan fingerprint dari Play Signing certificate (bukan upload key)? Ambil dari Play Console → App Integrity.
  3. Cek respons server: curl -I https://yourdomain.com/.well-known/assetlinks.json harus HTTP 200, Content-Type application/json, dan tidak ada 301/302 di antaranya. Detail spesifikasi ada di dokumentasi Android App Links resmi.
  4. Cek verifikasi device: adb shell pm get-app-links <package>, status harus "verified". Kalau "unverified", biasanya cause di poin 2 atau 3.
  5. Cek CDN: Cloudflare/Fastly sering meng-inject cache headers atau redirect HTTPS yang membuat Google verifier fail. Bypass CDN untuk path /.well-known/.

iOS: Universal Links tidak trigger

  1. Uninstall dan reinstall aplikasi. iOS meng-cache AASA saat first install dan hanya me-refresh setelah beberapa jam.
  2. Cek AASA dari cache Apple: curl https://app-site-association.cdn-apple.com/a/v1/yourdomain.com. Kalau Apple tidak melihat file Anda, device pun tidak akan pernah melihatnya.
  3. Cek Team ID dan Bundle ID di AASA, harus persis TEAMID.bundleid, case-sensitive. Team ID ada di membership page Apple Developer.
  4. Cek capability Associated Domains: buka file .entitlements, pastikan prefix applinks: ada dan domain-nya persis (tanpa https://).
  5. Redirect terlarang: file AASA tidak boleh mengalami redirect satu kali pun. Bahkan HTTP → HTTPS redirect akan membuat iOS menolak verifikasi.

Untuk observability produksi, log kombinasi uri.Scheme, uri.Host, dan uri.PathAndQuery setiap kali OnAppLinkRequestReceived ter-trigger. Kalau Anda sudah menggunakan setup GitHub Actions dari panduan CI/CD .NET MAUI, tambahkan smoke test yang meng-invoke xcrun simctl openurl di post-build simulator boot. Regresi deep link biasanya masuk lewat perubahan routing yang tidak sengaja mem-break URI parsing.

Pertanyaan yang sering diajukan

Apakah saya masih perlu Custom URL Scheme kalau sudah pakai App Links dan Universal Links?

Ya, untuk kasus OAuth 2.0 redirect. Microsoft Identity Client (MSAL) dan Google Sign-In tetap menggunakan custom scheme sebagai callback default karena tidak membutuhkan verifikasi domain. Untuk marketing link, sharing, dan email, cukup App Links/Universal Links.

Bagaimana cara mendukung banyak domain sekaligus di satu aplikasi?

Di Android, tambahkan beberapa IntentFilter attribute (satu per domain) atau gunakan DataHosts array. Di iOS, tambahkan multiple entries di applinks: array Associated Domains. Setiap domain memerlukan assetlinks.json atau apple-app-site-association sendiri di root domain masing-masing.

Apakah deep link bekerja di .NET MAUI Blazor Hybrid?

Ya, OnAppLinkRequestReceived tetap dipanggil di App class. Anda kemudian bisa memanggil NavigationManager.NavigateTo di dalam komponen Blazor untuk berpindah rute. Yang perlu diperhatikan adalah race condition: pastikan BlazorWebView sudah selesai load sebelum navigasi diminta.

Bisakah deep link membawa parameter sensitif seperti token?

Sebaiknya tidak. URL Universal Link/App Link tetap dilog oleh sistem OS, dan pada Android, disambiguation dialog bisa mengekspos URL ke aplikasi lain. Gunakan short-lived exchange code yang di-tukarkan di server side, bukan token langsung. Prinsip yang sama berlaku untuk OAuth PKCE flow.

Kenapa deep link saya bekerja di iOS 16 tetapi tidak di iOS 17+?

Sejak iOS 17, Apple memperketat validasi components matcher di AASA. Beberapa pola wildcard yang dulu diterima sekarang gagal secara diam-diam. Jalankan file Anda lewat Apple AASA Validator dan pastikan setiap komponen menggunakan sintaks baru dengan key "/" dan "?" yang eksplisit, bukan singkatan lama.

David O'Reilly
Tentang Penulis David O'Reilly

Native iOS/Android specialist turned MAUI advocate. Writes about the gritty platform details most cross-platform tutorials skip.

Artikel Terkait