Enregistre des handlers monapp:// sur macOS, Windows et Linux depuis un seul bloc Gradle.

Une URL, c'est la manière universelle pour l'OS — et les autres apps — de parler à la tienne. Un lien dans un mail, un message Slack, un QR code : ça finit en monapp://action?id=42 sur la machine de quelqu'un. Nucleus enregistre le protocole au packaging et tend l'URI dans le main() au runtime.

TL;DR

Déclare les protocoles une fois dans nucleus { application { nativeDistributions { protocol(...) } } }.
Le plugin écrit la plomberie : LSBundleURLTypes (macOS), entrées registre HKCU (Windows), MimeType .desktop (Linux).
DeepLinkHandler.setHandler(args, onDeepLink) parse l'URI qu'elle arrive via Apple Events ou args CLI.
Combine avec SingleInstanceManager pour transférer les URI d'une instance secondaire vers la primaire en cours.

Installation

Fourni avec core-runtime (tiré transitivement par nucleus-application).

Quickstart

1. Déclare le schéma

nucleus.application {
    nativeDistributions {
        protocol("MyApp", "myapp")
        // protocol(name, vararg schemes) — name visible dans l'UI de l'OS,
        // schemes = les préfixes (sans ://) que voulu capturer.
    }
}

2. Traite les URI entrantes

import dev.nucleusframework.core.runtime.DeepLinkHandler

fun main(args: Array<String>) = nucleusApplication(args) {
    onDeepLink { uri ->
        // uri est un java.net.URI — route sur uri.host / uri.path / query
        navigateTo(uri)
    }

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

Sans nucleusApplication { } :

fun main(args: Array<String>) {
    DeepLinkHandler.setHandler(args) { uri -> navigateTo(uri) }
    // Sur macOS, ajoute aussi :
    DeepLinkHandler.installAwtAppleEventHandler()

    application { /* ... */ }
}

Comment ça marche

Les trois OS livrent les URL de trois façons différentes :

OS	Mécanisme
macOS	Apple Events. L'app déjà lancée reçoit des événements `GetURL` via `NSAppleEventManager` (ou `Desktop.setOpenURIHandler` d'AWT sur JBR/OpenJDK). Le plugin déclare le schéma dans `Info.plist` sous `CFBundleURLTypes`.
Windows	Entrée registre sous `HKCU\Software\Classes\<scheme>`. Cliquer une URL `monapp://...` lance le `.exe` avec l'URL en premier argument CLI — un nouveau process.
Linux	Un fichier `.desktop` avec `MimeType=x-scheme-handler/monapp;` plus l'association `xdg-mime`. L'URL arrive aussi en argument CLI.

DeepLinkHandler.setHandler(args, onDeepLink) masque la différence : sur macOS il installe le handler Apple-event d'AWT pour que le callback se déclenche pendant que l'app tourne, sur Windows / Linux il scanne args à la recherche d'entrées URI. Combine avec SingleInstanceManager pour le cas très courant Windows / Linux où un second .exe est lancé juste pour livrer l'URL : la secondaire écrit l'URI dans le fichier restore-request, la primaire le relit.

Le plugin s'occupe de tout le statique — Info.plist, entrées registre, fichiers .desktop. On décrit le protocole une fois.

Référence

DSL Gradle

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

`DeepLinkHandler`

Membre	Signature	Notes
`setHandler(args, onDeepLink)`	`(Array<String>, (URI) -> Unit) -> Unit`	Câble le handler. Appelle-le avant `application { }`.
`installAwtAppleEventHandler()`	`() -> Unit`	macOS uniquement ; idempotent. `nucleusApplication { }` l'appelle automatiquement.
`uri`	`var URI?`	L'URI la plus récente, p. ex. celle du cold start.
`writeUriTo(path)`	`(Path) -> Unit`	Persiste l'URI courante — à combiner avec `SingleInstanceManager`.
`deliver(uri)`	`(URI) -> Unit`	Injecte une URI manuellement (utile en test).

`NucleusApplicationScope.onDeepLink`

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

Raccourci pour DeepLinkHandler.setHandler qui diffère l'inscription jusqu'au démarrage de l'app.

Notes

Teste en dev avec xdg-open monapp://test (Linux), open monapp://test (macOS), start monapp://test (Windows). Les entrées de jump-list ne marchent que sur builds packagés — voir Launcher : Windows.
L'URI de cold start (celle qui a lancé l'app) est aussi dans DeepLinkHandler.uri — lis-la après avoir enregistré le handler.
Pour les associations de fichiers (ouvrir un .csv avec le app), utilise le DSL fileAssociation(...) du plugin.

Deep links et schémas d'URL