Request documentation for Navigation deeplink

[easyhooon]

Description

I'd like to request adding documentation about Navigation deeplink in the Circuit documentation.
This would help developers understand how to implement deep linking features in their applications.

It would be helpful if the documentation could include:

1. Basic concepts of Navigation deeplink
2. Implementation methods with example code
3. List of supported schemes
4. Parameter passing methods
5. Important considerations and limitations
6. Testing guidelines

Motivation

While browsing the Circuit documentation's Screen tab, I found the phrase "easy deeplinking". However, without any implementation examples or detailed explanations, it's difficult to understand what makes Circuit's deeplinking feature easy to use compared to alternatives.

Expected Outcome

Having this documentation would greatly help developers in understanding and implementing deep linking functionality using Circuit.

[ZacSweers]

This would be a new standalone doc page, or even a blog post. PRs are welcome. The doc reference you mention is emphasizing their Parcelable nature, as Android Intents require parcelable data and are the primary entry point of a deeplink.

[hossain-khan]

Recently, I was also looking into deeplinking to different screen using Circuit.

Base on my understanding, here is how I was able to kinda deep link to different screen.

Depending on where you create the Intent, add your screen to the bundle parameter

// Add the intent to `PendingIntent` if using notification or other relevant location
val intent =
    context.packageManager.getLaunchIntentForPackage(context.packageName)?.apply {
        flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP

        // `UserProfileDetailsScreen` is your circuit screen with params if applicable
        putExtra("destination_screen", UserProfileDetailsScreen(userId))
    }

Assuming app uses single entry point activity called MainActivity.

// In your `MainActivity`

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)

    handleDeepLink(intent)
}

private fun handleDeepLink(intent: Intent) {
    val destinationScreen =
        intent.extras?.let { bundle ->
            BundleCompat.getParcelable(
                bundle,
               "destination_screen", // bundle key for Circuit Screen
                Screen::class.java,
            )
        }
    if (destinationScreen != null) {
        navigator.goTo(destinationScreen)
    }
}

This worked fine when activity was alive in the background, the onNewIntent(intent: Intent) was called.

However, I am not sure how to modify the circuit initialization to create new stack from onCreate() to leverage the rememberSaveableBackStack(initialScreens: List<Screen>) circuit API.

For example, would something like this be ideal? 😕

// In your`MainActivity`
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)


    setContent {
        // ... code omitted for brevity
        
        val deepLinkScreen: Screen? = deepLinkScreen(intent?.extras)
        val backStack: SaveableBackStack = if (deepLinkScreen != null) {
            rememberSaveableBackStack(listOf(AppHomeScreen(), deepLinkScreen))
        } else {
            rememberSaveableBackStack(root = AppHomeScreen())
        }
        navigator = rememberCircuitNavigator(backStack)
        
        // ... more code omitted
        NavigableCircuitContent(
            navigator = navigator,
        )

If this is not ideal path, how can I build stack of screen based on bundle data from onCreate()?

---

If feel like deep linking is a broad topic and may be hard to document, however a basic guide/pointer would definitely be helpful for starters like me.

I can take a stab at documenting based on feedback received here.

[ZacSweers]

Docs are definitely welcome! I think a lot of it depends on the app itself. Here's another implementation I wrote for a sideproject app: ZacSweers/CatchUp#880

[ZacSweers]

For the backstack, you likely want to keep one instance and then call resetRoot() ± pushing your new list in a snapshot

[hossain-khan]

Thanks for the pointer! I will take a look.

Yes, I felt there are many ways to do it (using URI scheme, or parcelable data).
However, the entry point on Android platform would be same to get the intent via the Android OS callbacks (onCreate & onNewIntent).

[hossain-khan]

👋🏽 Hi folks, here is the draft I could come up with to give some idea about deep linking on Android.

However, Circuit is a multi-platform library, I am not sure how useful this would be as a guide, at the same time I don't have expertise on multi-platform realm. This can stay as a discussion post and let users discover it through search. Basically, I am not too confident about this doc graduating to https://slackhq.github.io/circuit/ 😅

Here is something I still wasn't able to figure out properly:

• When activity is already open, and onNewIntent(intent: Intent) is received, how do I set a new stack of screens? Currently navigator.resetRoot() only takes single screen.

Thanks! 🙏🏽

---

Deep-linking using Circuit

Deep linking to app is a vast topic and the implementation detail can vary based on your application needs.
Deep linking strategy can be highly sophisticated or simple based on the use-case.

To keep things very simple and easy to understand, we will be focusing on deep linking to Android platform only.
You can then extend the idea to other platforms as needed.

Important

Pre-requisite: You should have basic understanding of deep linking and should go through the Android's official training guide that contains useful information about deep linking to Android app.

Deep linking strategy

Essentially, you need to define a strategy for you app to handle the incoming deep link. We will take a look at Circuit's email app from the tutorial with following screens:

• Inbox Screen - List all incoming emails
• Details Screen - Show details of the email
• Draft Screen - Compose a new email (additional screen added for this demo)

By default, the app launches with Inbox Screen as the root screen. To deep link into other two screens, we will define URI path segment as:

• inbox - Inbox Screen
• view_email - Details Screen with emailId as query parameter
• new_email - Draft Screen

Assuming, our app's URI scheme is circuitapp:// with host emailonthego, the deep links will look like:

• circuitapp://emailonthego/inbox - Deep link to Inbox Screen
• circuitapp://emailonthego/inbox/view_email?emailId=2 - Deep link to Details Screen with email id 2 with Inbox Screen as parent
• circuitapp://emailonthego/inbox/new_email - Deep link to Draft Screen with Inbox Screen as parent
• circuitapp://emailonthego/inbox/view_email/new_email?emailId=3 - Deep link to Draft Screen and in backstack there is Details Screen and Inbox Screen.

Once you have added intent-filter in your AndroidManifest.xml file, you can handle the incoming deep link in your Activity.

Handling deep link in Circuit

In our case, we will create a parseDeepLink function to parse the incoming deep link and return the list of screens to be displayed in the app.

// In your `MainActivity.kt` or activity that has the `intent-filter` for custom URI scheme
override fun onCreate(savedInstanceState: Bundle?) {
    // ...

    setContent {
        ComposeAppTheme {
            // When there is no deeplink data in the intent, default to Inbox Screen as root screen
            val screensStack: List<Screen> = parseDeepLink(intent) ?: listOf(InboxScreen)
            val backStack = rememberSaveableBackStack(screensStack)
            val navigator = rememberCircuitNavigator(backStack)

            // ...
        }
    }
}

And here is a simple implementation of parseDeepLink function that creates the list of screens based on the incoming deep link:

/**
 * Parses the deep link from the given [Intent.getData] and returns a list of screens to navigate to.
 */
private fun parseDeepLink(intent: Intent): List<Screen>? {
    val dataUri = intent.data ?: return null
    val screens = mutableListOf<Screen>()

    dataUri.pathSegments.filter { it.isNotBlank() }.forEach { pathSegment ->
        when (pathSegment) {
            "inbox" -> screens.add(InboxScreen)
            "view_email" ->
                dataUri.getQueryParameter("emailId")?.let {
                    screens.add(DetailScreen(it))
                }
            "new_email" -> screens.add(DraftNewEmailScreen)
            else -> Log.d("App", "Unknown path segment: $pathSegment")
        }
    }

    return screens.takeIf { it.isNotEmpty() }
}

Tip

Ideally, you would have deep link components that does the parsing and building screens based on parameters provided in the deep link URI.

To test try the following command from the terminal:

adb shell am start -W \
  -a android.intent.action.VIEW \
  -d "circuitapp://emailonthego/inbox/view_email/new_email/?emailId=2"

It should launch the app and navigate to the Draft Screen with backstack containing Details Screen and Inbox Screen.

---

Quick demo of deep linking working (src) using the sample code:

[ZacSweers]

This looks great! Do you think it would make sense to keep this solely as a doc or maybe perhaps also set it up as an optional part of the tutorial?

One note I'd add is that this doc is android-specific in implementation but should give a good idea of how to go about it for any other platform too