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 that expect the application to be running such as checkLicenseKey(String, List) and checkForReachOut(MutableObject, MutableInt, MutableObject).

RUIResult startSDK()

Starts the RUI SDK. startSDK() must be paired with a call to stopSDK(int). After the RUI SDK is started, the various event tracking APIs are available to be used. If createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) did not detect a configuration file, startSDK() will perform a New Registration with the RUI Server. Until a New Registration is complete, the RUI SDK will not be able to save event data to a log file or perform synchronization with the RUI Server. A successful New Registration (or presence of a configuration file) will put the RUI SDK into a normal running state, whereby events are saved to a log file, automatic and manual synchronizations with the RUI Server are possible, and ReachOutTMs from the Server are possible. A failed New Registration will put the RUI SDK into an aborted state, not allowing further activity.

startSDK() must be called after createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), and must be called only once.

startSDK() is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

If optOut() is called before a new registration has been done for a user, the SDK will not sync any system and product information and no data is recorded for the user. The SDK will inform the server once that there is an opted out user for reporting opt-out statistics only.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     synchronous functionality successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STARTED                    SDK has already been successfully started.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.

RUIResult stopSDK(int dosync)

Stops the RUI SDK that was started with startSDK(). If explicit sessions are allowed (multiSessionsEnabled = true in createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean)), then any sessions that have been started with startSession(String) that have not been stopped with stopSession(String) are automatically stopped. A manual synchronization with the RUI Server, sync(boolean), will be performed at stop depending on the value of dosync:

* -1 : Do not perform a manual synchronization with the RUI Server as part of the stop.
*  0 : Perform a manual synchronization with the RUI Server as part of the stop; wait indefinitely for completion.
* >0 : Perform a manual synchronization with the RUI Server as part of the stop; wait only dosync seconds for completion.

stopSDK(int) must be called after startSDK() and must be called only once. After stopSDK(int) is called, the various event tracking APIs are no longer available. The only API available is getState(). The RUI SDK cannot be re-started with a subsequent call to startSDK().

stopSDK(int) is a synchronous function, including the manual synchronization with the RUI Server (if requested), returning when all functionality is completed.

Parameters:

dosync (int) - Indicates whether to do a manual synchronization as part of the stop, and if so, the maximum wait limit in seconds.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     synchronous functionality successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STARTED                    SDK has already been successfully started.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* INVALID_DO_SYNC_VALUE                  The dosync manual sync flag/limit violates its allowable range.

Code Example: This example shows stopSDK(int) being called in the closing event of a form.

// Create instance
boolean registerDefaultReachOut = false; // no default ReachOut exists for Java SDK
mySDK = new SDKImpl(registerDefaultReachOut);
// Other initialization.....


private void close()
{
    mySDK.stopSDK(5);     // wait maximum of 5 seconds
}

RUIResult startSession(String sessionID)

Starts an explicit session for event tracking in the RUI SDK. Must be paired with a call to stopSession(String). Explicit sessions are allowed only if createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) was called with multiSessionEnabled = true. When explicit sessions are enabled, a valid sessionID becomes a required parameter to the event tracking APIs.

The content of a sessionID is conditioned and validated (after conditioning) with the following rules:

* Conditioning: All leading white space is removed.
* Conditioning: All trailing white space is removed.
* Conditioning: All internal white spaces other than space characters (' ') are removed.
* Validation: Cannot be shorter than 10 UTF-8 characters.
* Validation: Cannot be longer than 64 UTF-8 characters.

The resulting conditioned and validated sessionID must be unique (i.e. not already in use). NOTE: With the above conditioning, two sessionID’s that differ only by white space or after the 64th character, will not be unique. A sessionID should not be re-used for different sessions.

startSession(String) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

startSession(String) is a synchronous function, returning when all functionality is completed.

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. sessionID must be at least 10 characters long
and no longer than 64 characters.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     synchronous functionality successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be non-empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length (10 characters).
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length (64 characater).
* INVALID_SESSION_ID_ALREADY_ACTIVE      The sessionID is already currently in use.

RUIResult stopSession(String sessionID)

Stops an explicit session started with startSession(String). Explicit sessions are allowed only if createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) was called with multiSessionEnabled = true. Any explicit sessions not ended with a call to stopSession(String) are automatically ended when stopSDK(int) is called. 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 last event was recorded.

stopSession(String) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

stopSession(String) is a synchronous function, returning when all functionality is completed.

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 startSession(String).

Return Type:

RUIResult enum value with the following possible values:

* OK                                     synchronous functionality successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be non-empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length (10 characters).
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length (64 characters).
* INVALID_SESSION_ID_NOT_ACTIVE          The sessionID is not currently in use.

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. By default, log data is sent once for every runtime session (during startSDK()) and every 20 minutes after that while the application is running.

Data may be sent via HTTP (port 80) or HTTPS (port 443) depending on application preference. When data is sent over HTTP, AES encryption is used to encrypt the data payload. When data is sent on HTTPS, normal HTTPS security measures are used. The application may also choose to start with HTTPS communication and if blocked or unsuccessful the RUI SDK will fall back to using encrypted HTTP.

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 startSDK(). For long running applications, the RUI SDK will periodically sync with the server every 20 minutes.

For applications that require a more customized synchronization, the API also provides an option to request manual synchronization of all cached data. This is done by calling the sync(boolean) function.

RUIResult sync(boolean getReachOut)

Performs a manual synchronization with the RUI Server. The RUI SDK periodically performs automatic synchronizations with the RUI Server. sync(boolean) provides the client an ability to explicitly synchronize with the RUI Server at a specific time. The manual synchronization can request a ReachOutTM with getReachOut. NOTE: Similar to reachOutOnAutosync (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean)), the ReachOutTM will not be requested if there is no registered handler (RUISDK constructor and setReachOutHandler(RUIReachOutHandler)).

sync(boolean) can be called between startSDK() and stopSDK(int) and can be called zero or more times. NOTE: sync(boolean) will not be successful if a New Registration is in progress (i.e. createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean) and startSDK()). A manual synchronization with the RUI Server can be associated with stopSDK(int).

sync(boolean) is an asynchronous function returning immediately with further functionality executed on separate thread(s).

Parameters:

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

Return Type:

RUIResult enum value with the following possible values:

* OK                                     synchronous functionality successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* SYNC_ALREADY_RUNNING                   A sync with the RUI Server is already running.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* TIME_THRESHOLD_NOT_REACHED             The API call frequency threshold (set by the RUI Server) has not been reached.