androidx.navigation3.runtime.deeplink

Interfaces

DeepLinkMatcher.Filter

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

The base Key associated with a value of type T.
Cmn

Classes

BackStackMatchResult

Result returned when a BackStackMatcher successfully matches a DeepLinkRequest.
Cmn
BackStackMatcher

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

Represents a deep link that can be deep linked into when matched with a DeepLinkRequest.
Cmn
DeepLinkMatcher.MatchResult

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

Represents a requested deep link.
Cmn
DeepLinkSerializer

A KSerializer abstract implementation that encodes and decodes T as a String.
Cmn
DeepLinkUri

see android.net.Uri
Cmn
android
RequestExtras

A map-like class that stores key-value pairs of RequestExtrasKey to its associated value for use as DeepLinkRequest.extras.
Cmn
RequestExtrasScope

Scope provided to the requestExtras dsl builder.
Cmn
StaticKeyDeepLinkMatcher

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

A DeepLinkMatcher implementation that matches based on DeepLinkUri.
Cmn
UriMatchResult

The class that is returned when a UriDeepLinkMatcher matches with a DeepLinkRequest
Cmn
WrappedMatchResult

A DeepLinkMatcher.MatchResult implementation that wraps another MatchResult.
Cmn

Objects

DeepLinkMatcher.Companion
Cmn
DeepLinkRequest.Companion
Cmn
DeepLinkRequest.Companion.MimeTypeExtrasKey

The RequestExtrasKey for the mimeType stored inside the RequestExtras returned by mimeTypeExtra.
Cmn

Annotations

RequestExtrasDsl
Cmn

Type aliases

DeepLinkUri

see android.net.Uri
android

Top-level functions summary

DeepLinkUri
DeepLinkUri(uriString: String)

Creates a DeepLinkUri which parses the given encoded URI string.
Cmn
RequestExtras

Returns an empty RequestExtras.
Cmn
inline RequestExtras

Provides a RequestExtrasScope to build a RequestExtras for a DeepLinkRequest.
Cmn

Extension functions summary

RequestExtras

Returns a RequestExtras that stores the provided actionExtra with the key ActionExtrasKey.
android
DeepLinkMatcher.Filter

Creates a DeepLinkMatcher.Filter that filters a DeepLinkRequest with the action.
android
operator DeepLinkRequest

Creates a DeepLinkRequest with an Intent.
android
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

Extension properties summary

RequestExtrasKey<String>

The RequestExtrasKey for the Action stored inside the RequestExtras returned by actionExtra.
android
RequestExtrasKey<Bundle>

The RequestExtrasKey for the Intent.extras stored in DeepLinkRequest.extras when the Request is created with DeepLinkRequest.Companion.invoke factory method.
android

Top-level functions

DeepLinkUri

Cmn 
fun DeepLinkUri(uriString: String): DeepLinkUri

Creates a DeepLinkUri which parses the given encoded URI string.

Parameters
uriString: String

an RFC 2396-compliant, encoded URI
Returns
DeepLinkUri

NavUri for this given uri string

emptyRequestExtras

Cmn 
fun emptyRequestExtras(): RequestExtras

Returns an empty RequestExtras.

requestExtras

Cmn 
inline fun requestExtras(builder: RequestExtrasScope.() -> Unit): RequestExtras

Provides a RequestExtrasScope to build a RequestExtras for a DeepLinkRequest.

Parameters
builder: RequestExtrasScope.() -> Unit

the DSL that provides a RequestExtrasScope to build a RequestExtras

Extension functions

DeepLinkRequest.Companion.actionExtra

android 
fun DeepLinkRequest.Companion.actionExtra(action: String): RequestExtras

Returns a RequestExtras that stores the provided actionExtra with the key ActionExtrasKey.

The value can be retrieved via extras[ActionExtrasKey].

DeepLinkMatcher.Companion.actionFilter

android 
fun DeepLinkMatcher.Companion.actionFilter(action: String): DeepLinkMatcher.Filter

Creates a DeepLinkMatcher.Filter that filters a DeepLinkRequest with the action. Matching is case-insensitive.

Parameters
action: String

the action the filter by
Returns
DeepLinkMatcher.Filter

true if the DeepLinkRequest's Action exactly matches the action, false if the request's Action does not match or if the request does not provide any Action.

DeepLinkRequest.Companion.invoke

android 
operator fun DeepLinkRequest.Companion.invoke(
    intent: Intent,
    extras: RequestExtras = emptyRequestExtras()
): DeepLinkRequest

Creates a DeepLinkRequest with an Intent.

The returned DeepLinkRequest will be populated with the following data:

  1. DeepLinkRequest.uri will be Intent.getData if not null

  2. DeepLinkRequest.extras will contain any non-null information from Intent.getType, Intent.getAction, and Intent.getExtras.

Parameters
intent: Intent

The Intent with the metadata to construct a DeepLinkRequest
extras: RequestExtras = emptyRequestExtras()

The RequestExtras holding key-value pairs of RequestExtrasKey<T> to T to provide extra information to the DeepLinkRequest. If extras contains an Action stored under ActionExtrasKey or a MimeType stored under MimeTypeExtrasKey, their values will override any Action or MimeType stored in the intent.
Returns
DeepLinkRequest

a DeepLinkRequest instance

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

Extension properties

DeepLinkRequest.Companion.ActionExtrasKey

android 
val DeepLinkRequest.Companion.ActionExtrasKey: RequestExtrasKey<String>

The RequestExtrasKey for the Action stored inside the RequestExtras returned by actionExtra.

DeepLinkRequest.Companion.IntentExtrasKey

android 
val DeepLinkRequest.Companion.IntentExtrasKey: RequestExtrasKey<Bundle>

The RequestExtrasKey for the Intent.extras stored in DeepLinkRequest.extras when the Request is created with DeepLinkRequest.Companion.invoke factory method.

The android.os.Bundle is stored as a SavedState.