Developer Zone

SDK Configuration

Before an application can start reporting usage to the Revulytics Usage Intelligence SDK, it must first provide some basic information such as the location of where the SDK will create and save its working files, the application Product ID and the CallHome URL.

You should always attempt to fill in as much accurate and specific details as possible since this data will then be used by the Usage Intelligence Analytics Server to generate the relevant reports. The more (optional) details you fill in about your product and its licensing state, the more filtering and reporting options will be available to you inside the Usage Intelligence portal.

Getting SDK Version Information

(NSString*) createSDKVersionString

This function returns the SDK Version String (NSString) for this Revulytics Usage Intelligence SDK Instance. The SDK Version String contains the following formatted information:

Revulytics Usage Intelligence SDK version [VER_NUM] for [PLATFORM]/[SHIM]

Where:

* VER_NUM      is X.Y.Z  (currently 4.0.1)
* PLATFORM     is WINDOWS, OSX, or LINUX
* SHIM         is only provided if using a shim layer
               and if provided will be either C, ObjC, or .NET

Return Type:

Formatted string in form of “Revulytics Usage Intelligence SDK version [VER_NUM] for [PLATFORM]/[SHIM]”

Setting the data path

(TBCRESULT) setFilePath: (NSString*)filePath

This method sets the file path where the Revulytics Usage Intelligence SDK will create and save its working files. If the path is not set, the SDK will place the files working directory of the application. It is important to remember that the calling process should have read/write accessibility to the location.

IMPORTANT - This function needs to be called BEFORE any other method - including createConfigWithURL.

Parameters:

filePath (NSString*) - The location where to create and save the Revulytics Usage Intelligence SDK working files.

Return Type:

Integer constant value with the following possible values:

* TBC_OK  (1)
* TBC_CONFIG_ALREADY_CREATED (-6)
* TBC_INVALID_PARAMETER  (-9)
* TBC_INVALID_PATH  (-10)
* TBC_ACCESS_DENIED (-11)
* TBC_INTERNAL_ERROR  (-99)

Initializing the configuration

Before calling any other method other than setFilePath, the createConfigWithURL method must be called in order to initialize the configuration. The method signature is as follows:

(TBCRESULT) createConfigWithURL: (NSString*)url productID: (NSString*)productID productVersion: (NSString*)productVersion productBuildNumber: (NSString*)buildNumber multiSessionEnabled: (BOOL)multiSessionEnabled

Parameters:
url (NSString*) - CallHome URL: Every product registered with Usage Intelligence has its own unique CallHome URL

usually in the form ‘http://xxxxx.tbnet1.com’. This URL is generated automatically on account creation and is used by the SDK to communicate with the Usage Intelligence server. You can get this URL from the Developer Zone once you login to the customer area. If you have a Premium product account you may opt to use your own custom CallHome URL (such as http://updates.yourdomain.com) that must be setup as a CNAME DNS entry pointing to your unique Usage Intelligence URL. Please note that before you can use your own custom URL you must first inform Revuyltics Usage Intelligence support (support-rui@revulytics.com) to register your domain with the Usage Intelligence server. If you fail to do this, the server will automatically reject any incoming calls using yourdomain.com as a CallHome URL.

IMPORTANT: Once you call this method for the first time, a configuration file (tbconfig.xml) is created. This contains most configuration values including the URL. Once this file is created, the URL passed in this method is ignored, and the one inside the config file is used. This is done so that the server can instruct the Revulytics Usage Intelligence SDK to start using a new URL in cases of URL change. Also, every Usage Intelligence product has a unique URL. Therefore, if during testing you use a product account and then you register another product ID for production, it is important that you delete all Usage Intelligence data files or else, the clients will keep trying to use the old URL that won’t match the new product ID.

IMPORTANT - The URL should start with http://

productID (NSString*) - This is a unique 10-digit Product ID number that identifies your product with
the Usage Intelligence server. You can get this ID from the Developer Zone once you login to the customer area.

productVersion (NSString*) - The version number of the application being run.

productBuildNumber (NSString*) - The build number of the application being run.

multiSessionEnabled (BOOL) - Whether multiple user sessions can be present in a single application runtime. Refer to Single vs. Multiple session modes.

Return Type:

Integer constant value with the following possible values:

* TBC_OK  (1)
* TBC_CONFIG_ALREADY_CREATED (-6)
* TBC_INVALID_PARAMETER  (-9)
* TBC_FILE_PATH_NOT_SET  (-13)
* TBC_INTERNAL_ERROR  (-99)

Code Example:

TBCTrackerbirdOBJC* tbcInstance; // = ...; //Creation and initialization shown in other snippets.

NSString* url = @"http://INSERT-YOUR-URL";
NSString* productID = @"INSERT-YOUR-PROD-ID";
NSString* productVersion = @"1.2.3";
NSString* productBuildNumber = @"4567";
BOOL      multiSessionEnabled = NO;

[tbcInstance createConfigWithURL:url productID:productID productVersion:productVersion productBuildNumber:productBuildNumber multiSessionEnabled:multiSessionEnabled];

Single vs. Multiple session modes

In desktop software, a single application instance would normally have only one single user session. This means that such an application would only show one window (or set of windows) to a single user and interaction is done with that single user. If the user would like to use two different sessions, two instances of the application would have to be loaded that would not affect each other. In such cases, you should use the single session mode, that handles user sessions automatically and assumes that one process (instance) means one user session.

The multiple session mode needs to be used in multi-user applications, especially applications that have web interfaces. In such applications, a number of users might be using the same application process simultaneously. In such cases, you need to manually tell Revulytics Usage Intelligence SDK when user sessions start and stop, and also how to link events (see Feature / Event Tracking) to user sessions. To do this, when starting or stopping a user session, the methods startSession and stopSession should be used, and when tracking events, a session ID needs to be passed as a parameter.

Providing further data

Apart from the four compulsory parameters that must be passed to createConfigWithURL, there are a number of methods meant to provide further data to the SDK that would either help generate better reports such as by providing the product language or edition name.

Any of these methods can also be called during application runtime such as for changing privacy settings that the user just set or changing the key type after the user enters a new license key.

License Management

(TBCRESULT) setLicenseInformationForKeyType: (int)keyType expiredStatus: (int)expiredStatus activatedStatus: (int)activatedStatus blacklistedStatus: (int)blacklistedStatus whitelistedStatus:* (int)whitelistedStatus

This method is used to set the type of license key being used by the client and the 4 license status flags. Although this function accepts 5 parameters, it can be used to set any subset of these values. If a value is not to be changed, a null value should be sent as its corresponding parameter.

Parameters:

keyType (int) - One of the key types from the integer list below. Note that customer types can be used for application specific license types:

* TBC_KEYTYPE_UNCHANGED  (-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)

expiredStatus (int) - Indicates whether the client license has expired. One of the possible values:

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

activatedStatus (int) - Indicates whether the client license has been activated. One of the possible values:

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

blacklistedStatus (int) - Indicates whether the client license key has been blacklisted. One of the possible values:

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

whitelistedStatus (int) - Indicates whether the client license key has been whitelisted. One of the possible values:

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

Return Type:

Integer constant value with the following possible values:

TBC_OK                 ( 1)
TBC_CONFIG_NOT_CREATED (-5)
TBC_INVALID_PARAMETER  (-9)
TBC_INTERNAL_ERROR     (-99)

Product Details

(TBCRESULT) setProductEdition: (NSString*)productEdition

This method allows you to set the edition of your product. An example of this would be when a single product can be licensed/run in different modes such as as “Home” and “Business”.

Parameters:

productEdition (NSString*) - The product edition that is to be set.

Return Type:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_CONFIG_NOT_CREATED ( -5)
* TBC_INTERNAL_ERROR     (-99)

(TBCRESULT) setProductLanguage: (NSString*)productLanguage

This method allows you to set the language in that the client is viewing your product. This is useful for products that have been internationalized, so you can determine how many installations are running your software in a particular language. Please note this is different than the OS language that is collected automatically by the Revulytics Usage Intelligence SDK.

Parameters:

productLanguage (NSString*) - The product language that is to be set.

Return Type:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_CONFIG_NOT_CREATED ( -5)
* TBC_INTERNAL_ERROR     (-99)

(TBCRESULT) setProductVersion: (NSString*)productVersion

This method is used to set the version number of the application being run. In most cases, this property would already have been set when initiating createConfigWithURL. So, this function normally only needs to be used if the version number changes during runtime such as after an update.

Parameters:

productVersion (NSString*) - The product version number that is to be set.

Return Type:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_CONFIG_NOT_CREATED ( -5)
* TBC_INTERNAL_ERROR     (-99)

(TBCRESULT) setProductBuildNumber: (NSString*)productBuildNumber

This method is used to set the build number of the application being run. In most cases, this property would already have been set when initiating createConfigWithURL. So, this function normally only needs to be used if the build number changes during runtime such as after an update.

Parameters:

productBuildNumber (NSString*) - The product build number that is to be set.

Return Type:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_CONFIG_NOT_CREATED ( -5)
* TBC_INTERNAL_ERROR     (-99)