DO NOT MERGE Add deeplink recipe for single module #97

claraf3 · 2025-10-10T21:08:49Z

A recipe that shows how to parse a requested deeplink into a backStack key. It demonstrates a few crucial steps:

STEP 1.Parse supported deeplinks (URLs that can be deeplinked into) into a readily readable format (see [DeepLinkCandidate])

STEP 2. Parse the requested deeplink into a readily readable format (see [DeepLinkTarget])
note the parsed requested deeplink and parsed supported deeplinks should be cohesive with each other to facilitate comparison and finding a match

STEP 3. Compare the requested deeplink target with supported deeplinks in order to find a match (see [DeepLinkMatchResult]). The match result's format should enable conversion from result to backstack key, regardless of what the conversion method may be.

STEP 4. Associate the match results with the correct backstack key

This recipes provides an example for each of the above steps by way of kotlinx.serialization.

Note that this recipe is designed to focus on parsing an intent into a key, and therefore the following deeplink considerations are not included in this scope:

Create synthetic backStack
Multi-modular setup
DI
Managing Task back stack
Up button ves Back Button

Those topics will be covered in follow up PRs.

gemini-code-assist · 2025-10-10T21:09:15Z

Summary of Changes

Hello @claraf3, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request adds a new recipe to the application, focusing on the robust parsing of Android deeplinks within a single-module setup. The recipe illustrates a structured approach to defining, matching, and interpreting deeplink URLs, converting them into serializable navigation keys. It highlights the use of kotlinx.serialization for argument deserialization and includes an interactive UI to facilitate testing of different deeplink patterns.

Highlights

New Deeplink Parsing Recipe: Introduces a comprehensive example demonstrating how to parse incoming Android deeplinks into strongly-typed NavKey objects for navigation within a single-module application.
Structured Parsing Logic: Implements a four-step process involving DeepLinkCandidate for supported patterns, DeepLinkTarget for requested URIs, DeepLinkMatchResult for comparison, and KeyDecoder for converting arguments into NavKey instances.
kotlinx.serialization Integration: Leverages kotlinx.serialization for efficient and type-safe handling of deeplink arguments, mapping them directly to serializable NavRecipeKey data classes.
Interactive Sandbox UI: Provides a ParseIntentLandingActivity that acts as a sandbox, allowing users to construct and test various deeplink URLs with different path and query parameters.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

claraf3 · 2025-10-10T21:09:19Z

Ready for initial review.

gemini-code-assist

Code Review

This pull request introduces a new recipe for parsing deeplinks. The implementation is well-structured, demonstrating the key steps from parsing a URL to resolving it into a backstack key. However, I've found several critical issues, particularly in AndroidManifest.xml and DeepLinkUtil.kt, that will cause deeplinks to fail or the app to crash. There are also opportunities to improve code robustness and readability. Please review the detailed comments for suggestions.

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/DeepLinkUtil.kt

app/src/main/AndroidManifest.xml

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/DeepLinkUtil.kt

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt

app/src/main/java/com/example/nav3recipes/deeplink/basic/CreateDeepLinkActivity.kt

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonResources.kt

app/src/main/AndroidManifest.xml

...c/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/ParseIntentActivity.kt

A recipe that shows how to parse a requested deeplink into a backStack key. It demonstrates a few crucial steps: STEP 1.Parse supported deeplinks (URLs that can be deeplinked into) into a readily readable format (see [DeepLinkCandidate]) STEP 2. Parse the requested deeplink into a readily readable, format (see [DeepLinkTarget]) **note** the parsed requested deeplink and parsed supported deeplinks should be cohesive with each other to facilitate comparison and finding a match STEP 3. Compare the requested deeplink target with supported deeplinks in order to find a match (see [DeepLinkMatchResult]). The match result's format should enable conversion from result to backstack key, regardless of what the conversion method may be. STEP 4. Associate the match results with the correct backstack key This recipes provides an example for each of the above steps by way of kotlinx.serialization. Note that this recipe is designed to focus on parsing an intent into a key, and therefore the following deeplink considerations are not included in this scope: - Create synthetic backStack - Multi-modular setup - DI - Managing TaskStack - Up button ves Back Button

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt

jbw0033 · 2025-10-14T16:17:12Z

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt

+import androidx.navigation3.runtime.NavKey
+import kotlinx.serialization.Serializable
+
+internal interface NavRecipeKey: NavKey {


I think we can be more specific here by calling this a NavDeepLinkKey.

Could that confuse people into thinking all those keys support deep link?

But you're right, the naming could be better. What about

DeepLinkRecipeKey
BasicDeepLinkRecipeKey

zzz...
Although I have refactored upperbound from NavRecipeKey to NavKey so the name NavRecipeKey shows up lot less now.

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt

jbw0033

With the current organization it is not immediately clear to me which part developers should be copying to implement their own deep links vs what is specific to this App.

Some ideas I think that might help this for me:

Splitting the DeepLinkUtil file up into separate files for each component. Maybe DeepLinkRequest and DeepLinkMatchResult in one. DeepLink in another. Then KeyDecoder in its own as well.
Having NavRecipeKey in its own file separate from the specific implementations.

dturner

Great to see this coming together. In case it's useful I created a branch with a few of the changes I suggested here: abb9300#diff-b49bfd99d5a52d31e22d0e0fc0d6b6ec029f048a1b665000bfb967efef6ded02

dturner · 2025-10-22T16:53:59Z

app/src/main/java/com/example/nav3recipes/RecipePickerActivity.kt

 import com.example.nav3recipes.basicsaveable.BasicSaveableActivity
 import com.example.nav3recipes.commonui.CommonUiActivity
 import com.example.nav3recipes.conditional.ConditionalActivity
+import com.example.nav3recipes.deeplink.parseintent.singleModule.ParseIntentLandingActivity


The package name could just be com.example.nav3recipes.deeplinks and all the library code could be placed in a subpackage say common or library. We could make it clear that to add deeplinks to your app you can just copy the library package into your own app. WDYT?

I think it is really important for each recipe to stand on its own - the simple example should include only simple code.

Trying to make just a single shared library means that to understand even what the simple recipe is doing you have to understand a library that handles way more than what is needed for that recipe.

I do think we should separate the recipe into the activity code (e.g., the example of how to use it) from the library code (e.g., what we expect developers to use in their own app if they want to 'adopt' that specific recipe).

Updated with

1. Simplified the base package from "deeplink.parseIntent.singleModule" to "deeplink.basic". 2. Added `ui` and `deeplinkutil` packages to separate sample ui code from parsing/matching helpers

WDYT?

You can simplify deeplinkutil to just util since it's a subpackage of deeplink.basic

...java/com/example/nav3recipes/deeplink/parseintent/singleModule/ParseIntentLandingActivity.kt

...c/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/ParseIntentActivity.kt

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt

dturner · 2025-10-22T18:32:56Z

app/src/main/java/com/example/nav3recipes/deeplink/basic/ui/CommonResources.kt

+/**
+ * String resources
+ */
+internal const val STRING_LITERAL_FILTER = "filter"


It looks like a lot of this data is associated with the navigation keys. Would it be possible to move it into those keys rather than having global constants file?

For the test data it's fine, but for everything associated with specifying the deeplinks it'd be good to see these declared in line with the key itself.

dturner · 2025-10-22T18:57:34Z

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt

+import androidx.navigation3.runtime.NavKey
+import kotlinx.serialization.Serializable
+
+internal interface NavRecipeKey: NavKey {


I'm not sure that inheritance is the right approach here. Not all keys will have deeplinks. It might be better to have routes/keys implement an optional DeepLink interface through their companion object. For example:

internal interface DeepLink { val name: String } @Serializable internal data class UsersKey( val filter: String, ): NavKey { companion object : DeepLink { const val FILTER_KEY = STRING_LITERAL_FILTER const val FILTER_OPTION_RECENTLY_ADDED = "recentlyAdded" const val FILTER_OPTION_ALL = "all" override val name: String = STRING_LITERAL_USERS } }

It inherits NavKey only to get free save/restore from rememberNavBackKey().

This recipe intentionally keeps the inheritance simple - you can either inherit NavKey for free save/restore, or even inherit nothing at all.

But you're right that more advanced use cases could benefit from inheritance, i.e. for building synthetic backStack, for more efficient parsing and matching. That will come with the follow up recipes.

dturner · 2025-10-22T19:03:07Z

...c/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/ParseIntentActivity.kt

+ */
+class ParseIntentActivity : ComponentActivity() {
+    /** STEP 1. Parse supported deeplinks */
+    private val deepLinkCandidates: List<DeepLink<out NavRecipeKey>> = listOf(


This feels like it could be improved. As a user of the deeplink API, ideally I don't want to do anything aside from mark my keys as having a deeplink by implementing an interface. I'm guessing it's not possible to obtain a list of objects that implement an interface (although maybe with a plugin? and/or with an annotation?). In which case, I would like to just specify the list of keys that have deep links.

Is it possible to do this work inside the library just by specifying a list of keys?

That would be part of the more advanced recipes i.e. with mulitple modules. The current idea for that would be for each module to inject something into the common module that indicates:

That it supports a deep link

The type of deeplink it supports

How to match and map to its key

Annotations could be one way. But i'll likely go with DI as it's still simpler than annotations (IMO). We could consider expanding recipes in the future with more alternatives.

dturner · 2025-10-22T19:04:03Z

...c/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/ParseIntentActivity.kt

+        // retrieve the target Uri
+        val uri: Uri? = intent.data
+        // associate the target with the correct backstack key
+        val key: NavKey = uri?.let {


You could move this into a Uri extension function that takes the list of candidates

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/DeepLinkUtil.kt

Rename activites, classes, and parameters.

claraf3 · 2025-10-24T21:33:49Z

With the current organization it is not immediately clear to me which part developers should be copying to implement their own deep links vs what is specific to this App.

Some ideas I think that might help this for me:

Splitting the DeepLinkUtil file up into separate files for each component. Maybe DeepLinkRequest and DeepLinkMatchResult in one. DeepLink in another. Then KeyDecoder in its own as well.

Having NavRecipeKey in its own file separate from the specific implementations.

Done 1. But moved the keys into the Screens file per your other comment.

1. Simplified the base package from "deeplink.parseIntent.singleModule" to "deeplink.basic". 2. Added `ui` and `deeplinkutil` packages to separate sample ui code from parsing/matching helpers 3. Separate classes within DeepLinkUtil into their own separate files 4. Separate DeepLinkRequest into two separate classes - DeepLinkRequest: parse uri and store parse result - DeepLinkMatcher: takes a request + pattern and matches the two 5. Change type <T> upper bound to NavKey to make the helpers more general Other misc non-structural changes: 1. Added kdocs in CreateDeepLinkActivity to explain how this recipe works 2. inlined String parsers into #getTypeParser

galex · 2025-11-02T11:48:10Z

app/src/main/java/com/example/nav3recipes/deeplink/basic/MainActivity.kt

+        // retrieve the target Uri
+        val uri: Uri? = intent.data
+        // associate the target with the correct backstack key
+        val key: NavKey = uri?.let {


May I ask what is planned for supporting passing deep links from onNewIntent to this mechanism? Meaning, what would be the equivalent of this?

dturner · 2025-11-03T11:52:30Z

app/src/main/java/com/example/nav3recipes/deeplink/basic/deeplinkutil/KeyDecoder.kt

+import kotlinx.serialization.modules.SerializersModule
+
+/**
+ * Decodes the list of arguments into a a backstack key


Suggested change

* Decodes the list of arguments into a a backstack key

* Decodes the list of arguments into a back stack key

claraf3 requested review from dturner, ianhanniballake and jbw0033 as code owners October 10, 2025 21:08

gemini-code-assist bot reviewed Oct 10, 2025

View reviewed changes

claraf3 force-pushed the basic-deeplink-new-design branch 2 times, most recently from 1bae1b4 to d22b204 Compare October 10, 2025 22:06

claraf3 force-pushed the basic-deeplink-new-design branch from d22b204 to 5c6e910 Compare October 13, 2025 18:24

jbw0033 reviewed Oct 14, 2025

View reviewed changes

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/CommonScreens.kt Outdated Show resolved Hide resolved

jbw0033 reviewed Oct 14, 2025

View reviewed changes

app/src/main/java/com/example/nav3recipes/deeplink/parseintent/singleModule/NavRecipeKey.kt Outdated Show resolved Hide resolved

jbw0033 reviewed Oct 14, 2025

View reviewed changes

langsmith mentioned this pull request Oct 20, 2025

Provide a mechanism that allows users to deeplink to a specific destination in their app. #40

Open

dturner reviewed Oct 22, 2025

View reviewed changes

claraf3 self-assigned this Oct 24, 2025

claraf3 requested a review from marcellogalhardo October 24, 2025 16:32

marcellogalhardo reviewed Oct 24, 2025

View reviewed changes

Merge branch 'android:main' into basic-deeplink-new-design

6f6717a

claraf3 force-pushed the basic-deeplink-new-design branch 2 times, most recently from 099671a to 03bc869 Compare October 24, 2025 20:46

Address the simpler feedbacks

68c060d

Rename activites, classes, and parameters.

claraf3 force-pushed the basic-deeplink-new-design branch from 03bc869 to 68c060d Compare October 24, 2025 20:51

claraf3 force-pushed the basic-deeplink-new-design branch from a9dc248 to 48ec2ad Compare October 24, 2025 21:57

claraf3 requested review from dturner, jbw0033 and marcellogalhardo October 24, 2025 22:03

galex reviewed Nov 2, 2025

View reviewed changes

dturner reviewed Nov 3, 2025

View reviewed changes

	* Decodes the list of arguments into a a backstack key
	* Decodes the list of arguments into a back stack key

**DO NOT MERGE** Add deeplink recipe for single module #97

Are you sure you want to change the base?

**DO NOT MERGE** Add deeplink recipe for single module #97

Uh oh!

Conversation

claraf3 commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Oct 10, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

claraf3 commented Oct 10, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claraf3 Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jbw0033 left a comment

Choose a reason for hiding this comment

Uh oh!

dturner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

claraf3 Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

claraf3 commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

DO NOT MERGE Add deeplink recipe for single module #97

DO NOT MERGE Add deeplink recipe for single module #97

claraf3 commented Oct 10, 2025 •

edited

Loading

claraf3 Oct 24, 2025 •

edited

Loading

claraf3 Oct 24, 2025 •

edited

Loading