Revulytics Blog

Software License Usage Tracking - Getting Started with Usage Intelligence - Part 3

January 4, 2017

Subscribe

In the last article of this 3 part series, we will look at the license key management capabilities offered by Usage Intelligence. In addition to Software Analytics, Usage Intelligence provides a License Key Usage Tracking and Piracy Monitoring Service. This functionality is embedded as part of the Analytics SDK and allows you to validate keys on the client, track which license keys are in use as well as detect and report abused keys. Please check out this blog post for a high-level overview of what is included with this service.

There are two modes of licensing management available, Client or Server managed (both explained later).  Each mode can be configured from the License Key Registry page as follows:

  1. Log in to the Usage Intelligence Dashboard, go to the Administration page and under Product Settings click on License Key Registry
  2. Click on the Settings tab

    Usage Intelligence: Manage License Keys

  3. Select the licensing management mode for each flag and click Save. By default, the licensing management is set to Client Managed. You may choose to have a mix of Client and Server managed for the license flags, for example, you might want to handle activation on the client side while managing the rest on the server.

Read on for more information on the different modes and when to use them.

1. Client Managed

In this mode, your application notifies the server when the license status has changed, and the licensing mechanism is used for reporting purposes only. It is generally used when you already have a licensing management system in place that can identify whether a license key is valid, expired, blacklisted etc..

In the example below, we are notifying Revulytics of a new license status when the user changes the license key in the application by using the SetLicenseData method. Note that the license key is not collected when using this method, but only the status flags are registered for reporting.

  1. Open the class where you handle the licensing key change
  2. At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0
  3. Add the following code when the user enters a new key. In this example we are using the Click event of the Save button:
private void btnSave_Click(object sender, EventArgs e)
{
//rui is your RUISDK instance
rui.SetLicenseData(keyType: (int)RUILicenseKeyType.purchased,
keyExpired: 0, keyActivated: 1, keyBlacklisted: 0, keyWhitelisted: 0);

//The rest of your code…
}

The SetLicenseData() function has 5 required parameters:

Key Type – A value from the RUILicenseKeyType enum representing the type of key

Key Expired – An integer representing whether the license key is expired (1), not expired (0) or unchanged (-1)

Key Activated - An integer representing whether the license key is activated (1), not activated (0) or unchanged (-1)

Key Blacklisted – An integer representing whether the license key is blacklisted (1), not blacklisted (0) or unchanged (-1)

Key Whitelisted – An integer representing whether the license key is whitelisted (1), not whitelisted (0) or unchanged (-1)

Any license flags which do not apply to your license model can be set to -1.

This function also accepts an optional string parameter for the session ID. In our example we did not specify this value since our calculator application does not manage sessions itself.

  1. Build your solution, run the application, set the license data, and close the application
  2. From your Revulytics Product Dashboard go to Product Metrics > Licenses in Use and License Status to view the licensing reports.

    Software Licensing Reports with Software Usage Analytics

2. Server Managed

In this mode, license keys are collected/stored on the Revulyitcs server and you can use the SDK to check the real-time status of a license key from within your application. In this mode the Revulytics server also keeps count of the number of installations that are sharing each license key. This will enable you to sync with your CRM or licensing service to detect piracy or license key abuse. This mode is also ideal if you do not have a license key verification system in place already.

Uploading keys from your CRM: To use Server Managed licensing you will need to submit your license keys and any information about these keys to the License Key Registry. You can do this by entering/editing license keys manually or through the Web API.  More info on using the Web API can be found in the documentation.

You can view or manage the license keys that are available on the server by going to the dashboard, navigating to the Administration page and under Product Settings click on License Key Registry.

Usage Intelligence: License Key Registry

Once the license keys are in the registry, you are now ready to register and validate keys from your application.

Validating a Key from the Client

The following example uses the CheckLicenseKey method to retrieve the license key information from the server.

  1. Open the class where you handle the licensing key check
  2. At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0

  3. Add the following code when the user enters a new key. In this example we are using the Click event of the Submit button:
private void btnSubmit_Click(object sender, EventArgs e)
{
List<int> licenseResult;

//rui is your RUISDK instance
RUIResult result = rui.CheckLicenseKey(txtKey.Text, out licenseResult);

//The rest of your code…
}

The CheckLicenseKey() function has 2 required parameters, a string which is the license key you would like to validate, and a List<int> which will be filled with the returned result and will contain the following properties:

    • Key Type – A value from the RUILicenseKeyType enum representing the key type (Evaluation, Purchased, Freeware etc..)
    • The license key flags with a value of 0 if false, 1 if true, and -1 if unknown:
      • License Expired
      • License Activated
      • License Blacklisted
      • License Whitelisted
    • If the key does not exist on the server, all the status flags will be returned with a value of -1
    • If a status flag is set to Client managed, the returned value for that specific flag will always be -1

Registering a Key from the Client

Registering a key is similar to validating a key, however, you need to use the SetLicenseKey method.

  1. Open the class where you handle the licensing key change
  2. At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0

  3. Add the following code when the user enters a new key. In this example we are using the Click event of the Save button:
private void btnSubmit_Click(object sender, EventArgs e)
{
List<int> licenseResult;
//rui is your RUISDK instance
RUIResult result = rui.SetLicenseKey(txtKey.Text, out licenseResult);
//The rest of your code… }

When a status flag is set to Client Managed, the returned value for that specific flag will always be -1.

If the key does not exist on the server, it will return the license type as Unknown while the rest of the status flags will have a value of 0. The key will also be added to the License Key Registry and this makes it easy for you to track illegitimate keys by searching for Auto Collected keys with an Unknown type. To do this go to the Usage Intelligence Product Dashboard, navigate to Manage Product > License Key Registry and click on the Show Advanced Key Search. Once on the License Key Registry page click on the Filters tab, add your filters and click on the Apply Filter button.

Usage Intelligence: License Key Filtering

This brings the Getting Started series of posts to an end. We recommend you review the full documentation available in the Developer Zone to benefit from the advanced features provided by the Usage Intelligence SDK. If you require any further assistance, contact us at our helpdesk and we would be happy to help!

Get Started with Usage Analytics

Register a free account and start touring analytics immediately. Then, simply integrate the SDK into your app to start your free trial. Start making data-driven decisions.

Post written by Arielle Bonnici

Software Developer & Technical Writer