Deep Links¶

Handle custom URL protocol links (myapp://action?param=value).

import io.github.kdroidfilter.nucleus.core.runtime.DeepLinkHandler

DeepLinkHandler is a Kotlin object (singleton).

Setup¶

Register the protocol in the DSL:

nativeDistributions {
    protocol("MyApp", "myapp")
}

Handle incoming links in your app:

fun main(args: Array<String>) {
    DeepLinkHandler.register(args) { uri ->
        println("Received deep link: $uri")
        // Handle: myapp://open?file=document.txt
    }

    // The current URI is also available as a property
    val currentUri = DeepLinkHandler.uri

    // Launch the UI...
}

API Reference¶

Member	Type / Signature	Description
`uri`	`URI?` (read-only, volatile)	The most recent deep link URI
`register(args, onDeepLink)`	`fun register(args: Array<String>, onDeepLink: (URI) -> Unit)`	Register a deep link handler with CLI args
`writeUriTo(path)`	`fun writeUriTo(path: Path)`	Write the current URI to a file (for IPC)
`readUriFrom(path)`	`fun readUriFrom(path: Path)`	Read a URI from a file (for IPC)

Integration with Single Instance¶

Deep links work with SingleInstanceManager to forward URLs to the primary instance:

fun main(args: Array<String>) {
    DeepLinkHandler.register(args) { uri ->
        handleDeepLink(uri)
    }

    val isSingle = SingleInstanceManager.isSingleInstance(
        onRestoreFileCreated = {
            // New instance: write our deep link URI for the primary to read
            // `this` is the Path to the restore request file
            DeepLinkHandler.writeUriTo(this)
        },
        onRestoreRequest = {
            // Primary instance: read the URI from the new instance
            // `this` is the Path to the restore request file
            DeepLinkHandler.readUriFrom(this)
            window.toFront()
        },
    )

    if (!isSingle) {
        System.exit(0)
        return
    }

    // Handle the initial deep link if launched with one
    DeepLinkHandler.uri?.let { handleDeepLink(it) }

    // Launch the UI...
}

Platform Behavior¶

Platform	Mechanism
macOS	Apple Events (`setOpenURIHandler`) — works even when app is already running
Windows	CLI argument via registry handler — new process forwards to primary instance
Linux	CLI argument via `.desktop` MimeType — new process forwards to primary instance