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 would be same to get the intent via the Android OS callback.