Rinku is a lightweight Kotlin Multiplatform library designed to simplify deep link handling across iOS and Android platforms. By abstracting platform-specific details, Rinku enables developers to manage deep links in a unified manner, enhancing code reuse and maintaining consistency across platforms.

• Unified Deep Link Management: Architect your deep link logic once, and execute seamlessly across iOS and Android platforms.
• Simplified Integration: Designed for rapid setup with minimal configuration requirements, ensuring a smooth start.
• Universal Compatibility with Navigation Libraries: Rinku's architecture is designed for compatibility with any navigation library. It delegates the parsing and navigation logic to the application, permitting seamless integration and enhanced flexibility.

• Kotlin Multiplatform project setup
• For Android: Minimum SDK version 22
• For iOS: iOS 13.0 or later

The library is available via Maven Central

implementation("dev.theolm:rinku:<latest_version>")
implementation("dev.theolm:rinku-compose-ext:<latest_version>")

In your build.gradle.kts file you need to:

• Include Rinku in commonMain as an api (this is required to export it to iOS)
• If you are using Compose multiplatform, also include the compose-extensions
• Export the lib in the ios framework

Example:

kotlin {
    ...
    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
        // Specify iOS targets
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            // Export of Rinku library to the iOS framework
            export("dev.theolm:rinku:<latest_version>")
            ...
        }
    }
    ...
    sourceSets {
        commonMain.dependencies {
            api("dev.theolm:rinku:<latest_version>")

            // For compose multiplatform projects
            implementation("dev.theolm:rinku-compose-ext:<latest_version>")
        }
    }
}

This guide presupposes the prior configuration of deeplinks within the native platforms:

• Android deeplink
• iOS URL scheme
• iOS universal link

The library provides two types of initialization (KMP only and Compose), you should use the one that fit your needs.

On the Android app, inside the onCreate, call the extension RinkuInit().

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        RinkuInit()
        setContent {
            App()
        }
    }
}

First make sure you included the rinku-compose-extin your commonMain. On the Android app inside the setContent use ComponentActivity.Riku extension to wrap the root of your app.

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            Rinku {
                App()
            }
        }
    }
}

For the iOS platform, deep links are processed within the AppDelegate or SceneDelegate, contingent on the project's configuration. The primary objective is to intercept the platform-specific deep link and relay it as an argument to Rinku's handleDeepLink(url) method.

Example within AppDelegate:

@UIApplicationMain
class AppDelegate: NSObject, UIApplicationDelegate {
    ...
    // Provide deepLinkFilter and deepLinkMapper if needed
    let rinku = RinkuIos.init(deepLinkFilter: nil, deepLinkMapper: nil)
    func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
        rinku.onDeepLinkReceived(url: url.absoluteString)
        return true
    }
    
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let url = userActivity.webpageURL {
            let urlString = url.absoluteString
            rinku.onDeepLinkReceived(userActivity: userActivity)
        }
        return true
    }
    ...
}

In the common code you just need to listen to the deeplinks and treat them as you need. Once the application (Android or iOS) recieves a deeplink it will parse it into a Deeplink data class and pass it into the listener. Use the listener that suite your project.

Example RootApp in commonMain:

@Composable
fun RootApp() {
    var deepLink by remember { mutableStateOf<DeepLink?>(null) }
    DeepLinkListener { deepLink = it }
    MainScreen(deepLink)
}

Just use the suspend function listenForDeepLinks and react as you will.

Example inside a Decompose component:

class AppComponentImpl(
    private val initialStack: List<Config> = emptyList(),
    componentContext: ComponentContext,
) : AppComponent, ComponentContext by componentContext {
    private val navigation = StackNavigation<Config>()

    init {
        launch { initDeepLinkListener() }
    }

    private suspend fun initDeepLinkListener() {
        listenForDeepLinks {
            navigation.replaceAll(
                *it.toScreenStack().toTypedArray()
            )
        }
    }
}

Rinku simplifies the process of triggering internal deep links directly from your common Kotlin Multiplatform (KMP) code. This feature allows you to easily navigate within your application using a unified approach across all platforms.

To invoke an internal deep link within your application, use the handleDeepLink method provided by Rinku. This method accepts a single parameter: the URL of the deep link you wish to trigger.

Rinku.handleDeepLink("https://test.deeplink/path?query=true")

In this example, https://test.deeplink/path?query=true represents the URL of the deep link. The URL scheme, path, and query parameters should be replaced with values that are relevant to your application's routing structure.

By leveraging Rinku's handleDeepLink method, you can enhance your application's navigation capabilities, making it easier to programmatically direct users to specific areas of your app from shared KMP code.

Rinku supports get and create typesafe parameters leveraging the kotlinx-serialization. In order to use the following functions the app/module needs to setup kotlinx-serialization.

Use the DeepLink extension <T> DeepLink.getParameter and pass the key of the argument in the URL query and the KSerializer of the correspoinding kotlin class.

example:

@Serializable
data class Name(val name: String)

fun example() {
    val url = "https://theolm/dev/path?test={"name": "Theo"}"
    val deepLink = DeepLink(url)

    val param : Name = deepLink.getParameter(name = "wrong name", kSerializer = Name.serializer())
}

Rinku also provides the helper funcion Rinku.buildUrl that facilitates the creation of internal deeplinks with parameters. In order to do that you first need to create the URL and fire the deeplink.

example:

@Serializable
data class Name(val name: String)

fun example() {
    val testModel = Name("Testing")
    val testParam = DeepLinkParam(
        "testParam",
        testModel,
        Name.serializer()
    )
    val url = Rinku.buildUrl(TestUrl, testParam)
    Rinku.handleDeepLink(url)
}

Rinku provides a simple way to filter unwanted external deeplinks. Instead of filter deeplinks providing specific paths in the AndroidManifest and info.plist you implment the interface DeepLinkFilter and pass it into Rinku initialization. With this configuration, when the app recieves a not valid deeplink rinku is not going to handle it. This is usefull to block internal deeplinks from external access without having to include it in platform specific configuration.

This feature is used to map external deeplinks into internal deeplinks. Use case 1: Android and ios application has different deeplinks registered in marketing campaigns. The mapper can be used to map the external deeplink to unique internal deeplink, and the application can handle the deeplink accordingly in a unified way. Use case 2: External deeplink does not have the full path to represent a valid stack. Use the mapper to provide the full stack.

// External deeplink rinku://dev.theolm/screenC/
// The deeplink is missing A and B

// Implement and pass the mapper into Rinku init. This way the external deeplink will be mapped and can be handle in the commonMain.
object ExampleMapper : DeepLinkMapper {
    override fun map(url: String): String {
        return if (url == "rinku://dev.theolm/screenC/") {
            return "rinku://dev.theolm/screenA/screenB/screenC/"
        } else {
            url
        }
    }
}

The library includes two illustrative examples utilizing the foremost multiplatform navigation libraries: Voyager and Decompose

• Voyager sample
• Decompose sample

Note: Only the Voyager sample includes an iOS application. Nonetheless, the setup for Decompose would mirror that of Voyager.

Note 2: Both examples are using Compose multiplatform.

Rinku is released under the MIT License. See the LICENSE file for more details.