Skip to content

OS integration

Introduction

Operating systems expose a lot of integration points. Some are directly supported by Conveyor. For others you can extend the generated metadata files from your config, meaning you don't need direct support.

This section discusses how to achieve common integrations and how to develop your own.

URL handlers / deep linking

Having your app launch when the user clicks a URL is easy. If you want to handle my-app:foo or my-app://foo links then just add it to the app.url-schemes key, like this:

app.url-schemes = [ my-app ]

If users won't directly see your links then a reasonable choice for the URL scheme is your app's rdns-name, because that's meant to be globally unique, and only contains characters valid for URL schemes.

Important! This only registers your app for that URL scheme. You still have to receive and handle open requests from the OS. This differs by platform and runtime. On macOS the OS delivers the request via your Cocoa app delegate and no work is required for single instance mode. On Linux and Windows the request is delivered by executing a new process with the URL as the command line parameter. It's up to you to locate the other instance of the app if there is one and relay the request to it. For Electron apps this is built in. For JVM apps you can use a library like unique4j on Windows/Linux and java.awt.Desktop.setOpenURIHandler on macOS.

Custom integrations

Conveyor isn't an installer generator; it builds packages that declare how to integrate apps with the OS using static metadata. Each OS has its own metadata file controlling the integration:

For Linux and macOS the underlying file types can be cleanly mapped to the JSON data model and therefore set via config keys. For Windows, you can control the generated XML using a mix of keys for common settings and the extensions-xml key:

app.windows.manifests.msix.extensions-xml = """
  <XML/>
"""

See the Windows, macOS and Linux sections for details on how you can override custom keys.

Windows AppX manifest

In legacy Windows app deployment, programs are deployed using a dedicated installer EXE that (un)integrates the app by modifying the registry. In modern Windows app deployment, programs are installed using the built in package manager and desired integrations are expressed using an XML file interepreted by the OS. This approach has many advantages, for example, uninstallation is always clean. The "AppX Manifest" is usable by any kind of app packaged using MSIX. Therefore, instead of asking "what registry key do I need for this", you can look up the relevant portion of the XML schema instead.