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(TBINSTANCE *tbInstance, int doSync)

This function must be called before utilizing any of the other tracking functionality of the Revulytics Usage Intelligence SDK. This function requires the SDK configuration to be set properly before being called. At the very minimum, the functions tbSetFilePath() and tbCreateConfig() need to be called prior to this. For further detail, refer to the SDK Configuration page. NOTE: tbStart can only be called once per tbInstance. It cannot be called after a tbStop.

Parameters:

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

doSync (int) - This parameter is normally set to TB_START_SYNC (0) by default and instructs the SDK on whether to sync

with the server on start up. Another option is to allow the SDK to sync, but to instruct the server not to send any ReachOutTM message during the start up synchronization. The possible values are as follows:

* TB_START_SYNC (0) (Sync and get ReachOut\ :sup:`TM` \   message)
* TB_START_NO_REACHOUT (-1) (Sync but do not get ReachOut™ message)
* TB_START_NO_SYNC (-2) (Do not sync)
Returns:One of the return status constants below.
* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_CONFIG_NOT_CREATED (-5)
* TB_INVALID_PARAMETER (-9)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbStop(TBINSTANCE *tbInstance, int doSync)

This function should always be called at the exit point of your application. This will help the Revulytics Usage Intelligence 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 Revulytics Usage Intelligence server that your application was terminated gracefully without any unhandled exceptions. Unlike most Revulytics Usage Intelligence SDK functions, tbStop() is synchronous, meaning it returns only once it is finished. Hence, it is recommended to close/hide the application UI before calling this function. By default, this function syncs all data with the server potentially causing a delay for application exit. If the application needs to exit immediately, the application may choose to set the doSync parameter to TB_STOP_NO_SYNC, however, when doing this, you will need to make sure that syncing is done during the application runtime.

Parameters:

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

doSync (int) - This optional parameter is set to TB_STOP_SYNC (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_SYNC (0) (Sync and allow it to finish)
* TB_STOP_NO_SYNC (-1) (Do not sync)
* Any numeric value >= 1: Do sync and allow it to run for a maximum of x seconds.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbSessionStart(TBINSTANCE *tbInstance, const char *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 Revulytics Usage Intelligence 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:

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

sessionID (char*) - 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.
Returns: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)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbSessionStop(TBINSTANCE *tbInstance, const char *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 Revulytics Usage Intelligence can calculate 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:

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

sessionID (char*) - This parameter should contain a unique ID that refers to the user session that is being

Returns:One of the return status constants below.
* TB_OK (1)
* TB_FUNCTION_NO_AVAIL (-1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

Caching and Synchronizing

The Revulytics Usage Intelligence 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 Revulytics Usage Intelligence 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 Revulytics Usage Intelligence protocol. Using HTTP port 80 is crucial so that CallHome requests are not blocked by gateway firewalls, especially when running in corporate networks that 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 plain text 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 Revulytics Usage Intelligence SDK when to synchronize with the cloud server, since this happens automatically and is triggered by application interaction with the API. In a typical runtime session, the SDK will always attempt to synchronize with the server at least once whenever the application calls tbStop().

For applications that require a more customized synchronization, the API also provides an option to forcefully request the SDK to sync all cached data. This is done by calling the tbSync() function. In the case where the application runs as a background service or as a web server where tbStop() is rarely called due to the always-on nature of the application, you may opt to use tbStartAutoSync() and StopAutoSync() that launch a background process that will perform a sync on a regular schedule.

TBRESULT tbSync(TBINSTANCE *tbInstance, bool getReachout)

This function will forcefully synchronize all cached data from the client machine with the Revulytics Usage Intelligence 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 not normally required and should be avoided in most cases. Both the SDK and the server can reject a sync request from occurring 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:

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

getReachout (bool) - This optional parameter instructs the server whether to send a ReachOut™ message during
this particular sync if available.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbStartAutoSync(TBINSTANCE *tbInstance, bool getReachout)

The Revulytics Usage Intelligence SDK gives you the option to launch a separate thread that will perform an automatic sync with the server at 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:

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

getReachout (bool) - This optional parameter instructs the server whether to send a ReachOut™ message during
automatic synchronization, if available.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbStopAutoSync(TBINSTANCE *tbInstance)

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

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_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)