Developer Zone

License Management

Revulytics Usage Intelligence allows you to maintain your own license key registry on the Revulytics Usage Intelligence server in order to track license key usage and verify the status/validity of license keys used on your clients.

There are multiple ways that the key registry is populated with license keys.

  1. Keys are collected automatically from your clients whenever you call the RUISDK.SetLicenseKey function.
  2. You can add/edit keys manually via the Revulytics Usage Intelligence dashboard.
  3. You can add/edit keys directly from your CRM by using the Revulytics Usage Intelligence Web API.

Client vs. Server Managed Licensing

Revulytics Usage Intelligence gives you the option to choose between managing your license key status (i.e. Blacklisted, Whitelisted, Expired or Activated) and key type on the server (server managed) or managing this status through the application (client managed). Applications can individually set whether each license status or license type is either Sever Managed or Client Managed by visiting the License Key Management Settings page on the Revulytics Usage Intelligence dashboard. The major difference is outlined below:

1- Client managed: The server licensing mechanism works in reporting-only mode and your application is expected to notify the server that the license status has changed through the use of RUISDK.SetLicenseData.

When to use: You have implemented your own licensing module/mechanism within your application that can identify whether the license key used by this client is blacklisted, whitelisted, expired or activated. In this case you do not need to query the Revulytics Usage Intelligence server to get this license status. However you can simply use this function to passively inform Revulytics Usage Intelligence about the license status used by the client. In this case:

  1. Revulytics Usage Intelligence will use this info to filter and report the different key types and statuses and their activity.
  2. Revulytics Usage Intelligence licensing server will operate in passive mode (i.e. reporting only).
  3. Calling RUISDK.CheckLicenseKey will return the license type and flags as Unknown (-1).

2- Server managed: You manage the key status on the server side and your application queries the server to determine the status of a particular license key by calling RUISDK.CheckLicenseKey or RUISDK.SetLicenseKey.

When to use: If you do not have your own licensing module/mechanism within your application and thus you have no way to identify the license status at the client side. In this mode, whenever a client changes their license key your application can call RUISDK.SetLicenseKey to register the new license key. In reply to this API call, the server will check if the license key exists on the key register and in the reply it will specify to your application whether this key is flagged as blacklisted, whitelisted, expired or activated, along with the type of key submitted. If you want to verify a key without actually registering a key change for this client you can use RUISDK.CheckLicenseKey which returns the same values but does not register this key with the server. In this case:

  1. The key register is maintained manually on the server by the software owner
  2. Revulytics Usage Intelligence licensing server will operate in active mode so apart from using this key info for filtering and reporting, it will also report back the key status (validity) to the SDK whenever requested through the API.
  3. Calling RUISDK.CheckLicenseKey or RUISDK.SetLicenseKey will return the 4 status flags denoting whether a registered key is: Blacklisted, Whitelisted, Expired and Activated and the key type.
  4. If the key does not exist on the server, all 4 status flags will be returned as false (0).

RUIResult RUISDK.CheckLicenseKey (String licenseKey, out List<Int32> licenseArray)

Checks the RUI Server for the license data for the supplied licenseKey. Whereas RUISDK.CheckLicenseKey is a passive check, RUISDK.SetLicenseKey changes the license key. The license array has size, indexes and values as specified in RUISDKDefines.h:

NOTE: The order of the license array data has changed from the RUI (Trackerbird) SDK V4.

RUISDK.CheckLicenseKey can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.CheckLicenseKey is a synchronous function returning when all functionality is completed.

The function accepts a String parameter that is the license key itself and a List<Int32> array of length 5 that it fills with the returned result. You may use the following constants to refer to the required value by its index from the RUILicenseKeyIndex enum:

* typeIndex (0)
* expiredIndex (1)
* activeIndex (2)
* blacklistedIndex (3)
* whitelistedIndex (4)

Each of the values 1 through 5 will be set to either 0 or 1 that refers to false or true respectively. The first value (RUILicenseKeyIndex.typeIndex) will be set to a number between 0 and 7 (inclusive) that refers to the 8 possible license types listed below. The values may also be -1 that means “Unknown”.

The following are the possible license types from the RUILicenseKeyType enum:

* unchanged (-1) - Key Type is Unchanged (when in parameter) or Unknown (when out parameter)
* evaluation (0)
* purchased (1)
* freeware (2)
* unknown (3)
* nfr (4) - Key Type is Not For Resale
* custom1 (5)
* custom2 (6)
* custom3 (7)

The following are the possible key status values from the RUILicenseKeyStatus enum:

* unchanged (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* no (0) - Key Status is No.
* yes (1) - Key Status is Yes.

Parameters:

licenseKey (String) - The license key to be checked. This value cannot be empty.

licenseArray (List<Int32> length of 5) - The vector that will be filled to contain the license status flags.

Return Type:

RUIState enum values below:

* ok                                     Function successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Function validation: Configuration has not been successfully created.
* sdkNotStarted                          Function validation: SDK has not been successfully started.
* sdkAlreadyStopped                      Function validation: SDK has already been successfully stopped.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.
* timeThresholdNotReached                Function validation: The API call frequency threshold (set by the RUI Server) has not been reached.
* networkConnectionError                 Not able to reach the RUI Server.
* networkServerError                     Error while communicating with the RUI Server.
* networkResponseInvalid                 Message format error while communicating with the RUI Server.

Code Example:

//Test a license key
mySDK.StartSDK(); //...; //Creation and initialization shown in other snippets.
String myProductKey = "xyz";
List<Int32> licenseResult;

RUIResult rc = mySDK.CheckLicenseKey(myProductKey, out licenseResult);
if(rc == RUIResult.ok)
{
    if (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex] == (Int32)RUILicenseKeyType.unchanged) {
        MessageBox.Show("License Key is unchanged");
    } else {
        String myType = "License type = " + (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex]).ToString();
        MessageBox.Show(myType);
    }
    //Check if the license key is activated
    if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("License Active");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("License Inactive");
    } else {
        MessageBox.Show("License status unknown");
    }

    //check if license key is blacklisted
    if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is black listed");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT black listed");
    } else {
        MessageBox.Show("Key blank listed status is unknown");
    }

    //Check if license key is expired
    if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is expired");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT expired");
    } else {
        MessageBox.Show("Key expiration status is unknown");
    }

    //Check if license key is white listed
    if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is white listed");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT white listed");
    } else {
        MessageBox.Show("Key white listed status is unknown");
    }
} else {
    MessageBox.Show("Failed to invoke function RUISDK.CheckLicenseKey()");
}

RUIResult RUISDK.SetLicenseKey (String newKey, out List<Int32> licenseArray, String sessionID = “”)

Checks the RUI Server for the license data for the supplied licenseKey and sets the current license to licenseKey. Whereas RUISDK.CheckLicenseKey is a passive check, RUISDK.SetLicenseKey changes the license key. The RUI Server always registers the licenseKey even if the RUI Server knows nothing about the licenseKey. When a new (unknown) licenseKey is registered, the RUI Server sets the license data to RUILicenseKeyType.unknown and the four status flags (blacklisted, whitelisted, expired, activated) to RUILicenseKeyStatus.no. The license array has size, indexes and values as specified in RUISDKCS.cs

NOTE: Different from the V4 of the RUI SDK, a sessionID parameter can be supplied (based on RUISDK.CreateConfig multi session value):

* multiSessionEnabled = false - sessionID must be empty.  This is similar to event tracking APIs.
* multiSessionEnabled = true  - sessionID must be a current valid value used in startSession(), or it can be
                                empty.  This is different than normal event tracking APIs, whereby a empty value is not be allowed.

NOTE: The order of the license array data has changed from the RUI SDK V4.

RUISDK.SetLicenseKey can be called between StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.SetLicenseKey is primarily a synchronous function, returning once the check with RUI Server has completed. Some post- processing functionality is performed asynchronously, executed on separate thread(s).

This function should be called when an end user is trying to enter a new license key into your application and you would like to confirm that the key is in fact valid (i.e. blacklisted or whitelisted), active, or expired. The function is very similar to the RUISDK.CheckLicenseKey function, however rather than just being a passive license check, it also registers the new key with the server and associates it with this particular client installation.

The function accepts a String parameter that is the license key itself and a List<Int32> array of length 5 that it fills with the returned result. You may use the following constants to refer to the required value by its index from the RUILicenseKeyIndex enum:

* typeIndex (0)
* expiredIndex (1)
* activeIndex (2)
* blacklistedIndex (3)
* whitelistedIndex (4)

Each of the values 1 through 5 will be set to either 0 or 1 that refers to false or true respectively. The first value (RUILicenseKeyIndex.typeIndex) will be set to a number between 0 and 7 (inclusive) that refers to the 8 possible license types listed below. The values may also be -1 that means “Unknown”.

The following are the possible license types from the RUILicenseKeyType enum:

* unchanged (-1) - Key Type is Unchanged (when in parameter) or Unknown (when out parameter)
* evaluation (0)
* purchased (1)
* freeware (2)
* unknown (3)
* nfr (4) - Key Type is Not For Resale
* custom1 (5)
* custom2 (6)
* custom3 (7)

The following are the possible key status values from the RUILicenseKeyStatus enum:

* unchanged (-1) - Key Status is Unchanged (when in parameter) or Unknown (when out parameter).
* no (0) - Key Status is No.
* yes (1) - Key Status is Yes.

Parameters:

licenseKey (String) - The license key to be checked. This value cannot be empty.

licenseArray (List<Int32> of length 5) - The vector that will be filled to contain the license status flags.

sessionID (String) - An optional session ID complying with above usage (content conditioning and validation rules in RUISDK.StartSession).

Return Type:

RUIState enum values below:

* ok                                     Function successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Function validation: Configuration has not been successfully created.
* sdkNotStarted                          Function validation: SDK has not been successfully started.
* sdkAlreadyStopped                      Function validation: SDK has already been successfully stopped.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.
* timeThresholdNotReached                Function validation: The API call frequency threshold (set by the RUI Server) has not been reached.
* networkConnectionError                 Not able to reach the RUI Server.
* networkServerError                     Error while communicating with the RUI Server.
* networkResponseInvalid                 Message format error while communicating with the RUI Server.

Code Example:

//Register a new license key
bool useDefaultReachOutHandler = false;
RUISDK mySDK = new RUISDK(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.
String myProductKey = "xyz";
List<Int32> licenseResult;

RUIResult rc = mySDK.SetLicenseKey(myProductKey, out licenseResult);
if(rc == RUIResult.ok)
{
    if (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex] == (Int32)RUILicenseKeyType.unchanged) {
        MessageBox.Show("License Key is unchanged");
    } else {
        String myType = "License type = " + (licenseResult[(Int32)RUILicenseKeyIndex.typeIndex]).ToString();
        MessageBox.Show(myType);
    }
    //Check if the license key is activated
    if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("License Active");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.activeIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("License Inactive");
    } else {
        MessageBox.Show("License status unknown");
    }

    //check if license key is blacklisted
    if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is black listed");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.blacklistedIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT black listed");
    } else {
        MessageBox.Show("Key blank listed status is unknown");
    }

    //Check if license key is expired
    if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is expired");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.expiredIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT expired");
    } else {
        MessageBox.Show("Key expiration status is unknown");
    }

    //Check if license key is white listed
    if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.yes){
        MessageBox.Show("Key is white listed");
    } else if (licenseResult[(Int32)RUILicenseKeyIndex.whitelistedIndex] == (Int32)RUILicenseKeyStatus.no) {
        MessageBox.Show("Key is NOT white listed");
    } else {
        MessageBox.Show("Key white listed status is unknown");
    }
} else {
    MessageBox.Show("Failed to invoke function RUISDK.setLicenseKey()");
}