Developer Zone

SDK Configuration

Before an application can start reporting usage to the Trackerbird SDK, it must first provide some basic information such as the 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 Trackerbird 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 Trackerbird Analytics portal.

Also, if you would like to store the Trackerbird data files in a particular directory, this needs to be specified before initializing the configuration.

Setting the data path

TBRESULT tbSetFilePath(const wchar_t* filePath)

This function sets the file path where the Trackerbird 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 function - including tbCreateConfig().

Parameters:
  • filePath (wchar_t*) – The location where to create and save the Trackerbird SDK working files.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_INVALID_PATH (-10)
* TB_ACCESS_DENIED (-11)

Initializing the configuration

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

TBRESULT tbCreateConfig(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 Trackerbird SDK.

Parameters:
  • url (wchar_t*) –

    Callhome URL: Every product registered with Trackerbird 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 Trackerbird 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) which must be setup as a CNAME DNS entry pointing to your unique Trackerbird URL. Please note that before you can use your own custom URL you must first inform Trackebird support (support@trackerbird.com) to register your domain with the Trackerbird 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 function 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 function is ignored, and the one inside the config file is used. This is done so that the server can instruct the Trackerbird SDK to start using a new URL in cases of URL change. Also, every Trackerbird 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 Trackerbird data files or else, the clients will keep trying to use the old URL that won’t match the new product ID.

  • productID (wchar_t*) – This is a unique 10-digit Product ID number which identifies your product with the Trackerbird 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
Return type:

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)

The following example shows how to initialize the Trackerbird configuration:

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(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, which handles user sessions automatically and assumes that 1 process (instance) means 1 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 Trackerbird 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 functions tbSessionStart() and tbSessionStop() 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 tbCreateConfig(), there are a number of functions meant to provide further data to the SDK which would 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 setups such as the proxy server settings.

Any of these functions 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

TBRESULT tbSetLicense(int keyType, BOOL keyExpired, BOOL keyActivated, BOOL keyBlacklisted, BOOL 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 -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_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:
  • keyType (int) – One of the key types from the list shown above.
  • keyExpired (BOOL) – Indicates whether the client license has expired.
  • keyActivated (BOOL) – Indicates whether the client license has been activated.
  • keyBlacklisted (BOOL) – Indicates whether the client license key has been blacklisted.
  • keyWhitelisted (BOOL) – Indicates whether the client license key has been whitelisted.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)

Product Details

TBRESULT tbSetProductEdition(const 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”.

Parameters:
  • productEdition (wchar_t*) – The product edition that is to be set.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)

TBRESULT tbSetProductLanguage(const wchar_t* productLanguage)

This function allows you to set the language in which the client is viewing your product. This is useful for products which 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 which is collected automatically by the Trackerbird SDK.

Parameters:
  • productLanguage (wchar_t*) – The product language that is to be set.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)

TBRESULT tbSetProductVersion(const 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:
  • productVersion (wchar_t*) – The product version number that is to be set.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)

TBRESULT tbSetProductBuildNumber(const 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:
  • productBuildNumber (wchar_t*) – The product build number that is to be set.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)

Privacy Settings

The Trackerbird SDK supports 3 different Privacy settings that give you control on what type of anonymous data should be collected form the end user’s machine, based on whether the user opted in or out of your Customer Experience Improvement Program. By default, this is set to TB_PRIVACYMODE_OFF. To read more about privacy and what data is collected by each privacy level, please refer to this Kbase article: http://helpdesk.trackerbird.com/knowledgebase.php?article=1

TBRESULT tbSetPrivacyMode(int privacyMode)

This function is used to set the level of privacy.

Parameters:
  • privacyMode (int) –

    One of the privacy mode constants listed below.

    * TB_PRIVACYMODE_OFF (0)
    * TB_PRIVACYMODE_LOW (1)
    * TB_PRIVACYMODE_HIGH (2)
    
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)

Environment-specific Settings

TBRESULT tbSetProxy(const wchar_t* address, const wchar_t* username, const wchar_t* password)

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

Parameters:
  • 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.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_INVALID_PARAMETER (-9)

Code Example:

tbSetProxy(L"192.168.1.250:8080", L"TestUser", L"TestPassword");
TBRESULT tbSetDefaultProxyCredentials(const wchar_t* username, const wchar_t* password)

This function is used in case the application is running behind an HTTP proxy which 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 you get the username and password from the user you can pass them on to the Trackerbird SDK through this function.

Parameters:
  • 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.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)

Code Example:

tbSetDefaultProxyCredentials(L"TestUser", L"TestPassword");