Developer Zone

Basic SDK Control

Once the required configuration is initialized (explained in the SDK Configuration page) and set according to the needs of your application, you may inform the SDK that the application has started. This will allow you to use further functions which expect the application to be running such as tbKeyCheck() and tbMessageCheck().

TBRESULT tbStart([int doSync=TB_START_SYN])

This function must be called before utilizing any of the other functionality of the Trackerbird SDK. This function requires the SDK configuration to be set properly before being called. At the very minimum, the tbCreateConfig() needs to be called prior to this. For further detail, refer to the SDK Configuration page.

Parameters:
  • doSync (int) –

    This optional parameter is set to TB_START_SYN (0) by default and instructs the SDK on whether to sync with the server on startup. Another option is to allow the SDK to sync, but to instruct the server not to send any ReachOut™ message during the startup sync. The possible values are as follows:

    * TB_START_SYN (0) (Sync and get ReachOut™ message)
    * TB_START_NO_REACHOUT (-1) (Sync but do not get ReachOut™ message)
    * TB_START_NO_SYN (-2) (Do not sync)
    
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_CONFIG_NOT_CREATED (-5)

TBRESULT tbStop([int doSync=TB_STOP_SYN])

This function should always be called on the exit point of your application. This will help the Trackerbird server keep track of when your application was closed to accurately calculate session runtime duration and provide you with reports based on application usage statistics. Calling tbStop() before your application terminates will also tell the Trackerbird server that your application was terminated gracefully without any unhandled exceptions. Unlike most functions in the SDK, this function is synchronous, which means it returns only once finished. Due to this fact, it is recommended to close/hide the application UI before calling this function. By default, during this function, the SDK syncs all data with the server, and this is what might take a bit long during. If you need your application to exit immediately, you may choose to set the doSync parameter to false, however, when doing this, you will need to make sure that syncing is done during the application runtime.

Parameters:
  • doSync (int) –

    This optional parameter is set to TB_STOP_SYN (0) by default and instructs the SDK on whether to sync with the server before returning and the maximum number of seconds to allow the SDK to sync. The possible values are as follows:

    * TB_STOP_SYN (0) (Sync and allow it to finish)
    * TB_STOP_NO_SYN (-1) (Do not sync)
    * Any numeric value >= 1: Do sync and allow it to run for a maximum of x seconds.
    
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)

TBRESULT tbSessionStart(const wchar_t* sessionID)

This function, in conjunction with tbSessionStop() should be called only if multiSessionEnabled in tbCreateConfig() has been set to true. When a new user session is started, the Trackerbird SDK needs to be informed so that events that happen within this session can be logged. The time when this function is called is also used to calculate the session duration. The sessionID parameter cannot be NULL. If a NULL value is passed, this function would return TB_INVALID_PARAMETER. Also, if this function is used and a sessionID is passed as a parameter, the value TB_FUNCTION_NOT_AVAIL would be returned.

Parameters:
  • sessionID (wchar_t*) – This parameter should contain a unique ID that refers to the user session that is being started. This same ID should later be used for event tracking.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)

TBRESULT tbSessionStop(const wchar_t* sessionID)

This function, in conjunction with tbSessionStart() should be called only if multiSessionEnabled in tbCreateConfig() has been set to true. When a user session has been closed, this function should be called so that Trackerbird can calulcate the duration of the user session. In case this function is never called, eventually this session will be considered as “timed-out”, and the time of the last recorded event will be assumed to be the time when the session was closed. If the sessionID value that is passed is not matched to a known sessionID that has been started earlier, this function returns TB_INVALID_PARAMETER.

Parameters:
  • sessionID (wchar_t*) – This parameter should contain a unique ID that refers to the user session that is being stopped. This must be the same same ID that was used earlier when calling tbSessionStart().
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)

Caching and Synchronizing

The Trackerbird SDK was designed to minimize network traffic and load on the end user’s machine. In order to do this, all the collected architecture info and runtime tracking data is cached locally and then compressed and sent to the Trackerbird server in batches, at various intervals whenever appropriate. Log data is usually sent at least once for every runtime session (during tbStop()), however this may vary based on the type of application and usage activity.

All data is sent over HTTP (port 80) using a proprietary Trackerbird protocol. Using HTTP port 80 is crucial for callhome requests not to be blocked by gateway firewalls, especially when running in corporate networks which are sometimes configured to block HTTPS and other unknown traffic. Only a minor portion of traffic (containing license keys) is encrypted by the protocol. Log data is stored in plaintext and transferred unencrypted. This was designed purposely for the sake of transparency so that security-conscious users can freely sniff whatever is being sent out of their machine so they can confirm that no user-identifiable information is being collected or transmitted.

Forced Synchronization

Under normal conditions, you do not need to instruct the Trackerbird SDK when to synchronize with the cloud server, since this happens automatically at various intervals, and is triggered by your interaction with the API. In a typical runtime session, the SDK will always attempt to synchronize with the server at least once whenever your application calls tbStop().

In order to cater for custom requirements, the API also provides you with the option to forcefully request the SDK to sync all cached data. This is done by calling the tbSync() function. In the case where your application runs as a background service or as a webserver where tbStop() is rarely called due to the always-on nature of the application, you may opt to use tbStartAutoSync() and StopAutoSync() which launch a background process that will perform a sync on a regular schedule.

TBRESULT tbSync([BOOL getReachout=TRUE])

This function will forcefully synchronize all cached data from the client machine with the Trackerbird server. The synchronization process runs asynchronously so there is no need to place this function inside a separate thread.

As explained in the previous section, this function is normally not required and should be avoided in most cases. Both the SDK and the server can reject a sync request from occuring even if this is forced by the developer. This is done to prevent abuse and unnecessary server load if this function is called too frequently.

Parameters:
  • getReachout (BOOL) – This optional parameter instructs the server whether to send a ReachOut™ message during this particular sync if available.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)

TBRESULT tbStartAutoSync([BOOL getReachout=TRUE])

The Trackerbird SDK gives you the option to launch a separate thread that will perform an automatic sync with the server at a regular intervals. This is usually only required for applications running as background services or web services whose running cycle (session runtime duration) spans over 6 hours. Before using this function please make sure you read the section on Caching and Synchronizing.

Once you call this function, you may use tbStopAutoSync() to stop the automatic synchronization process.

Parameters:
  • getReachout (BOOL) – This optional parameter instructs the server whether to send a ReachOut™ message during the following automatic syncs.
Return type:

One of the return status constants below.

* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)

TBRESULT tbStopAutoSync()

Use this function to stop the automatic synchronization with the server which can be started by calling on the tbStartAutoSync() function.

Return type:One of the return status constants below.
* TB_OK (1)
* TB_CONFIG_NOT_CREATED (-5)