DeepLinks - ADict Library

📖 Przegląd

Moduł DeepLinks pozwala na łatwą obsługę deep linków w aplikacji Android. Obsługuje wzorce URL z parametrami, walidację scheme i hostów oraz automatyczne wyciąganie parametrów z ścieżki i query string.

Szybki przykład

// Rejestracja handlera
ADict.DeepLinks.register("product/{id}") { params ->
    val productId = params["id"]
    openProduct(productId)
}

// W Activity.onCreate
ADict.DeepLinks.handle(intent)

⚙️ Konfiguracja

configure(schemes, hosts)

Skonfiguruj dozwolone schematy URI i hosty.

Parametry:

schemes: List<String> - Lista dozwolonych schematów (domyślnie: ["https", "http"])
hosts: List<String> - Lista dozwolonych hostów (pusta = wszystkie)

Przykład konfiguracji

// Konfiguracja dla aplikacji
ADict.DeepLinks.configure(
    schemes = listOf("https", "http", "myapp"),
    hosts = listOf("myapp.com", "www.myapp.com")
)

// Własny scheme (np. myapp://product/123)
ADict.DeepLinks.configure(
    schemes = listOf("myapp"),
    hosts = emptyList() // Wszystkie hosty
)

⚠️ Uwaga: Jeśli skonfigurujesz hosty, linki z innych hostów będą odrzucane. Pusta lista hostów oznacza akceptację wszystkich.

📝 Rejestracja handlerów

register(pattern, handler)

Zarejestruj handler dla wzorca URL.

Parametry:

pattern: String - Wzorzec URL z parametrami w nawiasach klamrowych
handler: (Map<String, String>) -> Unit - Callback z mapą parametrów

Składnia wzorców

Wzorzec	Przykładowy URL	Parametry
`product/{id}`	/product/123	`{"id": "123"}`
`user/{userId}/post/{postId}`	/user/42/post/99	`{"userId": "42", "postId": "99"}`
`search?q={query}`	/search?q=kotlin	`{"query": "kotlin"}`
`category/{cat}/item/{id}`	/category/electronics/item/456	`{"cat": "electronics", "id": "456"}`

Rejestracja wielu handlerów

// Strona produktu
ADict.DeepLinks.register("product/{id}") { params ->
    val productId = params["id"] ?: return@register
    navigateToProduct(productId)
}

// Profil użytkownika
ADict.DeepLinks.register("user/{userId}") { params ->
    val userId = params["userId"] ?: return@register
    navigateToProfile(userId)
}

// Post użytkownika
ADict.DeepLinks.register("user/{userId}/post/{postId}") { params ->
    val userId = params["userId"]
    val postId = params["postId"]
    navigateToPost(userId, postId)
}

// Wyszukiwanie z query params
ADict.DeepLinks.register("search") { params ->
    val query = params["q"] ?: ""
    val category = params["category"]
    searchProducts(query, category)
}

// Domyślny handler dla niedopasowanych linków
ADict.DeepLinks.setDefaultHandler { uri ->
    Log.d("DeepLinks", "Nieobsługiwany link: $uri")
    openWebView(uri.toString())
    true // true = obsłużono, false = nie obsłużono
}

unregister(pattern)

Usuń zarejestrowany handler.

Parametry:

pattern: String - Wzorzec do usunięcia

clear()

Wyczyść wszystkie zarejestrowane handlery i domyślny handler.

🔄 Obsługa linków

handle(intent: Intent?): DeepLinkResult

Obsłuż Intent zawierający deep link.

Parametry:

intent: Intent? - Intent z Activity

Zwraca:

DeepLinkResult - Wynik obsługi linku

handle(uri: Uri): DeepLinkResult

Obsłuż URI bezpośrednio.

handle(url: String): DeepLinkResult

Obsłuż string URL.

Obsługa w Activity

class MainActivity : AppCompatActivity() {

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

        // Obsługa deep linka z onCreate
        handleDeepLink(intent)
    }

    override fun onNewIntent(intent: Intent?) {
        super.onNewIntent(intent)
        // Obsługa deep linka gdy Activity jest już uruchomione
        intent?.let { handleDeepLink(it) }
    }

    private fun handleDeepLink(intent: Intent) {
        val result = ADict.DeepLinks.handle(intent)

        when {
            result.matched -> {
                Log.d("DeepLinks", "Dopasowano wzorzec: ${result.pattern}")
                Log.d("DeepLinks", "Parametry: ${result.params}")
            }
            result.uri != null -> {
                Log.d("DeepLinks", "Niedopasowany link: ${result.uri}")
            }
            else -> {
                Log.d("DeepLinks", "Brak deep linka w Intent")
            }
        }
    }
}

🧪 Testowanie

test(uri: Uri): DeepLinkResult

Testuj dopasowanie URL bez wykonywania handlera.

Parametry:

uri: Uri - URI do przetestowania

Zwraca:

DeepLinkResult - Wynik testu (bez wywołania handlera)

test(url: String): DeepLinkResult

Testuj dopasowanie string URL.

Testowanie dopasowań

// Testowanie bez wykonywania akcji
val result1 = ADict.DeepLinks.test("https://myapp.com/product/123")
println("Matched: ${result1.matched}")          // true
println("Pattern: ${result1.pattern}")          // "product/{id}"
println("Params: ${result1.params}")            // {id=123}

val result2 = ADict.DeepLinks.test("https://myapp.com/unknown/path")
println("Matched: ${result2.matched}")          // false

// Przydatne do unit testów
@Test
fun testProductDeepLink() {
    ADict.DeepLinks.register("product/{id}") { }

    val result = ADict.DeepLinks.test("https://myapp.com/product/456")

    assertTrue(result.matched)
    assertEquals("product/{id}", result.pattern)
    assertEquals("456", result.params["id"])
}

🔧 Budowanie URL

build(pattern, params, scheme, host): String

Wygeneruj deep link URL z wzorca i parametrów.

Parametry:

pattern: String - Wzorzec URL
params: Map<String, String> - Mapa parametrów
scheme: String - Schemat URL (domyślnie: "https")
host: String - Host URL (domyślnie: "")

Zwraca:

String - Wygenerowany URL

Budowanie URL

// Budowanie URL produktu
val productUrl = ADict.DeepLinks.build(
    pattern = "/product/{id}",
    params = mapOf("id" to "123"),
    scheme = "https",
    host = "myapp.com"
)
// Wynik: https://myapp.com/product/123

// Budowanie URL z wieloma parametrami
val postUrl = ADict.DeepLinks.build(
    pattern = "/user/{userId}/post/{postId}",
    params = mapOf("userId" to "42", "postId" to "99"),
    scheme = "myapp",
    host = ""
)
// Wynik: myapp:///user/42/post/99

// Bez hosta (relatywny URL)
val relativeUrl = ADict.DeepLinks.build(
    pattern = "/search?q={query}",
    params = mapOf("query" to "kotlin android")
)
// Wynik: /search?q=kotlin%20android

getRegisteredPatterns(): List<String>

Pobierz listę wszystkich zarejestrowanych wzorców.

Zwraca:

List<String> - Lista wzorców

📦 Klasy danych

data class DeepLinkResult

Wynik parsowania deep linka.

matched Boolean Czy link został dopasowany do wzorca
pattern String? Dopasowany wzorzec (null jeśli nie dopasowano)
params Map<String, String> Mapa wyciągniętych parametrów
uri Uri? Oryginalny URI

data class DeepLinkHandler

Wewnętrzna klasa reprezentująca zarejestrowany handler.

pattern String Oryginalny wzorzec
regex Pattern Skompilowany regex
paramNames List<String> Lista nazw parametrów
callback (Map<String, String>) -> Unit Funkcja callback

💡 Przykłady praktyczne

E-commerce App

Pełna konfiguracja dla sklepu

class ShopApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        ADict.init(this, BuildConfig.DEBUG)
        setupDeepLinks()
    }

    private fun setupDeepLinks() {
        ADict.DeepLinks.configure(
            schemes = listOf("https", "myshop"),
            hosts = listOf("myshop.com", "www.myshop.com")
        )

        // Produkt
        ADict.DeepLinks.register("product/{productId}") { params ->
            val productId = params["productId"] ?: return@register
            Navigator.navigateToProduct(productId)

            // Analytics
            ADict.Analytics.log("deep_link_product", mapOf(
                "product_id" to productId
            ))
        }

        // Kategoria
        ADict.DeepLinks.register("category/{categoryId}") { params ->
            val categoryId = params["categoryId"] ?: return@register
            Navigator.navigateToCategory(categoryId)
        }

        // Wyszukiwanie
        ADict.DeepLinks.register("search") { params ->
            val query = params["q"] ?: ""
            val category = params["category"]
            val sort = params["sort"] ?: "relevance"
            Navigator.navigateToSearch(query, category, sort)
        }

        // Koszyk
        ADict.DeepLinks.register("cart") { _ ->
            Navigator.navigateToCart()
        }

        // Promocja
        ADict.DeepLinks.register("promo/{code}") { params ->
            val promoCode = params["code"] ?: return@register
            applyPromoCode(promoCode)
            Navigator.navigateToCart()
        }

        // Domyślny handler
        ADict.DeepLinks.setDefaultHandler { uri ->
            // Otwórz w WebView dla nieznanych linków
            Navigator.navigateToWebView(uri.toString())
            true
        }
    }
}

Social Media App

Konfiguracja dla social media

private fun setupDeepLinks() {
    ADict.DeepLinks.configure(
        schemes = listOf("https", "socialapp"),
        hosts = listOf("socialapp.io")
    )

    // Profil użytkownika
    ADict.DeepLinks.register("user/{username}") { params ->
        val username = params["username"] ?: return@register
        viewModel.loadUserProfile(username)
    }

    // Profil po ID
    ADict.DeepLinks.register("users/{userId}") { params ->
        val userId = params["userId"] ?: return@register
        viewModel.loadUserProfileById(userId)
    }

    // Post
    ADict.DeepLinks.register("post/{postId}") { params ->
        val postId = params["postId"] ?: return@register
        viewModel.loadPost(postId)
    }

    // Post użytkownika
    ADict.DeepLinks.register("user/{username}/post/{postId}") { params ->
        val username = params["username"]
        val postId = params["postId"] ?: return@register
        viewModel.loadPost(postId)
    }

    // Hashtag
    ADict.DeepLinks.register("hashtag/{tag}") { params ->
        val tag = params["tag"] ?: return@register
        viewModel.searchByHashtag(tag)
    }

    // Wiadomość bezpośrednia
    ADict.DeepLinks.register("dm/{conversationId}") { params ->
        val conversationId = params["conversationId"] ?: return@register
        if (isLoggedIn()) {
            viewModel.openConversation(conversationId)
        } else {
            saveDeepLinkForAfterLogin()
            showLoginScreen()
        }
    }
}

Integracja z AndroidManifest

AndroidManifest.xml

<activity
    android:name=".MainActivity"
    android:launchMode="singleTask"
    android:exported="true">

    <!-- Standard launcher intent -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>

    <!-- HTTP/HTTPS deep links -->
    <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:scheme="https" />
        <data android:scheme="http" />
        <data android:host="myapp.com" />
        <data android:host="www.myapp.com" />
    </intent-filter>

    <!-- Custom scheme -->
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="myapp" />
    </intent-filter>
</activity>

📚 API Reference

Metoda	Opis	Zwraca
`configure(schemes, hosts)`	Konfiguruj dozwolone schematy i hosty	Unit
`register(pattern, handler)`	Zarejestruj handler dla wzorca	Unit
`unregister(pattern)`	Usuń handler	Unit
`setDefaultHandler(handler)`	Ustaw domyślny handler	Unit
`clear()`	Wyczyść wszystkie handlery	Unit
`handle(intent)`	Obsłuż Intent	DeepLinkResult
`handle(uri)`	Obsłuż URI	DeepLinkResult
`handle(url)`	Obsłuż string URL	DeepLinkResult
`test(uri)`	Testuj bez wykonywania	DeepLinkResult
`build(pattern, params, ...)`	Wygeneruj URL	String
`getRegisteredPatterns()`	Pobierz listę wzorców	List<String>