Deep links et schémas d'URL

Les deep links vous permettent d'enregistrer un schéma d'URL personnalisé myapp:// et de recevoir l'URI entrante en Kotlin. Le plugin Gradle Nucleus enregistre le schéma auprès de l'OS au packaging, et DeepLinkHandler, dans core-runtime, livre l'URI au runtime, qu'elle arrive via les Apple Events macOS ou via les arguments de ligne de commande.

Ajouter la dépendance

DeepLinkHandler est fourni par core-runtime, que nucleus-application tire transitivement. Si vous dépendez déjà de nucleus-application, vous l'avez. Sinon, ajoutez le module directement :

dependencies {
    implementation("dev.nucleusframework:nucleus.core-runtime:2.0.7")
}

Déclarer le schéma d'URL

Enregistrez le schéma dans le bloc nativeDistributions du plugin Nucleus. Le plugin écrit l'enregistrement propre à la plateforme dans chaque installeur qu'il génère :

nucleus.application {
    nativeDistributions {
        // protocol(name, vararg schemes)
        // name est affiché dans l'UI de l'OS ; schemes sont les préfixes d'URL (sans "://").
        protocol("MyApp", "myapp")
    }
}

Traiter les URI entrantes

Dans nucleusApplication { }, enregistrez un callback avec onDeepLink. Il choisit le chemin de livraison selon le backend actif (AWT ou Tao) et se déclenche à la fois pour l'URI de cold start et pour les activations ultérieures :

import java.net.URI

fun main(args: Array<String>) = nucleusApplication(args) {
    onDeepLink { uri: URI ->
        // Route selon uri.host / uri.path / les paramètres de requête.
        navigateTo(uri)
    }

    DecoratedWindow(onCloseRequest = ::exitApplication) {
        // ...
    }
}

Sans le point d'entrée nucleusApplication, câblez DeepLinkHandler vous-même. setHandler est sûr sur tous les backends ; sur macOS, vous installez en plus le handler Apple Events d'AWT :

import dev.nucleusframework.core.runtime.DeepLinkHandler

fun main(args: Array<String>) {
    DeepLinkHandler.setHandler(args) { uri -> navigateTo(uri) }
    // macOS uniquement, et seulement pour les lancements pilotés par AWT.
    DeepLinkHandler.installAwtAppleEventHandler()

    application {
        // ...
    }
}

Fonctionnement

Chaque OS livre les URL différemment :

setHandler(args, onDeepLink) réconcilie ces différences. Sur le chemin AWT, installAwtAppleEventHandler enregistre un handler Apple Events pour que le callback se déclenche pendant que l'app tourne déjà ; sur Windows et Linux, setHandler scanne args à la recherche de la première entrée contenant ://. L'URI de cold start n'est livrée au handler qu'une fois par process, donc l'enregistrer depuis un scope Compose qui se relance à la recomposition ne la redéclenche pas.

Windows et Linux démarrent un nouveau process à chaque activation. Combinez avec SingleInstanceManager pour transférer l'URI vers l'instance déjà en cours : le process secondaire enregistre son URI avec captureFromArgs et l'écrit avec writeUriTo(path) avant de quitter, et l'instance primaire la relit avec readUriFrom(path).

Le plugin génère tout l'enregistrement statique — entrées Info.plist, clés de registre Windows et fichiers .desktop. Vous déclarez le schéma une seule fois.

Référence de l'API

DSL Gradle

nativeDistributions {
    protocol(name: String, vararg schemes: String)
}

DeepLinkHandler

object DeepLinkHandler dans dev.nucleusframework.core.runtime.

NucleusApplicationScope.onDeepLink

nucleusApplication { onDeepLink { uri -> /* ... */ } }

Enregistre un callback DeepLinkHandler qui diffère jusqu'au démarrage de l'application et choisit le chemin de livraison adapté au backend.

Notes

• DeepLinkHandler.register(args, onDeepLink) est déprécié : il installe toujours le handler AWT et est incompatible avec le backend Tao sur macOS. Utilisez onDeepLink { … } ou setHandler.
• Testez en développement avec xdg-open myapp://test (Linux), open myapp://test (macOS) ou start myapp://test (Windows). L'enregistrement via l'installeur ne s'applique qu'aux builds packagés — voir Launcher : Windows.
• L'URI de cold start est aussi stockée dans DeepLinkHandler.uri ; lisez-la après avoir enregistré votre handler.
• Pour les associations de fichiers (ouvrir un .csv avec votre app), utilisez plutôt le DSL fileAssociation(...) du plugin.

Et ensuite

• Instance unique — transfère un deep link d'un process relancé vers celui déjà en cours.
• Launcher : macOS — l'intégration Info.plist et Apple Events.
• Launcher : Windows — l'enregistrement dans le registre et les entrées de jump-list.