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 TBClass.KeyCheck and TBClass.MessageCheck.

GenericReturn TBClass.Start (bool doSync = true, bool getReachout = true)

This method must be called before utilizing any of the other functionality of the Revulytics Usage Intelligence SDK. This method requires the SDK configuration to be set properly before being called. At the very minimum, the TBClass.SetFilePath and TBClass.CreateConfig need 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 start up.
getReachOut (bool) - This optional parameter is set to true by default and instructs the server on whether to send a
ReachOut™ message during the start up sync if available.

Return Type:

GenericReturn enum value with the following possible values:

* OK (1)
* FunctionNotAvailable (-1)
* ConfigNotCreated (-5)
* InternalError (-99)

GenericReturn TBClass.Stop (bool doSync = true)

This method should always be called on 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 TBClass.Stop() before your application terminates will also tell the Revulytics 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 too long. 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 (bool) - This optional parameter is set to true by default and instructs the
SDK on whether to sync with the server on start up.

Return Type:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotLoaded (-7)
* InternalError (-99)

Code Example: This example shows TBClass.Stop being called in the closing event of a form.

// Create instance
TBClass tb = new TBClass("<path to Revulytics Usage Intelligence SDK .NET library>");
// Other initialization.....


private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
    tb.Stop();
}

Recommendation: If you are using a windows forms application, the best location to place the TBClass.Stop call would be inside of the entry point method of your application, on the line immediately following the Application.Run call that creates your main form as seen below. This will allow the Revulytics Usage Intelligence SDK to execute its final server synchronization procedure AFTER your form has been closed. Although TBClass.Stop usually takes just a few milliseconds to execute, in case of a slow network connection, the user could experience a small lag from when he hits your application close button until the time the form actually closes. By placing TBClass.Stop in the location below, this delay is completely invisible to the user since the form would have been already closed.

// Create instance
TBClass tb = new TBClass("<path to Revulytics Usage Intelligence SDK .NET library>");
// Other initialization.....


[STAThread]
static void Main()
{
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);
    Application.Run(new Form1());
    tb.Stop();
}

GenericReturn TBClass.Stop (Int32 syncTimeout)

This is another overload to the TBClass.Stop method described above. The difference is that in this overload, a timeout is accepted as a parameter. This timeout is the maximum number of seconds to allow the Revulytics Usage Intelligence SDK to sync with the server before allowing the application to close even if the sync process has not finished.

Parameters:

syncTimeout (int) - The maximum number of seconds to allow the Revulytics Usage Intelligence SDK to sync with the server

Return Type:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotLoaded (-7)
* InvalidParameter(-9)
* InternalError (-99)

GenericReturn TBClass.SessionStart (String sessionID)

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

Parameters:

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

GenericReturn enum value with the following possible values:

* OK (1)
* FunctionNotAvailable (-1)
* ConfigNotLoaded (-7)
* InvalidParameter(-9)
* InternalError (-99)

GenericReturn TBClass.SessionStop (String sessionID)

This method, in conjunction with TBClass.SessionStart should be called only if multiSessionEnabled in TBClass.CreateConfig has been set to true. When a user session has been closed, this method should be called so that Revulytics 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 (string) - 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 TBClass.SessionStart.

Return Type:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotLoaded (-7)
* InvalidParameter(-9)
* InternalError (-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 TBClass.Stop), 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 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 TBClass.Stop.

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

void TBClass.Sync (bool getReachout)

This function will forcefully synchronize all cached data from the client machine with the Revulytics Usage Intelligence server. The method has no return value and has no parameters. 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:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotLoaded (-7)
* InternalError (-99)

void TBClass.StartAutoSync (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 method please make sure you read the section on Caching and Synchronizing.

Once you call TBClass.StartAutoSync() you may use TBClass.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:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotCreated (-5)
* InternelError (-99)

void TBClass.StopAutoSync ()

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

Return Type:

GenericReturn enum value with the following possible values:

* OK (1)
* ConfigNotCreated (-5)
* InternelError (-99)