Known direct subclasses
BackStackMatcher

A DeepLinkMatcher that builds a back stack when match succeeds.
StaticKeyDeepLinkMatcher

A DeepLinkMatcher that matches based on a list of Filter and if all filters match, returns the input key in the MatchResult.
UriDeepLinkMatcher

A DeepLinkMatcher implementation that matches based on DeepLinkUri.

Represents a deep link that can be deep linked into when matched with a DeepLinkRequest. Each matcher is associated with a navigation key that supports this deep link.

A navigation key can be associated with more than one DeepLinkMatcher if it supports different forms of deep links.

T The type of the navigation key associated with this deep link.

R The type of the DeepLinkMatcher.MatchResult returned by this deep link.

Summary

Nested types

A filter for a deep link, such as a mimeType.

The class that is returned when a DeepLinkMatcher matches with a DeepLinkRequest

Public companion functions
DeepLinkMatcher.Filter

Creates a DeepLinkMatcher.Filter that filters a DeepLinkRequest with the mimeType defined on the DeepLinkMatcher.
Cmn

Public constructors
Cmn

Public functions
R?

Matches a DeepLinkRequest to a DeepLinkMatcher.
Cmn

Protected functions
abstract R?

Matches a DeepLinkRequest to a DeepLinkMatcher.
Cmn

Extension functions
BackStackMatcher<T, K>
<T : K, K : Any> DeepLinkMatcher<T, DeepLinkMatcher.MatchResult<T>>.withBackStack(
    backStackBuilder: (matchResult: DeepLinkMatcher.MatchResult<T>) -> List<K>
)

Returns a BackStackMatcher which wraps this DeepLinkMatcher to build a back stack upon matching.
Cmn

Public companion functions

mimeTypeFilter

Cmn
Added in 1.2.0-alpha07
fun mimeTypeFilter(mimeType: String): DeepLinkMatcher.Filter

Creates a DeepLinkMatcher.Filter that filters a DeepLinkRequest with the mimeType defined on the DeepLinkMatcher. Matching is not case-sensitive.

Parameters
mimeType: String

the action the filter by
Returns
DeepLinkMatcher.Filter

true if the mimeType exactly matches the DeepLinkMatcher's action or if the matcher did not define any actions, false otherwise.

Public constructors

DeepLinkMatcher

Cmn 
<T : Any, R : DeepLinkMatcher.MatchResult<T>> DeepLinkMatcher(
    filters: List<DeepLinkMatcher.Filter> = emptyList()
)
Parameters
filters: List<DeepLinkMatcher.Filter> = emptyList()

an optional list of Filter to apply to the DeepLinkRequest during matching

Public functions

match

Cmn
Added in 1.2.0-alpha07
fun match(request: DeepLinkRequest): R?

Matches a DeepLinkRequest to a DeepLinkMatcher.

The entry point to match a DeepLinkMatcher to a DeepLinkRequest. It iterates through any filters and if all filters returns true, proceeds to call matchRequest to get the final match result.

R The type of the DeepLinkMatcher.MatchResult returned by this deep link.

Returns R if it is a match, and returns null otherwise.

Parameters
request: DeepLinkRequest

the DeepLinkRequest to match against

Protected functions

matchRequest

Cmn
Added in 1.2.0-alpha07
protected abstract fun matchRequest(request: DeepLinkRequest): R?

Matches a DeepLinkRequest to a DeepLinkMatcher.

The core function that is called within the matching process after all filters are applied. Subclasses should override this to implement matching logic beyond matching filters.

Returns MatchResult if it is a match, and returns null otherwise.

Parameters
request: DeepLinkRequest

the DeepLinkRequest to match against

Extension functions

DeepLinkMatcher.withBackStack

Cmn 
fun <T : K, K : Any> DeepLinkMatcher<T, DeepLinkMatcher.MatchResult<T>>.withBackStack(
    backStackBuilder: (matchResult: DeepLinkMatcher.MatchResult<T>) -> List<K>
): BackStackMatcher<T, K>

Returns a BackStackMatcher which wraps this DeepLinkMatcher to build a back stack upon matching.

When this matcher matches a DeepLinkRequest, backStackBuilder is invoked with the DeepLinkMatcher.MatchResult to construct the back stack.

T the type of the navigation key associated with this matcher, must be of type K the element type of the back stack List

import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.deeplink.BackStackMatchResult
import androidx.navigation3.runtime.deeplink.DeepLinkMatcher
import androidx.navigation3.runtime.deeplink.DeepLinkRequest
import androidx.navigation3.runtime.deeplink.DeepLinkUri
import androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher
import androidx.navigation3.runtime.deeplink.withBackStack

val matcher =
    UriDeepLinkMatcher(
            uriPattern = DeepLinkUri("https://www.nav3deeplinksample.com/userlist"),
            serializer = serializer<UserListKey>(),
        )
        .withBackStack { matchResult -> listOf(HomeKey, matchResult.key) }

// handling a request
val request = DeepLinkRequest(uri = DeepLinkUri("https://www.nav3deeplinksample.com/userlist/"))
// returns a BackStackMatchResult containing the matched key and the constructed back stack
val matchResult: BackStackMatchResult<UserListKey, NavKey>? = matcher.match(request)
// listOf(HomeKey, UserListKey)
val backStack: List<NavKey>? = matchResult?.backStack
val key: UserListKey? = matchResult?.key
 
import androidx.navigation3.runtime.NavKey
import androidx.navigation3.runtime.deeplink.BackStackMatchResult
import androidx.navigation3.runtime.deeplink.DeepLinkMatcher
import androidx.navigation3.runtime.deeplink.DeepLinkRequest
import androidx.navigation3.runtime.deeplink.DeepLinkUri
import androidx.navigation3.runtime.deeplink.UriDeepLinkMatcher
import androidx.navigation3.runtime.deeplink.withBackStack

val matcher =
    UriDeepLinkMatcher(
            uriPattern = DeepLinkUri("https://www.nav3deeplinksample.com/articles/{id}"),
            serializer = serializer<Article>(),
        )
        .withBackStack { matchResult ->
            val article = matchResult.key
            val parent =
                if (article.id >= 10) ArticleSection("Shipping") else ArticleSection("Returns")
            listOf(parent, article)
        }

// handling a request
val request =
    DeepLinkRequest(uri = DeepLinkUri("https://www.nav3deeplinksample.com/articles/12"))

// returns a BackStackMatchResult containing the Article key and parent key based on article id
val matchResult: BackStackMatchResult<Article, NavKey>? = matcher.match(request)
// listOf(parent, article)
val backStack: List<NavKey>? = matchResult?.backStack
val key: Article? = matchResult?.key
Parameters
backStackBuilder: (matchResult: DeepLinkMatcher.MatchResult<T>) -> List<K>

lambda used to construct the back stack from the DeepLinkMatcher.MatchResult
Returns
BackStackMatcher<T, K>

a BackStackMatcher wrapping this matcher