Custom links (myapp://)
Let links like myapp://invite/ABC open your app, read them at start-up and in a running copy, and treat them as untrusted input.
Available since 0.4.0. A link like myapp://invite/ABC in a browser, a chat or an email can start your application and tell it what to open. That is how "Open in the app" buttons, invitations and sign-in callbacks work. You choose the scheme (the part before ://); Jolt tells the operating system about it. This page registers a scheme, reads the link at start-up, then handles links that arrive while the app is already running.
1. Register your scheme
Registering writes an entry for the current user, with no administrator rights. You give the scheme, a name the system can show, and the command that starts your program:
UrlSchemes schemes = app.urlSchemes();
schemes.register("myapp", "My App", Autostart.currentCommand(List.of()));
schemes.isRegistered("myapp"); // true
schemes.unregister("myapp"); // remove it again (does nothing if there is none)- The scheme is lower case letters, digits,
+,-and., starting with a letter:myapp, notmyapp://. - The command is the program followed by its arguments.
Autostart.currentCommand(List.of())describes the running process, which suits an installed or packaged app. The same helper is used for autostart. - Windows writes keys under
HKCU\Software\Classes\<scheme>. Linux writes a.desktopfile that handlesx-scheme-handler/<scheme>and makes it the default withxdg-mime. - Web, mail and file schemes are refused (
http,https,file,ftp,mailto,data,blob,about,javascript), because taking one over would break links for the user's browser or mail program. They throwIllegalArgumentException.
2. When to register
- On every start, or at install time. Registering again replaces the entry, so doing it on every start keeps it correct if the program moves.
- Not from a development run. From an IDE or the classes folder the entry would point at a command that only works there. Register only when running the packaged app, for example behind a flag or when the app finds itself in its install folder.
3. Read the link at start-up
The link arrives as the last command-line argument. UrlSchemes.findUrl picks it out of the arguments:
public static void main(String[] args) {
Optional<URI> link = UrlSchemes.findUrl(List.of(args), "myapp"); // case-insensitive
link.ifPresent(url -> System.out.println(url.getHost() + url.getPath())); // "invite" + "/ABC"
...
}findUrl returns the first argument that starts with myapp:, as a URI, or empty. Use the usual URI getters to take it apart.
4. When the app is already running
Clicking a link starts your program again. You do not want a second window, so combine this with SingleInstance (see One copy only): the new launch hands its arguments to the copy that is running, then exits.
public static void main(String[] args) {
AppOptions options = AppOptions.of("com.example.myapp");
SingleInstance instance = SingleInstance.acquire(options, List.of(args), otherArgs ->
app.dispatch(() -> { // the callback is not on the UI thread
main.focus();
UrlSchemes.findUrl(otherArgs, "myapp").ifPresent(MyApp::openLink);
}));
if (!instance.isPrimary()) {
return; // the running copy has the link now
}
// first launch: the link may be in our own arguments
UrlSchemes.findUrl(List.of(args), "myapp").ifPresent(MyApp::openLink);
...
}The two places to read a link are the first launch (main's args) and the callback (otherArgs). A common bug is to handle only one of them.
5. Treat the link as untrusted
Any web page can open a myapp:// link, so anyone on the internet can make your program start with text of their choosing. Handle it like a request from the network:
- Check before acting. Allow a short list of actions and validate every part.
myapp://invite/ABCmay open an invitation screen; it should not delete anything or run a command. - Ask for anything that matters. A link that would sign out, delete or send something should show a confirmation first.
- Never build file paths or commands from the link without validating them.
Windows and browsers may also ask the user "Open My App?" before they launch it; that is why the display name matters.