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 methods that expect the application to be running such as checkKey and checkMessageReturningMessage.

(TBCRESULT) startWithSync: (int)doSync

This function must be called before utilizing any of the other 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 createConfigWithURL needs to be called prior to this. For further detail, refer to the SDK Configuration page.

Parameters:

doSync (int) - Determines if the Revulytics Usage Intelligence SDK will Synchronize with the Usage Intelligence server

immediately at start up. Normally, doSync is set to TBC_START_SYNC. Possible values:

* TBC_START_SYNC        ( 0)
* TBC_START_NO_REACHOUT (-1)
* TBC_START_NO_SYNC     (-2)

Return Type:

TBCRESULT integer constant value with the following possible values:

* TBC_OK                     (  1)
* TBC_FUNCTION_NOT_AVAILABLE ( -1)
* TBC_CONFIG_NOT_CREATED     ( -5)
* TBC_INVALID_PARAMETER      ( -9)
* TBC_INTERNAL_ERROR         (-99)

(TBCRESULT) stopWithSync: (int)doSync

This method should always be called on the exit point of your application after calling startWithSync . This will help the 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 stopWithSync before your application terminates will also tell the Usage Intelligence server that your application was terminated gracefully without any unhandled exceptions. Unlike most functions in the SDK, this function is synchronous, that 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 TBC_START_NO_SYNC, however, when doing this, you will need to make sure that syncing is done during the application runtime.

Parameters:

doSync (int) - Determines if the Revulytics Usage Intelligence SDK will Synchronize with the Usage Intelligence server

when exiting the Revulytics Usage Intelligence SDK. Normally, doSync is set to TBC_START_SYNC. Possible values:

* TBC_START_SYNC        ( 0)
* TBC_START_NO_REACHOUT (-1)
* TBC_START_NO_SYNC     (-2)

Return Type:

One of the constant return values with the following possible values:

* TBC_OK                     (  1)
* TBC_FUNCTION_NOT_AVAILABLE ( -1)
* TBC_NOT_STARTED            ( -7)
* TBC_INVALID_PARAMETER      ( -9)
* TBC_APP_STOPPED            (-14)
* TBC_INTERNAL_ERROR         (-99)

(TBCRESULT) startSession: (NSString*)sessionID

This method, in conjunction with stopSession should be called only if multiSessionEnabled in the createConfigWithURL is 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 method is called is also used to calculate the session duration.

Parameters:

sessionID (NSString*) - 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:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_FUNCTION_NOT_AVAIL ( -1)
* TBC_NOT_STARTED        ( -7)
* TBC_INVALID_PARAMETER  ( -9)
* TBC_APP_STOPPED        (-14)
* TBC_INTERNAL_ERROR     (-99)

(TBCRESULT) stopSession: (NSString*)sessionID

This method, in conjunction with startSession should be called only if multiSessionEnabled in the createConfigWithURL is set to true. When a user session has been closed, this method should be called so that Usage Intelligence can calculate the duration of the user session. In case this method 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.

Parameters:

sessionID (NSString*) - 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:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_FUNCTION_NOT_AVAIL ( -1)
* TBC_NOT_STARTED        ( -7)
* TBC_INVALID_PARAMETER  ( -9)
* TBC_APP_STOPPED        (-14)
* TBC_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 Usage Intelligence server in batches, at various intervals whenever appropriate. Log data is usually sent at least once for every runtime session (during stopWithSync), however this may vary based on the type of application and usage activity.

All data is sent over HTTP (port 80) using a proprietary Usage Intelligence protocol. Using HTTP port 80 is crucial for CallHome requests not to be 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 to 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 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 stopWithSync.

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 syncWithReachout method. When the application runs as a background service or as a web server where stopWithSync is rarely called due to the always-on nature of the application, you may opt to use startAutoSyncWithReachout and stopAutoSync that launch a background process that will perform a sync on a regular schedule.

(TBCRESULT) syncWithReachout: (BOOL)getReachout

This function will forcefully synchronize all cached data from the client machine with the Usage Intelligence server. It runs asynchronously so there is no need to place this method inside of a separate thread .

As explained in the previous section, this method is normally not 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 method is called too frequently.

Parameters:

getReachout (BOOL) - This parameter instructs the server whether to send a ReachOut™ message during this particular sync if available.

Return Type:

Integer constant value with the following possible values:

* TBC_OK                 (  1)
* TBC_FUNCTION_NOT_AVAIL ( -1)
* TBC_NOT_STARTED        ( -7)
* TBC_APP_STOPPED        (-14)
* TBC_INTERNAL_ERROR     (-99)

(TBCRESULT) startAutoSyncWithReachout: (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 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 method please make sure you read the section on Caching and Synchronizing.

Once you call startAutoSyncWithReachout you may use stopAutoSync to stop the automatic synchronization process.

Parameters:

getReachout (BOOL) - This parameter instructs the server whether to send a ReachOut™ message during this particular sync if available.

Return Type:

Integer constant value with the following possible values:

* TBC_OK              (  1)
* TBC_NOT_STARTED     ( -7)
* TBC_APP_STOPPED     (-14)
* TBC_INTERNAL_ERROR  (-99)

(TBCRESULT) stopAutoSync

Use this method to stop the automatic synchronization with the server that can be started by calling on the startAutoSyncWithReachout method.

Return Type:

Integer constant value with the following possible values:

* TBC_OK              (  1)
* TBC_NOT_STARTED     ( -7)
* TBC_APP_STOPPED     (-14)
* TBC_INTERNAL_ERROR  (-99)