Launcher SDK

Current version: 2.0

The Electron Launcher SDK is a tool that enables the development of PatchKit electron-based launcher themes in a lightweight development environment, consisting of a web browser window and a code editor of your choice. The SDK allows mimicking different states of the launcher to test how custom code would look and behave. The launcher is built on the Chromium web engine; therefore, we recommend using a Chromium-based web browser.

Please note that the launcher theme code is responsible for both the appearance and behavior, such as user flow. For instance, you can trigger the authentication logic before the user can install the game.

Requirements

To start working with the SDK, you need a few things installed on your development machine:

• NodeJS (we recommend nvs and NodeJS v16.16.0)
• A package manager of your choice (we recommend yarn, although both npm and pnpm should work as well)
• An App Catalog on PatchKit Panel (you can create it here)

Quick start with an example project

To assist you in bootstrapping your launcher, we recommend downloading the example project. Simply download the patchkit-example-launcher.zip archive and unpack the contents into a directory where you will be working on your launcher.

Now, you need to run theme and the runtime components in that order (preferably in development mode).

cd theme
yarn
yarn start

Once your theme is running, open a new terminal window and start the runtime.

cd runtime
yarn

# Windows
yarn run-dev -p windows-preset.js -t http://localhost:3000

# macOS
yarn run-dev -p macos-preset.js -t http://localhost:3000

# Linux
yarn run-dev -p linux-preset.js -t http://localhost:3000

As you do that, you will see a launcher window appear. The library on games in it, is a library of games of PatchKit demo launcher, which you can easily switch to yours later on. The example project has hot-reloading enabled, so any changes you make in the theme will be instantly reflected in the launcher.

Basic concepts

The PatchKit Launcher SDK structures the project into two separate components:

• Runtime - an application built on top of the Electron framework that supplies core functionality like installing and updating the apps, as well as window management, shortcut creation, and deep links.
• Theme - a user interface built with frontend technologies, allowing you to completely customize your launcher. You can think of it as a front-end application with additional API exposed from the launcher.

These two components are deployed individually to allow quick updates of the theme without the need to rebuild the whole launcher. The deployment instructions are detailed in this section.

Runtime component

The runtime component consists of:

• A package.json file that depends on two SDK packages: patchkit-generic-launcher2-dev-tools and patchkit-generic-launcher2-base-presets.
• Presets

Presets

The concept of presets allows you to have different variants of your launcher. Common use cases for having multiple presets are:

• To target multiple platforms (Windows, macOS, or Linux)
• To separate development/internal and production versions of the launcher

Each preset is a JavaScript file placed in the src directory that exports the configuration object. This setup enables you to store shared configurations in separate JavaScript files and compose them with libraries like deepmerge. Please refer to the example project for details.

Configurable preset fields include:

• id - Example: patchkit-demo-launcher. Required. Please note that it cannot be changed once the launcher is deployed.
• name - Example: PatchKit Demo Launcher. Required. This is used in areas visible to the user.
• description - Example: PatchKit Demo Launcher. Required. It usually matches the name, but you can use it to describe the specifics of your launcher.
• companyId - Example: upsoft. Required. Please note that it cannot be changed once the launcher is deployed.
• companyName - Example: Upsoft. Required. This is used in areas visible to the user.
• iconFilePath - Example: require.resolve("./icons/windows.ico").
• secret - Example: aabbccddeeffgghhiijjkkll11223344. Required.
• appsCatalogId - Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee. Required. You can find this in the list of your App Catalogs on PatchKit Panel.
• isAppsBranchesNotDefaultRootDirAllowed - Default: false. This determines whether to allow installing apps in any directory (not just the default ones).
• window
  • defaultSize - Default: { width: 1024, height: 768 }.
  • defaultMinSize - Default: { width: 1024, height: 768 }.
  • defaultMaxSize - Default: { width: 1024, height: 768 }.
  • defaultIsResizable - Default: false.
  • isBorderless - Default: false.
  • isTransparent - Default: false.
  • areCornersRounded - Default: true.
• protocol - Default: undefined. Example: { "id": "patchkit-demo-launcher" }. This allows you to configure the deep link functionality for your launcher so it can be opened from web links like patchkit-demo-launcher://action.

patchkit-generic-launcher2-dev-tools

This package provides the scripts required to start the launcher in development mode as well as to build it:

• run-patchkit-generic-dev-launcher2:
  • required -p or --presetFileName
  • required -t or --overrideThemeUrl
• build-patchkit-generic-prod-launcher2:
  • required -p or --presetFileName
  • required -v or --version
  • optional --appleId
  • optional --appleIdPassword

You can use these scripts:

• Directly with yarn, for example yarn run-patchkit-generic-dev-launcher2
• Directly with npx, for example npx run-patchkit-generic-dev-launcher2
• By aliasing them in the scripts field of package.json (please refer to the example project)

patchkit-generic-launcher2-base-presets

This package provides presets with default values that are commonly used across launchers built with the SDK.

Theme component

The theme is simply a user interface application built with web technologies, similar to a front-end. Please refer to the example project to learn how to utilize the API exposed from the launcher runtime to create the launcher user interface.

Possible routing issues

To ensure your launcher theme is compatible with the deployment option on the PatchKit Panel, you need to adjust the routing method in your application. Since the theme is going to be deployed in a subdirectory, you can’t assume the absolute path to your application at build time. Therefore, we recommend using solutions like HashRouter from react-router to avoid any issues after deployment.

Building and deployment

When you’re done working on your launcher, you need to build it.

Building and deploying the Runtime component

To build and deploy the launcher, follow these steps:

1. Open the PatchKit Panel.
2. If you already do have an Electron Launcher application, skip to step 7.
3. Navigate to the Applications page.
4. Click the New Application button and then choose New Custom Electron Launcher from the popup.
5. On the next form, provide the Electron Launcher name and platform, and then click the Create button.
6. Instead of uploading the new version, go back to the Overview tab.
7. Find and copy the Secret field to the clipboard.
8. Fill the secret property in specific preset file (like windows-preset.js).
9. Run the build-prod command with specific parameters:

cd runtime

# Windows
yarn build-prod -p windows-preset.js -v LAUNCHER_VERSION --upload --publish --patchKitApiKey YOUR_PATCHKIT_API_KEY

# macOS (with signing)
yarn build-prod -p macos-preset.js -v LAUNCHER_VERSION --upload --publish --patchKitApiKey YOUR_PATCHKIT_API_KEY --appleId YOUR_APPLE_ID --appleIdPassword YOUR_APPLE_ID_PASSWORD

# macOS (without signing)
yarn build-prod -p macos-preset.js -v LAUNCHER_VERSION --upload --publish --patchKitApiKey YOUR_PATCHKIT_API_KEY

# Linux
yarn build-prod -p linux-preset.js -v LAUNCHER_VERSION --upload --publish --patchKitApiKey YOUR_PATCHKIT_API_KEY

Where:

• YOUR_PATCHKIT_API_KEY - your PatchKit API Key that can be found here
• LAUNCHER_VERSION - the version label of the launcher (e.g., 1.0.0)
• YOUR_APPLE_ID (optional/macOS only) - your Apple ID (provide if you want to sign the launcher)
• YOUR_APPLE_ID_PASSWORD (optional/macOS only) - your Apple ID password (provide if you want to sign the launcher)

This should build, upload and publish the launcher directly on your PatchKit account.

Your new launcher is now online, but without a theme it will not display anything (or will generate an error). Please proceed to the next section to learn how to deploy the theme.

Building and deploying the Theme component

To build the theme, run:

cd theme
yarn build

This should create a build directory in the theme directory that contains the built theme. You will need to zip it. On macOS and Linux, you can use the following command:

cd build
zip -r theme.zip .

On Windows, you can use the following command:

cd build
Compress-Archive -Path * -DestinationPath theme.zip

Finally:

1. Visit the PatchKit Dashboard and sign in.
2. In the left sidebar, click on the Launcher Themes link.
3. Press the New Launcher Theme button.
4. Click the New Version button.
5. Choose the theme file (.zip format) and click the Upload button (you can ignore the Launcher Version field for now).

Understanding the Launcher Version Field

The Launcher Version field is used to indicate the launcher version compatible with the theme. If left empty, it will default to the highest defined version or 0.0.0 (compatible with all). If a launcher version is specified, the theme will only be compatible with that specific version and newer versions sharing the same major version number.

For example, if you specify 1.0.0 as the launcher version, the theme will be compatible with launcher versions 1.0.0, 1.0.1, 1.0.2, 1.1.0, 1.1.1, 1.2.0, 1.2.1, and so on, but not with launcher versions 2.0.0, 2.0.1, 2.1.0, 2.1.1, etc.

On the launcher version page, you can find all launcher versions sorted by their release date. The most recent version is at the top. If multiple versions have the same version number, the one with the latest release date takes precedence and will be used by the launcher.

Associating a Theme from the Launcher Themes Page

A newly uploaded theme is not immediately available to users. To make it accessible, you must associate it with a specific launcher app. You can do this from the Launcher Themes page in the PatchKit Dashboard or through your launcher app settings.

1. Visit the PatchKit Dashboard and sign in.
2. In the left sidebar, click on the Launcher Themes link.
3. Press the Edit button next to the theme you want to associate.
4. Click the Assign to Launcher button.
5. Choose the launcher app you want to associate the theme with, and click the Assign button.

Now, your users can access the theme you’ve uploaded. The launcher may need to be restarted for the changes to take effect.

Sharing your launcher

Once both the runtime and theme have been uploaded, you can distribute your launcher to the end-users. You can do so by navigating to your launcher application page on the PatchKit Dashboard (the Overview tab) and finding the Download Link in the Details frame on the right side of the page.

Signing your launcher on Windows

1. Obtain a Code Signing Certificate

First, you’ll need to obtain a code signing certificate.

2. View Certificate Details

Open the certificate details window. You can do this by locating your certificate in the Manage user/computer certificates or the SafeNet Authentication Client if you are using a USB token.

Steps:

1. Switch to the Details tab.
2. Locate the Subject property and note down the value of CN. Assign this value to a variable named subjectName. For example:

   CN = UPSOFT  sp. z o. o.
   ...
   subjectName = "UPSOFT  sp. z o. o."
   

3. Find the Thumbprint property and note its value. Assign this value to a variable named sha1.

3. Update Windows Preset File

Add the codeCertificate field to your Windows preset file with the appropriate values you just obtained.

const deepmerge = require(`deepmerge`);

module.exports = deepmerge(
  require(`patchkit-generic-launcher2-base-presets`).windowsBasePreset,
  deepmerge(
    require(`./shared-preset`),
    {
      secret: `WINDOWS_SECRET`,
      iconFilePath: require.resolve(`./icons/windows.ico`),
      codeCertificate: {
        subjectName: <subjectName>,  // Replace <subjectName> with your value
        sha1: <sha1>,                // Replace <sha1> with your value
      },
    },
  ),
);

Finding Certificate Details in SafeNet Authentication Client

If you’re using the SafeNet Authentication Client, follow these steps to locate your certificate details:

1. Open the SafeNet Authentication Client. It should be available in your system tray.
2. Switch to Advanced view. You can find this option represented by a gear icon in the top right corner.
3. Navigate through the list to find your certificate. Once located, double-click on it to view its details.

Signing your launcher on macOS

1. Enroll into Apple Developer Program

You can do it here.

2. Generate Developer ID Application certificate

Enter this page and select Developer ID Application option. Make sure to download certificate and install it on your building machine.

3. Install Apple Intermediate Certificates

When you install your Developer ID Application certificate it’s going to be untrusted, making it unusable for code sigining. To fix this, download and install Apple Intermediate Certificates from this page. You’re looking for two certificates:

• Developer ID - G1 (Expiring 02/01/2027 22:12:15 UTC)
• Developer ID - G2 (Expiring 09/17/2031 00:00:00 UTC)

Once you install them, you’re certificate should be marked as valid.

4. Install Command Line Tools for Xcode

Since last step of building the launcher is notarization, you need to install latest Command Line Tools for Xcode (or simply Xcode, Command Line Tools are just more lightweight option). You can find them here. Make sure to download at version 13 or higher.

5. Update macOS Preset File

Add the appleTeamId field to your macOS preset file and fill it with your Team ID. You find instructions on how to find it here.

const deepmerge = require(`deepmerge`);

module.exports = deepmerge(
  require(`patchkit-generic-launcher2-base-presets`).macosBasePreset,
  deepmerge(
    require(`./shared-preset`),
    {
      secret: `MACOS_SECRET`,
      iconFilePath: require.resolve(`./icons/macos.icns`),
      appleTeamId: `APPLE_TEAM_ID`,
    },
  ),
);

6. Generate App-Specific Passsword

Enter this page and select App-Specific Passwords option. Make sure to save generated password somewhere.

7. Modify your build command

You need to specify two additional arguments --appleId (email of your Apple account) and --appleIdPassword (App-Specific Password generated in previous step).

The build command should look like this:

yarn build-prod -p macos-preset.js -v LAUNCHER_VERSION --upload --publish --patchKitApiKey YOUR_PATCHKIT_API_KEY --appleId YOUR_APPLE_ID --appleIdPassword YOUR_APPLE_ID_PASSWORD

FAQ

Do I need to update the launcher each time I update the theme?

No, you don’t. The launcher is responsible for fetching the latest version of the theme from the PatchKit servers. Therefore, you can update the theme without the need to update the launcher binary.

When should I update the launcher binary and what changes can I expect?

You should update the launcher binary (the runtime component) only in two cases:

1. You modified the presets
2. You upgraded the SDK version

For the list of changes, please visit this page.

Should the launcher pop up as a window when I run it?

Yes, the launcher should pop up as a window every time it’s executed.

What if the launcher doesn’t show up even after the process seems to start successfully?

There could be multiple reasons for this, one being potential issues with Windows 11’s features of restoring apps. You might need to look for specific executable instances and close them or restart your computer.

Where can I find the logs for the launcher?

The logs are usually located in runtime/temp/your-launcher-id/dev-user-data/logs/logs.yml.

What should I do if the logs are empty or not found?

If logs are not available, please consider reaching PatchKit Support and giving us details about the issue.

How do I connect my application with the launcher?

You need to make sure that you’re using the correct ‘secret’ from your PatchKit application settings.

Can I upload a theme using the command-line tool?

Currently, themes cannot be uploaded via the command-line tool, but this might be considered for future versions.

How does the auto-update feature work regarding version labels?

Version labels need to be in x.y.z format and should match with the version you pass using the -v argument. Each new version should have a unique label.

Can deep links be used with the SDK?

Yes, deep links are fully supported.

How can I test the launcher with a protocol in dev mode?

First, start the launcher with run-dev. After that, protocol requests should be received.

How should I use Patchkit for different environments like prod and dev?

Some clients use a double launcher setup with a production launcher connected to their production app catalog and an internal launcher connected to the internal app catalog. You can also utilize branches, but managing them in your theme is necessary.

Can I retrieve values from the current preset.js in the theme?

No, currently, the SDK doesn’t support retrieving values directly from preset.js in the theme.

How can I detect the launcher runtime my theme is currently running in?

You can use different launcher IDs to distinguish between different launchers. The ID from patchkit-launcher2-api-theme-client package corresponds to the id field from your preset.

How do I revert to a previous version of a theme?

To revert to a previous version of a theme, you must delete all newer versions of the theme. You can do this from the Launcher Themes page in the PatchKit Dashboard by clicking the Delete button next to the version you want to remove.