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 ruiCheckLicenseKey() and ruiCheckForReachOut().


RUIRESULT ruiStartSDK(RUIINSTANCE* ruiInstance)

Starts the RUI SDK. ruiStartSDK() must be paired with a call to ruiStopSDK(). After the RUI SDK is started, the various event tracking APIs are available to be used. If ruiCreateConfig() did not detect a configuration file, ruiStartSDK() 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 ReachOutTM from the RUI Server are possible. A failed New Registration will put the RUI SDK into an aborted state, not allowing further activity.

ruiStartSDK() must be called after ruiCreateConfig(), and must be called only once.

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

If ruiOptOut() 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.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()
Returns:One of the return status constants below.
* RUI_OK - Synchronous functionality successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_ALREADY_STARTED - SDK has already been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.

RUIRESULT ruiStopSDK(RUIINSTANCE* ruiInstance, int32_t doSync)

Stops the RUI SDK that was started with ruiStartSDK(). This function should always be called at the exit point of your application. If explicit sessions are allowed (multiSessionsEnabled = true in ruiCreateConfig()), then any sessions that have been started with ruiStartSession() that have not been stopped with ruiStopSession() are automatically stopped. A manual synchronization with the RUI Server, ruiSync(), 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.

ruiStopSDK() must be called after ruiStartSDK() and must be called only once. After ruiStopSDK() is called, the various event tracking APIs are no longer available. The only APIs available are ruiGetState() and the ruiDestroyInstance(). The RUI SDK cannot be re-started with a subsequent call to ruiStartSDK().

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

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

doSync (int32_t) - Indicates whether to do a manual synchronization as part of the stop, and if so, the wait limit.

Returns:One of the return status constants below.
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED - SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_DO_SYNC_VALUE - The doSync manual sync flag/limit violates its allowable range.

RUIRESULT ruiStartSession(RUIINSTANCE* ruiInstance, const char* sessionID)

Starts an explicit session for event tracking in the RUI SDK. Must be paired with a call to ruiStopSession(). Explicit sessions are allowed only if ruiCreateConfig() 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.

ruiStartSession() can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.

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

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

sessionID (const 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.
* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED - SDK has not been successfully started.
* RUI_FUNCTION_NOT_AVAIL - Function is not available.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY - The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT - The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG - The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_ALREADY_ACTIVE - The sessionID is already currently in use.

RUIRESULT ruiStopSession(RUIINSTANCE* ruiInstance, const char* sessionID)

Stops an explicit session started with ruiStartSession(). Explicit sessions are allowed only if ruiCreateConfig() was called with multiSessionEnabled = true. Any explicit sessions not ended with a call to ruiStopSession() are automatically ended when ruiStopSDK() 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.

ruiStopSession() can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.

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

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

sessionID (const char*) - A current valid session ID to be stopped (content conditioning and validation rules in ruiStartSession()).

returns:

One of the return status constants below.

* RUI_OK - Function successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED - SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY - The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT - The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG - The sessionID violates its allowable maximum length.
* RUI_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 ruiStartSDK()) 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 ruiStartSDK(). 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 ruiSync() function.


RUIRESULT ruiSync(RUIINSTANCE* ruiInstance, bool getReachOut)

Performs a manual synchronization with the RUI Server. In normal operation, the RUI SDK periodically performs automatic synchronizations with the RUI Server. ruiSync() provides the client an ability to explicitly synchronize with the RUI Server on demand. The manual synchronization can request a ReachOutTM with getReachOut. NOTE: Similar to the parameter reachOutOnAutoSync (on function ruiCreateConfig()), the ReachOutTM will not be requested if there is no registered handler (ruiCreateInstance() and ruiSetReachOutHandler()).

ruiSync() can be called between ruiStartSDK() and ruiStopSDK() and can be called zero or more times. NOTE: ruiSync() will not be successful if a New Registration is in progress (i.e. ruiCreateConfig() and ruiStartSDK()). A manual synchronization with the RUI Server can be associated with ruiStopSDK().

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

As explained in the previous section, this function is not normally required and should be avoided in most cases. Both the RUI SDK and the RUI server can reject a ruiSync() request from occurring even if this is requested by the developer. This is done to prevent abuse and unnecessary server load if this function is called too frequently.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

getReachout (bool) - This optional parameter instructs the server whether to send a ReachOutTM message during
this particular sync if available.
Returns:One of the return status constants below.
* RUI_OK - Synchronous functionality successful.
* RUI_INVALID_SDK_OBJECT - SDK Instance parameter is NULL or invalid.
* RUI_SDK_INTERNAL_ERROR_FATAL - Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED - A required New Registration has failed, and hence the SDK is aborted.  ruiStopSDK and ruiDestroyInstance are possible.
* RUI_SDK_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED - Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED - SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_TIME_THRESHOLD_NOT_REACHED - The API call frequency threshold (set by the RUI Server) has not been reached. Sync not allowed at this time.