Create DeepLinkMatcher instances

To map incoming DeepLinkRequest instances to keys that can be added to your app's back stack, you define DeepLinkMatcher instances.

DeepLinkMatcher is an abstract class that includes two methods, match and matchRequest. Subclasses must implement matchRequest, which takes a DeepLinkRequest and returns a DeepLinkMatcher.MatchResult if the request matches, or null otherwise.

Because multiple matchers might match a single request, MatchResult implements Comparable to rank results and select the best match.

Type parameters

The DeepLinkMatcher class declares two generic type parameters: DeepLinkMatcher<T : Any, R : DeepLinkMatcher.MatchResult<T>>.

T : Any: The destination navigation key type (such as UserProfileKey or NavKey) returned when the deep link matches.
R : DeepLinkMatcher.MatchResult<T>: The specific MatchResult subtype returned by matchRequest and match.

The second type parameter, R, preserves specialized match information without requiring unchecked downcasting:

StaticKeyDeepLinkMatcher binds R to DeepLinkMatcher.MatchResult<T>.
UriDeepLinkMatcher binds R to UriMatchResult, retaining parsed path and query arguments alongside pattern-matching scores.
BackStackMatcher binds R to BackStackMatchResult, retaining the synthetic back stack list constructed by withBackStack.

Pre-filter requests

DeepLinkMatcher implementations can specify a list of DeepLinkMatcher.Filter instances to filter requests before evaluating them.

The library includes helper functions to create common filters:

DeepLinkMatcher.mimeTypeFilter: Matches by exact mimeType strings (checks MimeTypeExtrasKey).
DeepLinkMatcher.actionFilter: Matches by exact action strings (checks ActionExtrasKey).

This approach lets you reuse the same URI pattern for different actions, such as viewing versus editing:

val viewFilter = DeepLinkMatcher.actionFilter(Intent.ACTION_VIEW)
val editFilter = DeepLinkMatcher.actionFilter(Intent.ACTION_EDIT)

val imageUriPattern = DeepLinkUri("www.example.com/image/{id}")

val viewMatcher = UriDeepLinkMatcher(imageUriPattern, serializer<Gallery>(), filters = listOf(viewFilter))
val editMatcher = UriDeepLinkMatcher(imageUriPattern, serializer<Editor>(), filters = listOf(editFilter))CreateMatchersSnippets.kt

Because Filter is a functional (SAM) interface, you can also create filters using lambda expressions:

val myFilter = DeepLinkMatcher.Filter { request -> request.uri != null }CreateMatchersSnippets.kt

Use provided matchers

The library includes three standard DeepLinkMatcher implementations: StaticKeyDeepLinkMatcher, UriDeepLinkMatcher, and BackStackMatcher. If these matchers don't meet your app's requirements, you can create custom deep link matchers.

Match basic deep links

For basic deep links that don't have arguments to extract, use StaticKeyDeepLinkMatcher to match requests that meet all provided filters.

For example, to handle intents for ACTION_APPLICATION_PREFERENCES:

val preferencesActionFilter = DeepLinkMatcher.actionFilter(Intent.ACTION_APPLICATION_PREFERENCES)

val preferencesActionDeepLinkMatcher = StaticKeyDeepLinkMatcher(PreferencesScreen, listOf(preferencesActionFilter))CreateMatchersSnippets.kt

Match URI deep links

For matching hierarchical URIs against patterns and extracting arguments, use UriDeepLinkMatcher. For example, you can match www.example.com/users/{id} to extract the id argument into a destination key. For more information, see Match URI deep links.

Build a synthetic back stack

To define how to build a synthetic back stack from a successful match, use BackStackMatcher. Rather than instantiating BackStackMatcher directly, call the withBackStack extension function on another DeepLinkMatcher. withBackStack wraps the receiver in a BackStackMatcher that returns a BackStackMatchResult containing a synthetic back stack List. Because BackStackMatchResult delegates comparison to the underlying match result, wrapping a matcher in withBackStack preserves its original match ranking.

val homeMatcher = StaticKeyDeepLinkMatcher(HomeKey, listOf(DeepLinkMatcher.actionFilter(Intent.ACTION_VIEW)))

val userListMatcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/users?page={page}"),
    serializer<UserListKey>()
).withBackStack { matchResult ->
    listOf(HomeKey, matchResult.key)
}

val userProfileMatcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/users/{id}"),
    serializer<UserProfileKey>()
).withBackStack { matchResult ->
    listOf(HomeKey, UserListKey(), matchResult.key)
}CreateMatchersSnippets.kt

To handle the resulting back stack in your activity, see Match an incoming request.