Developer Zone

License Management

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

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

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

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

Client vs. Server Managed Licensing

Trackerbird 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 youself through your client (client managed). ou 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 Trackerbird 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 setLicense().

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

  1. Trackerbird will use this info filter and report the different key types and statuses and their activity.
  2. Trackerbird licensing server will operate in passive mode (i.e. reporting only).
  3. Calling keyCheck() will return FUNCTION_NOT_AVAILABLE 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 keyCheck() or keyChanged().

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 keyChanged() 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 keyCheck() 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. Trackerbird 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 keyCheck() or keyChanged() 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).
keyCheck(licKey)

By using this function, your software can validate a license key (entered by your client) with the key registry stored on the Trackerbird server. The function accepts a string parameter which is the license key itself and returns a tuple of 6 int values as explained below.

Parameters:licKey (str) – The license key to be tested.

rtype: Tuple in the format (<Status>, <Activated>, <Blacklisted>, <Expired>, <Whitelisted>, <KeyType>)

Status may be any of the following return codes:

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* CONN_ERROR (-2)
* AUTH_FAILURE (-3)
* SERVER_ERROR (-4)
* APP_CONFIG_NOT_LOADED (-7)

Each of the following 4 values will be set to either 0 or 1, which refer to false or true respectively. The 6th value will be set to a number between 0 and 7 (both included) which refer to the 8 possible license types listed below. The values may also be -1 which refers to “Function not available”.

You may use the following constants to refer to the required value by its index:

* KEY_ACTIVE_INDEX (1)
* KEY_BLACKLIST_INDEX (2)
* KEY_EXPIRED_INDEX (3)
* KEY_WHITELIST_INDEX (4)
* KEY_TYPE_INDEX (5)

The following are the possible license types

* KEYTYPE_EVALUATION (0)
* KEYTYPE_PURCHASED (1)
* KEYTYPE_FREEWARE (2)
* KEYTYPE_UNKNOWN (3)
* KEYTYPE_NFR (4)
* KEYTYPE_CUSTOM1 (5)
* KEYTYPE_CUSTOM2 (6)
* KEYTYPE_CUSTOM3 (7)

Note: Whenever a license key is sent to the server using this function, the key is automatically encrypted by the Trackebird SDK before being sent to the server.

Code Example:

#Test a license key
prod_key= "xyz";
license_result = Trackerbird.keyCheck(prod_key)
if license_result[0] == 0:
    #Check if the license is activated
    if license_result[1] == 1:
        print("License Active")
    else:
        print("License Inactive")

    #Check if key is blacklisted
    if license_result[2] == 1:
        print("Key is blacklisted")
    else:
        print("Key is NOT blacklisted")

    #Check if key is expired
    if license_result[3] == 1:
        print("Key is expired")
    else:
        print("Key is NOT expired")

    #Check if key is whitelisted
    if license_result[4] == 1:
        print("Key is whitelisted")
    else:
        print("Key is NOT whitelisted")
else:
    print("Failed to invoke function keyCheck")
keyChanged(newKey)

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. not blacklisted). The function is very similar to the keyCheck() 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 which is the license key itself and returns a tuple of 6 int values as explained below.

Parameters:newKey (str) – The license key to be tested.

rtype: Tuple in the format (<Status>, <Activated>, <Blacklisted>, <Expired>, <Whitelisted>, <KeyType>)

Status may be any of the following return codes:

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* CONN_ERROR (-2)
* AUTH_FAILURE (-3)
* SERVER_ERROR (-4)
* APP_CONFIG_NOT_LOADED (-7)

Each of the following 4 values will be set to either 0 or 1, which refer to false or true respectively. The 6th value will be set to a number between 0 and 7 (both included) which refer to the 8 possible license types listed below. The values may also be -1 which refers to “Function not available”.

You may use the following constants to refer to the required value by its index:

* KEY_ACTIVE_INDEX (1)
* KEY_BLACKLIST_INDEX (2)
* KEY_EXPIRED_INDEX (3)
* KEY_WHITELIST_INDEX (4)
* KEY_TYPE_INDEX (5)

The following are the possible license types

* KEYTYPE_EVALUATION (0)
* KEYTYPE_PURCHASED (1)
* KEYTYPE_FREEWARE (2)
* KEYTYPE_UNKNOWN (3)
* KEYTYPE_NFR (4)
* KEYTYPE_CUSTOM1 (5)
* KEYTYPE_CUSTOM2 (6)
* KEYTYPE_CUSTOM3 (7)

Note: Whenever a license key is sent to the server using this function, the key is automatically encrypted by the Trackebird SDK before being sent to the server.

Code Example:

#Register a new license key
new_key= "xyz";
license_result = Trackerbird.keyCheck(new_key)
if license_result[0] == 0:
    #Check if the license is activated
    if license_result[1] == 1:
        print("License Active")
    else:
        print("License Inactive")

    #Check if key is blacklisted
    if license_result[2] == 1:
        print("Key is blacklisted")
    else:
        print("Key is NOT blacklisted")

    #Check if key is expired
    if license_result[3] == 1:
        print("Key is expired")
    else:
        print("Key is NOT expired")

    #Check if key is whitelisted
    if license_result[4] == 1:
        print("Key is whitelisted")
    else:
        print("Key is NOT whitelisted")
else:
    print("Failed to invoke function keyChanged")