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 to detect and report abused keys. See How to Price Software Licensing for a high-level overview of what is included with this service.

• SDK Integration - Getting Started With Usage Intelligence - Part 1
• Event Tracking - Getting Started With Usage Intelligence - Part 2
• Software License Usage Tracking - Getting Started With Usage Intelligence - Part 3

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.

To configure licensing management mode:

1. Log in to the Usage Intelligence Dashboard.
2. Open the Additional Reports > License Key Registry page.
3. Click the Edit button in the License Key Settings box. The License Key Registry Settings dialog box opens.
   
   
4. Select the licensing management mode for each status/type and click Save & Update. 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.

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, blocked, etc.

In the example below, we are notifying Usage Intelligence 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.

To configure client managed licensing mode:

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, such as 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, keyBlocked: 0, keyAllowed: 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 Blocked: An integer representing whether the license key is blocked (1), not blocked (0) or unchanged (-1).
   • Key Allowed: An integer representing whether the license key is allowed (1), not allowed (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.

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

Server Managed

In this mode, license keys are collected/stored on the Usage Intelligence 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 Usage Intelligence server also keeps a 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 License Key Registry Management.

You can view or manage the license keys that are available on the server by logging into the Usage Intelligence Dashboard and opening the Additional Reports > License Key Registry page. 

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.

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, such as 5_6_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 two 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 Blocked
  • License Allowed
• 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.

To register a key from the client:

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, such as 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, open the License Key Registry page, click the ... button in the Filters box, and select Add Filter to open the Filters slideout. Use the controls on the Filters slideout to add filters, and then click on the Apply button to apply the filters.

This brings the Getting Started series of posts to an end. We recommend you review the full documentation available on the Usage Intelligence SDK Download Links and API Documentation page of the Revenera community to benefit from the advanced features provided by the Usage Intelligence SDK. If you require any further assistance, contact Revenera Support and we would be happy to help!