# DeepLinkMatcher

Artifact: [androidx.navigation3:navigation3-runtime](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/runtime/deeplink/DeepLinkMatcher.kt+class:androidx.navigation3.runtime.deeplink.DeepLinkMatcher) Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0) Common/AllAndroid/JVM
- Cmn

  ```
  abstract class DeepLinkMatcher<T : Any, R : DeepLinkMatcher.MatchResult<T>>
  ```
Known direct subclasses [BackStackMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher), [StaticKeyDeepLinkMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/StaticKeyDeepLinkMatcher), [UriDeepLinkMatcher](https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher)

|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` that builds a back stack when match succeeds. |
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/StaticKeyDeepLinkMatcher` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` that matches based on a list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` and if all filters match, returns the input `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/StaticKeyDeepLinkMatcher#(kotlin.Any,kotlin.collections.List)` in the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult`. |
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/UriDeepLinkMatcher` | A `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` implementation that matches based on `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkUri`. |

*** ** * ** ***

Represents a deep link that can be deep linked into when matched with a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`. Each matcher is associated with a navigation key that supports this deep link.

A navigation key can be associated with more than one `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` if it supports different forms of deep links.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` The type of the navigation key associated with this deep link.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` The type of the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` returned by this deep link.

## Summary

| ### Nested types |
|---|
| `object https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Companion` |
| `fun interface https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` A filter for a deep link, such as a mimeType. |
| `open class https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-comparable/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T>>` The class that is returned when a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` matches with a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` |

| ### Public companion functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#mimeTypeFilter(kotlin.String)(mimeType: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Creates a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` that filters a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` with the mimeType defined on the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. | Cmn |

| ### Public constructors |
|---|---|
| `<T : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html, R : https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T>> https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#DeepLinkMatcher(kotlin.collections.List)( filters: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter> )` | Cmn |

| ### Public functions |
|---|---|---|
| `R?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#match(androidx.navigation3.runtime.deeplink.DeepLinkRequest)(request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest)` Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. | Cmn |

| ### Protected functions |
|---|---|---|
| `abstract R?` | `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#matchRequest(androidx.navigation3.runtime.deeplink.DeepLinkRequest)(request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest)` Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. | Cmn |

| ### Extension functions |
|---|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher<T, K>` | `<T : K, K : https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html> https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher<T, https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T>>.https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#(androidx.navigation3.runtime.deeplink.DeepLinkMatcher).withBackStack(kotlin.Function1)( backStackBuilder: (matchResult: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T>) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<K> )` Returns a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` which wraps this `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` to build a back stack upon matching. | Cmn |

## Public companion functions

### mimeTypeFilter

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0)

```
fun mimeTypeFilter(mimeType: String): DeepLinkMatcher.Filter
```

Creates a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` that filters a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` with the mimeType defined on the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`. Matching is not case-sensitive.

| Parameters |
|---|---|
| `mimeType: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the action the filter by |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` | true if the mimeType exactly matches the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter> = emptyList()` | an optional list of `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.Filter` to apply to the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` during matching |

## Public functions

### match

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0)

```
fun match(request: DeepLinkRequest): R?
```

Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`.

The entry point to match a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`. It iterates through any `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()` and if all filters returns true, proceeds to call `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#matchRequest(androidx.navigation3.runtime.deeplink.DeepLinkRequest)` to get the final match result.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` The type of the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` returned by this deep link.

Returns `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` if it is a match, and returns null otherwise.

| Parameters |
|---|---|
| `request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` | the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to match against |

## Protected functions

### matchRequest

Cmn Added in [1.2.0](https://developer.android.com/jetpack/androidx/releases/navigation3#1.2.0)

```
protected abstract fun matchRequest(request: DeepLinkRequest): R?
```

Matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher`.

The core function that is called within the matching process after all `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()` are applied. Subclasses should override this to implement matching logic beyond matching `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher#filters()`.

Returns `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` if it is a match, and returns null otherwise.

| Parameters |
|---|---|
| `request: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` | the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest` to match against |

## Extension functions

### DeepLinkMatcher.withBackStack

Cmn Artifact: [androidx.navigation3:navigation3-runtime](https://developer.android.com/jetpack/androidx/releases/navigation3) [View Source](https://cs.android.com/search?q=file:androidx/navigation3/runtime/deeplink/BackStackMatcher.kt+function:withBackStack)

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

Returns a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` which wraps this `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher` to build a back stack upon matching.

When this matcher matches a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkRequest`, `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/package-summary#(androidx.navigation3.runtime.deeplink.DeepLinkMatcher).withBackStack(kotlin.Function1)` is invoked with the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` to construct the back stack.

`https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/package-summary#(androidx.navigation3.runtime.deeplink.DeepLinkMatcher).withBackStack(kotlin.Function1)` the type of the navigation key associated with this matcher, must be of type `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/package-summary#(androidx.navigation3.runtime.deeplink.DeepLinkMatcher).withBackStack(kotlin.Function1)` the element type of the back stack `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html`

```kotlin
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
```

```kotlin
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: https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult<T>) -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html<K>` | lambda used to construct the back stack from the `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/DeepLinkMatcher.MatchResult` |

| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher<T, K>` | a `https://developer.android.com/reference/kotlin/androidx/navigation3/runtime/deeplink/BackStackMatcher` wrapping this matcher |