• How it works?
• Enabling license keys
• Setup Overview
• Distributing collection
• Distributing individual keys
• Blocking collections and keys
• Securing the application from being used
  • Reading the license key
  • Verifying the license key
  • Tolerance to errors
    • Missing +patcher-data-location parameter
    • Invalid app_data.json content
    • Keys server not reachable
• Sharing keys between applications
  • Creating a Link
  • Testing a link
  • Modifying or removing a link

PatchKit allows you to use license keys with your applications. If you’re looking for a way of limiting who should be allowed to start your application, license keys may be the best available option.

How it works?

As soon as license keys are enabled for your application, your users will be prompted to enter a license key by the Launcher. Failing to do so prevents the user from downloading the application.

As you can see, having license keys enabled for your application only prevents the user from downloading it and any of the updates. As soon as your application is on the hard drive, it can be started without the need of having a valid license key if the user is smart enough to go into the installation directory and launch it from its executable instead of using the Launcher. We call this approach a non-intrusive DRM since it requires the user to be fair without any negative impact on the app’s mechanics.

If you find this method of validation insufficient, it’s recommended to implement additional keys check inside of your application’s code. Details of how to do that can be found inside Securing the application from being used section.

Enabling license keys

License keys are disabled for all new applications by default. To enable license keys:

1. Go to Applications listing.
2. Click on the name of your application.
3. Click on the Keys tab - it can be found on the upper navigation bar.
4. Find the Status option and change it to Enabled.

Setup Overview

License keys can be split into collections. Collection is a named set of license keys, and you may think of it as a box with keys created for a particular purpose. It’s a lot easier to work with collections rather than with individual keys.

There are several properties that collections may have:

1. Distributed - This flag tells you whether the collection has been distributed. This flag is set manually and exists only for organizational purposes.
2. In Use - The number of keys that have been used at least once. When a key has been used more than once, this number won’t change.
3. Blocked - Tells whether this collection has been blocked from further use. Users can no longer use blocked keys. You can always unblock any previously blocked collections.
4. Status - Keys generation status. If you order a large number of keys, you will have to wait sometime before the collection is ready to be used.

Distributing collection

There are two ways to distribute keys from a collection. You can:

1. Click on the collection name and copy individual keys from the listing.
2. Get a CSV file containing all the keys.

As soon as a collection or a license key is distributed, it’s recommended to set distributed flag to true, so you don’t distribute it twice by mistake. To mark the collection as distributed, click the Action button and then select Mark as distributed from the drop-down menu.

Distributing individual keys

If you’d like to distribute a small amount of license keys, go into a collection and:

1. Select the keys you want to mark as distributed using the checkbox on the left.
2. Click on the With selected… button that can be found at the bottom of the page.
3. From the drop-down menu choose Mark as distributed option.

Blocking collections and keys

Collections and keys can be blocked from further use in a manner similar to marking collections and keys as distributed. Note that blocking keys and collections have a real effect on the users by forbidding them from downloading the application and updates.

Securing the application from being used

License keys prevent the application from being downloaded by default, as soon as it resides on the hard drive, it can be started without any additional checks. Here you can find the instructions on making sure that users won’t be able to use the application without a valid license key.

Reading the license key

You can read the entered license key from your application. Launcher is passing to your app’s process an argument that looks similar to this:

" +patcher-data-location app_data.json ”

The app_data.json file contents look like this:

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

Make sure to verify that product_key_encryption is set to none and then read the product_key.

Verifying the license key

To verify a license key, you need one more thing - your application secret. Make sure to hard-code it within your application. Then make a GET request to:

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

Make sure to replace LICENSE_KEY with the entered license key, and APP_SECRET with your application secret string. Now expect to receive HTTP 200 OK response and ignore the body content. Any other response code would mean that something is wrong with the license key and the user is most probably not authorized to use the application.

Tolerance to errors

Missing +patcher-data-location parameter

If you cannot find this parameter within your application arguments, the user could’ve launched the application directly from the executable. You can try to locate this file manually or display an error with a request to start the application using the Launcher.

Invalid app_data.json content

If the content of app_data.json file is different than you’ve expected, somebody might’ve tried to point your application to a different file. You should terminate the process immediately and probably investigate this situation.

Keys server not reachable

If this happens, usually a lack of the Internet connection may be the reason. Then it’s up to you to decide if you allow the user to use your application. It may be the right approach to allow to use it offline at all times or for a limited amount of time.

Sharing keys between applications

License keys can be shared between applications. It may be useful if you require having a group of applications that should be accessible using the same license key. Like:

• A bundle of multiple applications
• The same application for multiple architectures / operating systems
• An application with multiple channels

There’s no limit to how many links you can create.

Creating a Link

Sharing keys between two applications can be done by making a link. To create a link:

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.

Testing a link

To test a link, simply try using a license key on all of the applications that are linked.

Modifying or removing a link

Links cannot be modified. If you want to change the direction or the application linked, the simplest approach would be to remove a link and create a new one.

To remove a link:

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. Find the link on the Links list that you want to remove and then click on the delete label.