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 keyCheck() and messageCheck().

appStart([doSync=True][, getReachout = True])

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

Parameters:
  • doSync (bool) – This optional parameter is set to True by default and instructs the SDK on whether to sync with the server on startup.
  • doSync – This optional parameter is set to True by default and instructs the server on whether to send a ReachOut™ message during the startup sync if available.
Return type:

One of the return status codes below.

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* CONFIG_NOT_CREATED (-5)

appStop([doSync=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 appStop() 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 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:

* STOP_SYN (0) (Sync and allow it to finish)
* 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 codes below.
* OK (1)
* APP_CONFIG_NOT_LOADED (-7)
sessionStart(sessionID)

This function, in conjunction with sessionStop() should be called only if multiSessionEnabled in createConfig() 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 None. If a None value is passed, this function would return INVALID_PARAMETER. Also, if this function is used and a sessionID is passed as a parameter, the value FUNCTION_NOT_AVAIL would be returned.

Parameters:sessionID (str) – 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 codes below.
* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* APP_CONFIG_NOT_LOADED (-7)
* INVALID_PARAMETER (-9)
sessionStop(sessionID)

This function, in conjunction with sessionStart() should be called only if multiSessionEnabled in createConfig() 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 INVALID_PARAMETER.

Parameters:sessionID (str) – 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 sessionStart().
Return type:One of the return status codes below.
* OK (1)
* APP_CONFIG_NOT_LOADED (-7)
* 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 appStop().

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 sync() function. In the case where your application runs as a background service or as a webserver where appStop() is rarely called due to the always-on nature of the application, you may opt to use startAutoSync() and stopAutoSync() which launch a background process that will perform a sync on a regular schedule.

sync([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 codes below.
* OK (1)
* APP_CONFIG_NOT_LOADED (-7)
startAutoSync([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 stopAutoSync() 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 codes below.
* OK (1)
* CONFIG_NOT_CREATED (-5)
stopAutoSync()

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

Return type:One of the return status codes below.
* OK (1)
* CONFIG_NOT_CREATED (-5)