Developer Zone

License Management

Revulytics Usage Intelligence allows you to maintain your own license key registry on the 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 the key registry is populated with license keys.

  1. Keys are collected automatically from your clients whenever you call the changeKey method.
  2. You can add/edit keys manually via the Usage Intelligence web UI.
  3. You can upload keys in bulk using CSV files from the Usage Intelligence web UI.
  4. You can add/edit keys directly from your CRM by using the Usage Intelligence Web API.

Please check out this KBase article to learn about the correct file format when uploading keys to the Usage Intelligence Key Registry: http://helpdesk.revulytics.com/knowledgebase.php?article=41.

Client vs. Server Managed Licensing

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 yourself through your client (client managed). You 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 Usage Intelligence web UI. 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 setLicenseInformationForKeyType.

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 Usage Intelligence server to get this license status. However you can simply use this function to passively inform Usage Intelligence about the license status used by the client. In this case:

  1. Usage Intelligence will use this info filter and report the different key types and statuses and their activity.
  2. Usage Intelligence licensing server will operate in passive mode (i.e. reporting only).
  3. Calling checkKey will return TBC_FUNCTION_NOT_AVAIL since the key status is client managed.

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 checkKey or changeKey.

When to use: If you do not have your own licensing module/mechanism within your application and thus you have no way to to identify the license status at the client side. In this mode, whenever a client changes their license key your application can call changeKey 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 checkKey that 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. 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 checkKey or changeKey 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 TBC_KEY_STATUS_NO (0).

(TBCRESULT) checkKey: (NSString*)key returningLicenseArray: (NSMutableArray*)licenseArray

By using this method, your software can validate a license key (entered by your client) with the key registry stored on the Usage Intelligence server. The function accepts a string parameter that is the license key itself and returns a TBLicenseInfo object.

Parameters:

key (NSString*) - The license key to be tested.

licenseArray (NSMutableArray*) - This is an out parameter. The Revulytics Usage Intelligence SDK will always update the array

object. This object should be released when the Revulytics Usage Intelligence SDK Client no longer needs it. The value will be a 5-element integer array containing the License Status Flag values at the following indexes:

* TBC_KEY_ACTIVE_INDEX    (0)
* TBC_KEY_BLACKLIST_INDEX (1)
* TBC_KEY_EXPIRED_INDEX   (2)
* TBC_KEY_WHITELIST_INDEX (3)
* TBC_KEY_TYPE_INDEX      (4)

NOTE: Any of the array elements can be set to -1 to indicate the data is not available.

Each of the first four (4) array elements will be set to one of the following values:

* TBC_KEY_STATUS_UNCHANGED (-1)
* TBC_KEY_STATUS_NO        ( 0)
* TBC_KEY_STATUS_YES       ( 1)

The last array element (KEYTYPE) will be set to one of the following License Type values:

* TBC_FUNCTION_NOT_AVAILABLE (-1)
* TBC_KEYTYPE_EVALUATION     ( 0)
* TBC_KEYTYPE_PURCHASED      ( 1)
* TBC_KEYTYPE_FREEWARE       ( 2)
* TBC_KEYTYPE_UNKNOWN        ( 3)
* TBC_KEYTYPE_NFR            ( 4)
* TBC_KEYTYPE_CUSTOM1        ( 5)
* TBC_KEYTYPE_CUSTOM2        ( 6)
* TBC_KEYTYPE_CUSTOM3        ( 7)

Return Type:

Integer constant from one of the following values:

* TBC_OK                  (  1)
* TBC_FUNCTION_NOT_AVAIL  ( -1)
* TBC_CONN_ERROR          ( -2)
* TBC_AUTH_FAILURE        ( -3)
* TBC_SERVER_ERROR        ( -4)
* TBC_NOT_STARTED         ( -7)
* TBC_INVALID_PARAMETER   ( -9)
* TBC_APP_STOPPED         (-14)
* TBC_INTERNAL_ERROR      (-99)

Code Example:

Passing “Test Key” as the key and checking the return

//OS X / ObjC Example.
//Test a license key
TBCTrackerbirdOBJC* tbcInstance; //...; //Creation and initialization shown in other snippets.

NSString* prod_key = @"Test Key";
NSMutableArray* license_result = [[NSMutableArray alloc] init];
if ([tbcInstance checkKey:prod_key returningLicenseArray:license_result] == TBC_OK) {

//Check license key type
    if ([license_result[TBC_KEY_TYPE_INDEX] int32Value] == TBC_FUNCTION_NOT_AVAIL) {
        NSLog(@"License key information is unavailable");
    } else {
        NSLog(@"License key type is %d", [license_result[TBC_KEY_ACTIVE_INDEX] int32Value]);
    }
    //Check if the license is activated
    if ([license_result[TBC_KEY_ACTIVE_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"License is active");
    } else if ([license_result[TBC_KEY_ACTIVE_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"License is NOT active");
    } else {
        NSLog(@"License active status unknown");
    }
    //Check if key is blacklisted
    if ([license_result[TBC_KEY_BLACKLIST_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"Key is blacklisted");
    } else if ([license_result[TBC_KEY_BLACKLIST_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"Key is NOT blacklisted");
    } else {
        NSLog(@"Key blacklisted status unknown");
    }
    //Check if key is expired
    if ([license_result[TBC_KEY_EXPIRED_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"Key is expired");
    } else if ([license_result[TBC_KEY_EXPIRED_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"Key is NOT expired");
    } else {
        NSLog(@"Key expiration status unknown");
    }
    //Check if key is whitelisted
    if ([license_result[TBC_KEY_WHITELIST_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"Key is whitelisted");
    } else if ([license_result[TBC_KEY_WHITELIST_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"Key is NOT whitelisted");
    } else {
        NSLog(@"Key whitelisted status unknown");
    }
} else {
    NSLog(@"Failed to invoke function checkKey");
}
//  [prod_key release];       //Either release or use ARC.
//  [license_result release]; //Either release or use ARC.

(TBCRESULT) changeKey: (NSString*)newKey returningLicenseArray: (NSMutableArray*)licenseArray

This method 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 method is very similar to the checkKey method, 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.

Parameters:

licKey (string) - The license key to be tested.

licenseArray (NSMutableArray*) - This is an out parameter. The Revulytics Usage Intelligence SDK will always update the array

object. This object should be released when the Revulytics Usage Intelligence SDK Client no longer needs it. The value will be a 5-element integer array containing the License Status Flag values at the following indexes:

* TBC_KEY_ACTIVE_INDEX    (0)
* TBC_KEY_BLACKLIST_INDEX (1)
* TBC_KEY_EXPIRED_INDEX   (2)
* TBC_KEY_WHITELIST_INDEX (3)
* TBC_KEY_TYPE_INDEX      (4)

NOTE: Any of the array elements can be set to -1 to indicate the data is not available.

Each of the first four (4) array elements will be set to one of the following values:

* TBC_KEY_STATUS_UNCHANGED (-1)
* TBC_KEY_STATUS_NO        ( 0)
* TBC_KEY_STATUS_YES       ( 1)

The last array element (KEYTYPE) will be set to one of the following License Type values:

* TBC_FUNCTION_NOT_AVAILABLE (-1)
* TBC_KEYTYPE_EVALUATION     ( 0)
* TBC_KEYTYPE_PURCHASED      ( 1)
* TBC_KEYTYPE_FREEWARE       ( 2)
* TBC_KEYTYPE_UNKNOWN        ( 3)
* TBC_KEYTYPE_NFR            ( 4)
* TBC_KEYTYPE_CUSTOM1        ( 5)
* TBC_KEYTYPE_CUSTOM2        ( 6)
* TBC_KEYTYPE_CUSTOM3        ( 7)

Return Type:

Integer constant from one of the following values:

* TBC_OK                  (  1)
* TBC_FUNCTION_NOT_AVAIL  ( -1)
* TBC_CONN_ERROR          ( -2)
* TBC_AUTH_FAILURE        ( -3)
* TBC_SERVER_ERROR        ( -4)
* TBC_NOT_STARTED         ( -7)
* TBC_INVALID_PARAMETER   ( -9)
* TBC_APP_STOPPED         (-14)
* TBC_INTERNAL_ERROR      (-99)

Code Example:

Changing the key to “Test Key Number 2” and checking the return
//OS X / ObjC Example.
//Register a new license key
TBCTrackerbirdOBJC* tbcInstance; // = ...; //Creation and initialization shown in other snippets.

NSString* new_key = @"Test Key Number 2";
NSMutableArray* license_result = [[NSMutableArray alloc] init];
if ([tbcInstance changeKey:new_key returningLicenseArray:license_result] == TBC_OK) {

    //Check license key type
    if ([license_result[TBC_KEY_TYPE_INDEX] int32Value] == TBC_FUNCTION_NOT_AVAIL) {
        NSLog(@"License key information is unavailable");
    } else {
        NSLog(@"License key type is %d", [license_result[TBC_KEY_ACTIVE_INDEX] int32Value]);
    }
    //Check if the license is activated
    if ([license_result[TBC_KEY_ACTIVE_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"New key license is active");
    } else if ([license_result[TBC_KEY_ACTIVE_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"New key license is NOT active");
    } else {
        NSLog(@"New key license active status unknown");
    }
    //Check if key is blacklisted
    if ([license_result[TBC_KEY_BLACKLIST_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"New key is blacklisted");
    } else if ([license_result[TBC_KEY_BLACKLIST_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"New key is NOT blacklisted");
    } else {
        NSLog(@"New key blacklisted status unknown");
    }
    //Check if key is expired
    if ([license_result[TBC_KEY_EXPIRED_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"New key is expired");
    } else if ([license_result[TBC_KEY_EXPIRED_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"New key is NOT expired");
    } else {
        NSLog(@"New key expiration status unknown");
    }
    //Check if key is whitelisted
    if ([license_result[TBC_KEY_WHITELIST_INDEX] int32Value] == TBC_KEY_STATUS_YES) {
        NSLog(@"New key is whitelisted");
    } else if ([license_result[TBC_KEY_WHITELIST_INDEX] int32Value] == TBC_KEY_STATUS_NO) {
        NSLog(@"New key is NOT whitelisted");
    } else {
        NSLog(@"New key whitelisted status unknown");
    }
} else {
    NSLog(@"Failed to invoke function changeKey");
}
//  [new_key release];        //Either release or use ARC.
//  [license_result release]; //Either release or use ARC.