Mencocokkan deep link URI

Untuk mencocokkan URI hierarkis dengan pola dan mengekstrak argumen, gunakan UriDeepLinkMatcher. Library ini mengandalkan kotlinx.serialization untuk melakukan deserialisasi argumen yang cocok ke dalam class kunci Anda.

Untuk membuat UriDeepLinkMatcher, berikan pola DeepLinkUri dan serializer untuk kunci yang sesuai:

@Serializable
data class UserProfileKey(val id: String) : NavKey

val userProfilePattern = DeepLinkUri("www.example.com/users/{id}")
val userProfileMatcher = UriDeepLinkMatcher(userProfilePattern, serializer<UserProfileKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/users/123")
val matchResult = userProfileMatcher.match(request)
val key = matchResult?.key // UserProfileKey(id = "123")
UriMatcherSnippets.kt

Untuk URI non-hierarkis atau skema kustom (seperti tel:), lihat Membuat pencocok deep link kustom.

Pola pencocokan yang didukung

UriDeepLinkMatcher mencocokkan URI berdasarkan lima komponennya: skema, otoritas, jalur, kueri, dan fragmen. Bagian berikut menjelaskan sintaksis pola yang didukung, placeholder argumen, dan aturan pencocokan untuk setiap komponen.

Pencocokan skema

Jika tidak ada skema dalam pola URI, http dan https akan dicocokkan. Untuk mencocokkan skema tertentu, sertakan skema tersebut dalam pola. Sebagai pengecualian, skema http dalam pola cocok dengan URI permintaan http dan https, sedangkan https dalam pola hanya cocok dengan permintaan https.

Pencocokan otoritas

UriDeepLinkMatcher melakukan pencocokan persis yang tidak peka huruf besar/kecil pada otoritas URI (host dan port opsional). Placeholder atau karakter pengganti tidak didukung dalam otoritas, dan tidak ada argumen yang diekstrak:

Pencocokan jalur

Pola jalur berikut didukung:

Pencocokan kueri

Urutan parameter kueri dalam URI permintaan tidak harus sama dengan urutan dalam URI pola. Selain itu, parameter yang ada di URI permintaan, tetapi tidak ada di URI pola akan diabaikan.

Pola parameter kueri berikut didukung:

Pencocokan fragmen

Jenis pola fragmen berikut didukung:

Jenis data yang didukung

UriDeepLinkMatcher mendukung deserialisasi argumen URI menjadi jenis primitif, enum, koleksi, dan objek kustom. Serialisasi terbagi menjadi dua kategori:

• Serialisasi standar: Menggunakan kotlinx.serialization untuk melakukan deserialisasi menjadi:
  • Primitif (Boolean, Int, Long, Float, Double, Char, Byte, Short) dan String
  • Enum
  • Set, List, atau Array primitif, string, atau enum
  • Class @Serializable bertingkat (yang propertinya diratakan menjadi placeholder URI individual)
• Serialisasi kustom dengan DeepLinkSerializer: Mengonversi antara satu String dan objek kustom, jenis eksternal (seperti java.time.LocalDate), atau koleksi yang dibatasi kustom.

Serialisasi standar

UriDeepLinkMatcher dapat langsung digunakan untuk jenis standar dan struktur yang di-flatten tanpa memerlukan implementasi serializer kustom.

Primitif dan string

UriDeepLinkMatcher otomatis mendekode jenis primitif (Boolean, Int, Long, Float, Double, Char, Byte, Short) dan String:

@Serializable
data class UserProfileKey(val id: Int) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/users/{id}"),
    serializer<UserProfileKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/users/123")
val key = matcher.match(request)?.key // UserProfileKey(id = 123)
UriMatcherSnippets.kt

Enum

Nilai enum dicocokkan dengan nama elemen enum dengan memperhatikan huruf besar/kecil:

enum class SortOrder { RELEVANCE, DATE, POPULARITY }

@Serializable
data class ProductsKey(val sort: SortOrder) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/products?sort={sort}"),
    serializer<ProductsKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/products?sort=DATE")
val key = matcher.match(request)?.key // ProductsKey(sort = SortOrder.DATE)
UriMatcherSnippets.kt

Koleksi kueri berulang

Parameter kueri dengan kunci berulang (seperti ?id=10&id=20) otomatis dideserialisasi menjadi List<T>, Set<T>, atau Array<T> dengan T adalah jenis primitif, String, atau enum:

@Serializable
data class FilteredItemsKey(val ids: List<Int>) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/items?id={ids}"),
    serializer<FilteredItemsKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/items?id=10&id=20")
val key = matcher.match(request)?.key // FilteredItemsKey(ids = listOf(10, 20))
UriMatcherSnippets.kt

Class @Serializable bertingkat

Jika NavKey berisi properti yang jenisnya adalah class @Serializable lain, UriDeepLinkMatcher akan meratakan propertinya sehingga setiap properti class bertingkat dipetakan langsung ke parameter URI individual dengan nama yang sama:

enum class SortOrder { RELEVANCE, DATE, POPULARITY }

@Serializable
data class SearchFilters(
    val category: String,
    val sortBy: SortOrder = SortOrder.RELEVANCE
)

@Serializable
data class SearchKey(
    val query: String,
    val page: Int = 1,
    // Flattened into {category} and {sortBy}
    val filters: SearchFilters
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/search?q={query}&page={page}&category={category}&sortBy={sortBy}"),
    serializer<SearchKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/search?q=kotlin&category=books&sortBy=DATE")
val key = matcher.match(request)?.key
// SearchKey(query = "kotlin", page = 1, filters = SearchFilters(category = "books", sortBy = SortOrder.DATE))
UriMatcherSnippets.kt

Serialisasi kustom dengan DeepLinkSerializer

Untuk melakukan deserialisasi objek kustom (seperti Filter(key = "brand", value = "pixel")), jenis eksternal (seperti java.time.LocalDate), atau string yang dibatasi kustom (seperti CSV), perluas DeepLinkSerializer<T>.

DeepLinkSerializer<T> adalah KSerializer<T> abstrak yang mengonversi antara String dan T:

abstract class DeepLinkSerializer<T : Any> : KSerializer<T> {
    abstract val serialName: String
    abstract fun deserialize(value: String): T
    abstract fun serialize(value: T): String
}

Misalnya, pertimbangkan definisi Filter dan FilterSerializer yang digunakan dalam cuplikan berikut:

@Serializable
data class Filter(val key: String, val value: String)

object FilterSerializer : DeepLinkSerializer<Filter>() {
    override val serialName: String = "com.example.Filter"

    override fun deserialize(value: String): Filter {
        val parts = value.split(":", limit = 2)
        if (parts.size < 2) {
            throw SerializationException("Invalid filter: $value. Expected key:value.")
        }
        return Filter(key = parts[0], value = parts[1])
    }

    override fun serialize(value: Filter): String = "${value.key}:${value.value}"
}
UriMatcherSnippets.kt

Objek kustom tunggal

Untuk mendekode objek dari satu string parameter URI (seperti ?filter=brand:google), anotasikan properti dengan @Serializable(with = ...):

@Serializable
data class CatalogKey(
    @Serializable(with = FilterSerializer::class)
    val filter: Filter
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/catalog?filter={filter}"),
    serializer<CatalogKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/catalog?filter=brand:google")
val key = matcher.match(request)?.key // CatalogKey(filter = Filter("brand", "google"))
UriMatcherSnippets.kt

Objek kustom dalam parameter kueri berulang

Untuk melakukan deserialisasi parameter kueri berulang ke dalam kumpulan objek kustom (List<T>, Set<T>, atau Array<T>), terapkan DeepLinkSerializer<T> untuk jenis elemen T dan anotasikan argumen jenis properti dengan @Serializable(with = ...):

@Serializable
data class SearchResultsKey(
    val query: String,
    val filters: List<@Serializable(with = FilterSerializer::class) Filter> = emptyList()
) : NavKey

val searchResultsPattern = DeepLinkUri("www.example.com/search?q={query}&filter={filters}")
val searchResultsMatcher = UriDeepLinkMatcher(searchResultsPattern, serializer<SearchResultsKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/search?q=phone&filter=brand:google&filter=color:hazel")
val matchResult = searchResultsMatcher.match(request)
val key = matchResult?.key
// SearchResultsKey(query = "phone", filters = listOf(Filter("brand", "google"), Filter("color", "hazel")))
UriMatcherSnippets.kt

Koleksi yang dibatasi dalam parameter tunggal

Untuk mengurai nilai yang dipisahkan koma atau dibatasi kustom (seperti ?ids=1,2,3) menjadi koleksi, terapkan DeepLinkSerializer untuk seluruh jenis koleksi dan anotasikan properti dengan @Serializable(with = ...):

object IntListCsvSerializer : DeepLinkSerializer<List<Int>>() {
    override val serialName: String = "com.example.IntListCsv"

    override fun deserialize(value: String): List<Int> {
        if (value.isEmpty()) return emptyList()
        return value.split(",").map { it.trim().toInt() }
    }

    override fun serialize(value: List<Int>): String = value.joinToString(",")
}

@Serializable
data class ItemListKey(
    @Serializable(with = IntListCsvSerializer::class)
    val ids: List<Int>
) : NavKey

val itemListPattern = DeepLinkUri("www.example.com/items/{ids}")
val itemListMatcher = UriDeepLinkMatcher(itemListPattern, serializer<ItemListKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/items/10,20,30")
val key = itemListMatcher.match(request)?.key // ItemListKey(ids = listOf(10, 20, 30))
UriMatcherSnippets.kt

Validasi argumen dan hasil pencocokan

UriDeepLinkMatcher membedakan antara ketidakcocokan (menampilkan null sehingga pencocok lain dapat dicoba) dan konfigurasi yang tidak didukung (memunculkan pengecualian).

Ketidakcocokan

Ketidakcocokan terjadi jika URI permintaan masuk tidak memenuhi persyaratan pola atau jenis:

• Parameter wajib tidak ada: Properti kunci yang tidak dapat di-null tanpa nilai default yang parameter URI terkaitnya tidak ada dalam URI permintaan.
• Kegagalan penguraian jenis: Nilai argumen yang diekstrak yang tidak dapat diuraikan menjadi jenis properti yang diharapkan (misalnya, "abc" untuk properti Int).

Jika terjadi ketidakcocokan, UriDeepLinkMatcher.match akan menampilkan null, sehingga pencocok berikutnya dapat dievaluasi.

Pertimbangkan class kunci dan matcher yang dikonfigurasi dengan nilai default, objek bertingkat, dan enum:

enum class MapLayer { STANDARD, SATELLITE, TERRAIN }

@Serializable
data class LayerOptions(
    val style: String,
    val layer: MapLayer = MapLayer.STANDARD
)

@Serializable
data class MapKey(
    val location: String,
    val zoom: Int = 12,
    val options: LayerOptions
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/map/{location}?zoom={zoom}&style={style}&layer={layer}"),
    serializer<MapKey>()
)
UriMatcherSnippets.kt

Tabel berikut menunjukkan hasil pencocokan untuk berbagai URI permintaan:

Konfigurasi yang tidak didukung

Jika class kunci Anda berisi jenis data yang tidak didukung, UriDeepLinkMatcher akan menampilkan pengecualian selama pencocokan, bukan menampilkan null.

• Peta dan koleksi multi-dimensi: UriDeepLinkMatcher hanya mendukung koleksi satu dimensi dari jenis primitif, string, enum, atau jenis kustom yang dianotasi dengan DeepLinkSerializer. Jenis Map menampilkan IllegalArgumentException, sedangkan koleksi bertingkat (seperti List<List<String>>) menampilkan SerializationException.
• Koleksi objek kustom tanpa anotasi: Koleksi jenis kustom (seperti List<Filter>) menampilkan SerializationException kecuali jika jenis elemen diberi anotasi dengan DeepLinkSerializer.
• Class bertingkat yang tidak di-unflatten: Class @Serializable bertingkat tidak dapat dipetakan ke satu placeholder (seperti ?user={user}) tanpa DeepLinkSerializer.

// Throws IllegalArgumentException: Map decoding is not supported.
@Serializable
data class InvalidKey(val tags: Map<String, String>) : NavKey
// Throws SerializationException: Only collections of primitives are supported.
@Serializable
data class InvalidKey(val filters: List<Filter>) : NavKey
UriMatcherSnippets.kt

Perbandingan UriMatchResult

Instance UriMatchResult diberi peringkat menggunakan kriteria berikut secara berurutan:

1. Jenis MatchResult: UriMatchResult memiliki peringkat lebih tinggi daripada jenis MatchResult lainnya.
2. Jalur persis: Kecocokan jalur literal memiliki peringkat lebih tinggi daripada kecocokan placeholder atau karakter pengganti.
3. Jumlah argumen jalur: Kecocokan dengan lebih banyak argumen jalur akan memiliki peringkat lebih tinggi.
4. Keberadaan argumen: Pencocokan yang menangkap argumen memiliki peringkat lebih tinggi daripada yang tidak.
5. Jumlah total argumen: Jumlah total argumen (jalur, kueri, fragmen) adalah penentu akhir.

Sesuaikan UriDeepLinkMatcher

UriDeepLinkMatcher adalah class open yang dapat Anda buat subclass-nya untuk menyesuaikan perilaku pencocokan URI dan ekstraksi argumen:

• matchRequest: Titik entri pencocokan tingkat teratas untuk DeepLinkRequest yang masuk. Ganti ini untuk memeriksa tambahan permintaan atau menerapkan prasyarat kustom sebelum pencocokan URI.
• matchUri: Mencocokkan DeepLinkUri dengan pola yang dikonfigurasi. Ganti ini untuk menangkap dan menormalisasi URI yang masuk (misalnya, menulis ulang subdomain dinamis atau format jalur lama) sebelum memanggil super.matchUri.
• matchArguments: Melakukan deserialisasi peta argumen jalur, kueri, dan fragmen yang diekstrak menjadi instance kunci navigasi menggunakan serializer yang disediakan. Ganti ini untuk memasukkan nilai dinamis atau mengubah argumen sebelum pembuatan instance kunci.

Contoh berikut menunjukkan subclassing UriDeepLinkMatcher untuk menormalisasi awalan jalur URL lama sebelum pencocokan:

class LegacyPrefixUriDeepLinkMatcher<T : Any>(
    uriPattern: DeepLinkUri,
    serializer: KSerializer<T>
) : UriDeepLinkMatcher<T>(uriPattern, serializer) {

    override fun matchUri(uri: DeepLinkUri): UriMatchResult<T>? {
        val path = uri.path
        val normalizedUri = if (path != null && path.startsWith("/legacy/")) {
            DeepLinkUri(uri.toString().replaceFirst("/legacy", ""))
        } else {
            uri
        }
        return super.matchUri(normalizedUri)
    }
}
UriMatcherSnippets.kt