SDK Initialization and Configuration

The Revulytics Usage Intelligence V4 SDK is built to support running Revulytics Usage Intelligence in plug-in type environments. To accomplish this goal, applications must first instantiate an instance of the Revulytics Usage Intelligence SDK by calling the function tbCreateInstance that returns a handle to the Revulytics Usage Intelligence SDK instance. All subsequent Revulytics Usage Intelligence API calls required this handle as the first (or only) parameter.

Before an application can start reporting usage to the Revulytics Usage Intelligence SDK, it must first provide some basic information such as the Product ID and the CallHome URL.

You should always fill in as much accurate and specific detail as possible since this data will be used by the Revulytics 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 Revulytics Usage Intelligence Analytics portal.

If you would like to store the Revulytics Usage Intelligence data files in a particular directory, this needs to be specified before initializing the configuration.

Creating the Revulytics Usage Intelligence SDK instance

TBINSTANCE *tbCreateInstance()

This function creates the Revulytics Usage Intelligence SDK instance to be used by the application. All subsequent Revulytics Usage Intelligence SDK calls use the returned value of the instance handle. This function also allocates the internal resources for the Revulytics Usage Intelligence SDK instance including memory, threads, locks, and loading any dependent libraries. Calls to :cpp:func`tbSetFilePath` , tbCreateConfig(), and tbStart() all follow this function.

Returns:One of the following values:
* NULL - This is an unrecoverable error during the Revulytics Usage Intelligence SDK create.
* TBINSTANCE pointer - This is the handle to the newly allocated Revulytics Usage Intelligence SDK instance. This value is used in all subsequent API calls.

Destroying the Revulytics Usage Intelligence SDK instance

TBRESULT tbDestroyInstance(TBINSTANCE *tbInstance)

This function is required to be the last call to a Revulytics Usage Intelligence SDK instance. The function tbDestroyInstance() frees all Revulytics Usage Intelligence internal resources including memory, threads, locks and any dynamically loaded libraries that the Revulytics Usage Intelligence SDK loaded. Prior to calling tbDestroyInstance, the application must have called tbStop(). After calling this function, the tbInstance variable can no longer be used.

NOTE: Do not call function tbFree() with the pointer to the Revulytics Usage Intelligence SDK instance.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()
Returns:One of the return status constants below:
* TB_OK (1)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

Getting SDK Version Information

const wchar_t *tbGetSDKVersion(TBINSTANCE *tbInstance)

This function returns the SDK Version String 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.7)
  * 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

IMPORTANT: Do not call tbFree() with the pointer to the Revulytics Usage Intelligence SDK version.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()
Returns:Formatted string in form of “Revulytics Usage Intelligence SDK version [VER_NUM] for [PLATFORM]/[SHIM]” where:
* VER_NUM      is X.Y.Z  (currently 4.0.7)
* 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

Setting the data path

TBRESULT tbSetFilePath(TBINSTANCE *tbInstance, const wchar_t *filePath)

This function sets the file path where the Revulytics Usage Intelligence SDK will locate, create and save its working files. 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 function other than tbCreateInstance() including tbCreateConfig().

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

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

Returns:One of the return status constants below:
* TB_OK (1)
* TB_CONFIG_ALREADY_CREATED (-6)
* TB_INVALID_PARAMETER (-9)
* TB_INVALID_PATH (-10)
* TB_ACCESS_DENIED (-11)
* TB_INTERNAL_ERROR (-99)

Initializing the configuration

Before calling any other function other than tbCreateInstance() and tbSetFilePath(), the tbCreateConfig() function must be called in order to initialize the configuration. The function signature is as follows:

TBRESULT tbCreateConfig(TBINSTANCE *tbInstance, const wchar_t *szUrl, const wchar_t *szProductID, const wchar_t *szProductVersion, const wchar_t *szProductBuildNumber, bool bMultiSessionEnabled)

This function is used to set the bare minimum of information required to start the Revulytics Usage Intelligence SDK.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

url (wchar_t*) - CallHome URL: Every product registered 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 Revulytics 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 set up as a CNAME DNS entry pointing to your unique Revulytics Usage Intelligence URL. Please note that before you can use your own custom URL you must first inform Revulytics Revulytics Usage Intelligence support (support-rui@revulytics.com) to register your domain. 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 function for the first time, a configuration file (tbconfig.xml) is created. This contains configuration values including the URL. Once this file is created, the URL passed in this function is ignored, and the one inside the configuration 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 Revulytics 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 Revulytics 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 (wchar_t*) - This is a unique 10-digit Product ID number that identifies your product with
the Revulytics Usage Intelligence server. You can get this ID from the Developer Zone once you login to the customer area.

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

productBuildNumber (wchar_t*) - 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

Returns:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_ALREADY_CREATED (-6)
* TB_INVALID_PARAMETER (-9)
* TB_FAILED_DEPENDENCY (-12)
* TB_FILE_PATH_NOT_SET (-13)
* TB_INTERNAL_ERROR (-99)

The following example shows how to initialize the Revulytics Usage Intelligence configuration:

//Windows Example - Linux and Mac OS X use char*

TBINSTANCE* tbInstance; //...; //Creation and initialization shown in other snippets.

wchar_t* purl=L"http://INSERT-YOUR-URL";
wchar_t* pproduct_id=L"INSERT-YOUR-PROD-ID";
wchar_t* pproduct_version=L"1.2.3";
wchar_t* pproduct_build_number=L"4567";
bool multi_session_enabled=false;
tbCreateConfig(tbInstance, purl, pproduct_id, pproduct_version, pproduct_build_number, multi_session_enabled);

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 2 different sessions, 2 instances of the application would have to be loaded which would not affect each other. In such cases, you should use the single session mode that handles user sessions automatically and assumes that 1 process (instance) means 1 user session.

The multiple session mode must be used in multi-user applications, especially applications that have web interfaces. In such applications, many users may be using the same application process simultaneously. In such cases, the Revulytics Usage Intelligence SDK must be notified when user sessions start, stop and how to link events (see Feature / Event Tracking) to user sessions. When starting or stopping a user session, the functions tbSessionStart() and tbSessionStop() must be used. When tracking events on a per user basis a session ID needs to be passed as a parameter.

Providing further data

Apart from the four compulsory parameters that must be passed to tbCreateConfig(), there are a number of functions meant to provide further data to the SDK that will either help generate better reports such as by providing the product language or edition name, or else set some configuration that might be required on some set ups such as the proxy server settings.

These functions can also be called during application runtime such as changing the key type after the user enters a new license key.

License Management

TBRESULT tbSetLicense(TBINSTANCE *tbInstance, int keyType, int keyExpired, int keyActivated, int keyBlacklisted, int keyWhitelisted)

This function 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, the value TB_KEY_STATUS_UNCHANGED (-1) should be sent as its corresponding parameter.

The keyType parameter can be set to any of the constant types below. Please note that the 3 custom values may be used freely to denote your own custom license types.

* TB_KEYTYPE_UNCHANGED (-1)
* TB_KEYTYPE_EVALUATION (0)
* TB_KEYTYPE_PURCHASED (1)
* TB_KEYTYPE_FREEWARE (2)
* TB_KEYTYPE_UNKNOWN (3)
* TB_KEYTYPE_NFR (4)
* TB_KEYTYPE_CUSTOM1 (5)
* TB_KEYTYPE_CUSTOM2 (6)
* TB_KEYTYPE_CUSTOM3 (7)

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

keyType (int) - One of the key types from the list shown above.

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

* TB_KEY_STATUS_UNCHANGED (-1)
* TB_KEY_STATUS_NO (0)
* TB_KEY_STATUS_YES (1)

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

* TB_KEY_STATUS_UNCHANGED (-1)
* TB_KEY_STATUS_NO (0)
* TB_KEY_STATUS_YES (1)

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

* TB_KEY_STATUS_UNCHANGED (-1)
* TB_KEY_STATUS_NO (0)
* TB_KEY_STATUS_YES (1)

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

* TB_KEY_STATUS_UNCHANGED (-1)
* TB_KEY_STATUS_NO (0)
* TB_KEY_STATUS_YES (1)
Returns:One of the return status constants below:
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

Product Details

TBRESULT tbSetProductEdition(TBINSTANCE *tbInstance, wchar_t *productEdition)

This function 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”. If using this function it must be called after tbCreateConfig() .

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

productEdition (wchar_t*) - The product edition that is to be set. NOTE: A NULL or empty value removes any previous value

Returns:One of the return status constants below:
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbSetProductLanguage(TBINSTANCE *tbInstance, wchar_t *productLanguage)

This function allows you to set the language 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:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

productLanguage (wchar_t*) - The product language that is to be set. NOTE: A NULL or empty value removes any previous value

Returns:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbSetProductVersion(TBINSTANCE *tbInstance, wchar_t *productVersion)

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

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

productVersion (wchar_t*) - The product version number that is to be set. NOTE: A NULL or empty value removes any previous value.

Returns:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbSetProductBuildNumber(TBINSTANCE *tbInstance, wchar_t *productBuildNumber)

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

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

productBuildNumber (wchar_t*) - The product build number that is to be set. NOTE: A NULL or empty value removes any previous value.

Returns:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

Operating System-specific Settings

These functions are operating system-specific and may not work on all operating systems. Please read the function descriptions for information on what operating systems are supported.
TBRESULT tbSetProxy(TBINSTANCE *tbInstance, wchar_t *address, wchar_t *username, wchar_t *password)

This function, available only on Windows, allows you to set specific proxy settings that the Revulytics Usage Intelligence SDK will use from the end user’s machine to connect to the Revulytics Usage Intelligence server. Please note that unless a proxy server is specified using this function, the Revulytics Usage Intelligence SDK will always use the default Windows settings as defined on Internet Explorer.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

address (wchar_t*) - The address of the HTTP proxy server from which any SDK communication must
pass. You may set this value to an empty string in order to discard a previously set proxy address and use the default Windows settings as defined in IE.

username (wchar_t*) - If authentication is required pass the username here, otherwise use an empty string.

password (wchar_t*) - If a password is required for the connection it should be passed here. If a
password is not required you can set this value to an empty string. Note that the password is not saved to disk and must be passed again once the application is restarted.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

Code Example:

//Windows example
tbSetProxy(tbInstance, L"192.168.1.250:8080", L"TestUser", L"TestPassword");

TBRESULT tbSetDefaultProxyCredentials(TBINSTANCE *tbInstance, wchar_t *username, wchar_t *password)

This function, available only on Windows, is used in case the application is running behind an HTTP proxy that requires authentication (usually verified through tbConnectionCheck()). It enables you to set the proxy username and password that will be used by the SDK to authenticate with the default Windows proxy server defined on the Internet Explorer settings. If the end-user does not have a default proxy server defined then these credentials are simply ignored.

Conventionally, web-enabled applications usually ask the user to enter these credentials by displaying a dialogue or having a proxy settings section inside the application. Once the application gets the username and password from the user it can pass them on to the Revulytics Usage Intelligence SDK through this function.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

username (wchar_t*) - The username to be used to authenticate with the proxy.

password (wchar_t*) - The password to be used to authenticate with the proxy. Note that the password
is not saved to disk and must be passed again once the application is restarted.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

Code Example:

//Windows example
tbSetDefaultProxyCredentials(tbInstance, L"TestUser", L"TestPassword");