Applications

Applications Overview

Before publishing anything with PatchKit, you need to create a new Application. Applications can be accessed using the Applications menu or using this link.

An Application is an entity that is used to identify your game or app and keep all its versions in a single place. This way, the launcher can download it, or check if there’s a new version available and how to update it.

Each application is bundled with a Unity launcher, but can be also downloaded by an Electron launcher.

Application Platform

The application needs to have a predefined architecture, that cannot be changed during its lifetime:

• Windows 32 bit
• Windows 64 bit
• OSX 64 bit
• OSX Silicon
• Linux 32 bit
• Linux 64 bit

Application Secret

Each Application is associated with a unique Secret string. Unless your Application has additional authentication enabled, you shouldn’t share this value with anyone that should not be allowed to download your files.

Application Settings

Application settings can be accessed through the Overview tab of the Application page and Settings tab. The Overview tab includes all the settings you should set before moving forward. The Settings tab is to fine-tune the defaults.

Overview tab

• Application Name - Internal application name.
• Display Name - The application name that is displayed within the launcher and any other place where the game is published.
• Author - The author’s name, can be visible inside the launcher or any other place where the game is published.
• Application Icon - The icon that should be used with the launcher executable or installer.
• Launcher Banner - The banner image that should be used in the default launcher.

Settings tab

• Changelong versions limit - The maximum number of version changes displayed inside the launcher.
• Hide empty version changelogs - When enabled, versions without changelogs will be hidden in the changelog list.
• Collect usage data - Select how the user should be asked to share their usage data.
• Compression Method - Select the compression method that should be used to compress the files before uploading them to the CDN. The default value is gzip.
• Processing Preset - Select the processing preset that should be used to process the files before uploading them to the CDN. The default value is normal.
• GZIP Compression Level - Select the compression level that should be used to compress the files before uploading them to the CDN. Lower values means faster processing times, but bigger distribution files. The default value is 4.
• LZMA2 Compression Level - Select the compression level that should be used to compress the files before uploading them to the CDN. Lower values means faster processing times, but bigger distribution files. The default value is 6.
• Librsync Block Size - Select the block size that should be used to calculate binary differences between files before uploading them to the CDN. Higher values means faster processing times, but bigger delta files. The default value is 2048.
• Publish automatically - When enabled, your each version will be published automatically after it’s uploaded. This option can be disabled to allow you to review the uploaded files before publishing them.
• Publish warnings settings - When Publish automatically is enabled, you can decide which processng warnings should be treated as errors and prevent the version from being published.
• Launcher Filename - The name of the downloadable launcher file. Please note that for the Unity launcher, the file extension is always .zip.
• Force HTTPS - When enabled, the launcher will always use HTTPS protocol to download the files.
• Authentication Method - Here you can configure player’s authentication method, the options are:
  • None - No authentication is required to download the files.
  • Product Keys - Require a valid License Key before the player can download the game.
  • External - External authentication based on External Authentication configuration.
  • Token - Authentication by token. Supported only by the Electron launcher.
  • Password - Authentication by password. Supported only by the Electron launcher.
  • Product keys and token - Authentication by License Key and token at the same time. Supported only by the Electron launcher.

Distribution

Distribution settings can be accessed through the Distribution tab of the Application page. This is where you set the distribution model for your application and access the launcher download links.

Distribution Model

The distribution model can be set to one of the following:

• Share Link - The application is free to download (via a share link) and run. This is the default value. If you have license keys enabled, the user will be able to use them to download and run the application.
• Paid - The application is paid. The user will be able to download and run the application only after paying for it.

When you decide to switch to the Paid mode, you will be asked to provide your payment account details and the price of the application. The download links will stay the same regardless of the distribution model. What changes is what the user will see after clicking the link. If the application is free, the user will be able to download and run it. If the application is paid, the user will be redirected to the payment page.

Free Distribution Model

When set to the free distribution model, users can freely download your application with a share link that you provide. You can copy the share link from the Distribution page or by clicking on the Get Launcher button.

Paid Distribution Model

The paid distribution model necessitates that the user pay for your application. You can specify the price in the Price Settings section of the Distribution page. Before you can begin distributing your application, you must configure tax settings, the price, and your PayPal integration.

Legal Information

PatchKit sells your applications by directly connecting to your merchant’s account (e.g., PayPal, Stripe, etc.). As such, you are the Merchant of Record and are responsible for tax collection and remittance, refunds, and chargebacks. Each transaction is directly transferred into your merchant’s account.

Setting the Tax

Before beginning the distribution process, you need to set the tax for particular world regions (or one global tax). This tax is applied to the final price and is visible on the receipt as a tax value. Your tax settings are applied globally across your account - you don’t need to configure it for each application.

To set the tax, navigate through Account -> Seller Settings and click on the New Tax button. Initially, you need to set the Global tax. This tax will be used if the buyer’s region has not been defined in your Tax Settings.

Setting the Price

Before enabling Paid Distribution for the first time, you need to set the price. You will be asked to enter the price on your first attempt to enable the paid distribution model. The price settings work very similarly to the tax settings. You can set the price for a more specific region and a global price for all other regions.

Setting the PayPal Integration

The last step is to set up the PayPal integration. The PayPal integration is used to process payments and forward them directly to your account. You can set up your live PayPal account or use a sandbox account for testing before going live.

Selling the Application

Once you have configured the price, taxes, and PayPal integration, you can enable the paid distribution model. From now on, your share link will prompt users to purchase the application. Anyone who buys your application can download the launcher at any time by providing their e-mail address.

By default, once downloaded, the launcher can be used to install the application on any number of devices.

Managing Transactions

You can browse all transactions made on your account on the Transactions page. By browsing a specific transaction, you can revoke user access to the application (e.g., if they have paid for it but then decided to cancel the transaction).

Channels

Channels are used to distribute multiple different versions of the same application. For example, you can have a stable channel for the latest stable version of the game and a beta channel for the latest beta version of the game. There are some important advantages of using channels:

• Each channel can have its own launcher, or even a different platform.
• Each channel can have its own distribution model and authentication method.
• You can easily revert to a previous version of the game by linking the channel to a specific version.
• You can link multiple channels to the same version, which means that you can have multiple launchers for the same version of the game.

Creating a New Channel

To create a new channel, naviigate to the Application page, click the great (⚙) icon on the top-right corner of the page and select New Channel. You will be asked to provide the channel name.

Now, the structure of your application now looks like this:

• group
  • main channel
  • new channel

The main channel is the default channel. All your users previously using the launcher will be redirected to this channel. You can rename the main channel, but you cannot delete it.

Deploying a New Version

To deploy a new version, you need to follow these steps:

• Navigate to your group page. It can be done by clicking your application name. You will know that you’re on the group page when you see the list of channels.
• Click on the New Version button.
• Upload your files.
• Click on the Persist button. This won’t publish the version, but it will make it available for the channels that are linked to it.
• Navigate to the Overview tab and click on the channel name you want to publish the version to.
• Click on the New Version button.
• Click on the Link to version button.
• Select the version you want to link to the channel.
• Wait for the processing to be finished.
• Click on the Publish button.

License Keys

License Keys are used to authenticate the users of your application. You can enable them by navigating to the License Keys tab of the Application page, When done, your launcher will prompt the user to enter a license key before they can download and run the application.

Managing License Keys

Keys are split into collections. Each collection can have its own set of keys. To create a new collection, navigate to the License Keys tab of the Application page and click on the New Keys Collection button. You will be asked to provide the collection name, the desired amount, and the key format. Generating keys may take a while depending on the number of keys.

Each key collection has the Distributed flag that can be set to true or false. It’s only for your own convience to mark the keys that have been distributed to your users. You can also set the Distributed flag to true for the keys that you have generated for testing purposes.

Each collection reports the number of keys that have been used.

You can block individual keys as well as whole collections of keys. To do that:

• For the collection, click on the Action button and select Block from further use.
• For the individual key, select the key you want to block and click on the With selected… button on the bottom of the page, then select Block from further use.

Keys Distribution

You can distribute your keys in two ways:

• Manually - You can distribute the keys manually by copying them from the collection page.
• CSV File - You can generate a CSV file with the keys and import it into your system.

Secure Running

You can secure your application from being run by parsing command-line arguments provided by the launcher. You should look for +patcher-data-location argument and use the value of this argument. It’s a relative path to the app_data.json file. You can use this file to verify the user’s license key.

{
  "file_id":"patcher_data",
  "version":"1.0",
  "product_key":"ABCD-EFGH-IJKL",
  "product_key_encryption":"none"
}

To verify if the license key can be used to run the application, you need to send a request to the following endpoint:

https://keys2.patchkit.net/v2/keys/LICENSE_KEY?app_secret=APP_SECRET

where LICENSE_KEY is the license key from the app_data.json file and APP_SECRET is the application secret (you can find it on the Application page).

If the response is 200 OK, the license key is valid. Any other response could mean that the license key is invalid. You can choose to treat 5xx responses as valid as well for the sake of reliability.

Sharing Keys Between Applications

You can share keys between applications. It may be useful if you require a group of applications that should be accessible using the same license key.

To share keys between applications, you need to:

1. Navigate to Applications.
2. Find your application on the list and click on its name.
3. Click on the Keys tab - it can be found on the upper navigation bar.
4. Click on the New Link button.

On the next form, you will be asked to specify the direction of the link.

• Outgoing - License keys of the current application will be shared with another application that you will choose.
• Incoming - License keys of another application will be shared with the current one.

In the same form, there’s an application choice box as well.

For instance, if your application name is AppOne and you want to share its keys with AppTwo, you have to select the direction to be Outgoing and find AppTwo on the applications list.

When done, click on the Create Link button.

Webhooks

The Webhooks feature lets you receive notifications about events in your PatchKit Panel. You can use this feature to integrate PatchKit with your systems.

Webhook Events

The following events are available:

• Version Published - triggered when a new version of an application is published.
• Version Processed - triggered when a version of an application is processed.
• Version Process Failed - triggered when a version of an application fails to process.

How to Set Up Webhooks?

To set up Webhooks, you need to:

1. Go to the Applications page.
2. Select one of your applications.
3. Click on the Webhooks tab.
4. Click on the New Webhook button.

On the next page, you will be asked to provide:

• Event - the event type that will trigger the webhook.
• Request Method - the HTTP method that will be used to send the request.
• URL - the URL that will receive the webhook.
• Headers - the headers that will be sent with the request. Must be provided in JSON format.
• Request Format - the format of the request body.
• Payload - the payload that will be sent to the webhook. Must be provided in JSON format.

Finally, click on the Create button to create a webhook.

Headers Example

Headers must be provided in JSON format. Example:

{
  "Authorization": "Bearer <your_token>"
}

Payload Example

The payload must be provided in JSON format. Example:

{
  "msg": "Application published!"
}

Using Variables

You can use variables in the payload, headers, and URL. The following variables are available:

• {{app.name}} - the name of the application.
• {{app.display_name}} - the display name of the application.
• {{app.group_name}} - the name of the application group (when using channels).
• {{app.download_url}} - the download URL of the application launcher.
• {{app.direct_download_url}} - direct download URL of the application launcher.
• {{version.id}} - the ID of the published version.
• {{version.label}} - the label of the published version.
• {{version.published_at}} - the date and time when the version was published.
• {{version.humanized_content_size}} - the size of the published version in human-readable format.
• {{version.humanized_diff_size}} - the size of the published version’s diff in human-readable format.
• {{version.changes}} - the change list of the published version.
• {{version.processing_error}} - the list of errors that occurred during the version processing (if any).
• {{version.processing_started_at}} - the date and time when the version processing started.
• {{version.processing_finished_at}} - the date and time when the version processing finished.
• {{version.humanized_processing_duration}} - the duration of the version processing in human-readable

Example:

{
    "msg": "Application {{app.display_name}} version {{version.label}} has been published!"
}

How to Test Webhooks?

You can test any webhook by clicking on the Test button on the webhooks page. This will send a test request to the webhook’s URL.