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 RUISDK.CheckLicenseKey and RUISDK.CheckForReachOut.

RUIResult RUISDK.StartSDK ()

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

RUISDK.StartSDK must be called after RUISDK.CreateConfig, and must be called only once.

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

If RUISDK.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.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and DestroySDK are possible.
* sdkPermantelyDisabled                  The RUI Server has instructed a permanent disable.
* configNotCreated                       Configuration has not been successfully created.
* sdkAlreadyStarted                      SDK has already been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.

RUIResult RUISDK.StopSDK (Int32 doSync)

Stops the RUI SDK that was started with RUISDK.StartSDK. If explicit sessions are allowed (multiSessionsEnabled = true in RUISDK.CreateConfig), then any sessions that have been started with RUISDK.StartSession that have not been stopped with RUISDK.StopSession are automatically stopped. A manual synchronization with the RUI Server, RUISDK.Sync, 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.

RUISDK.StopSDK must be called after RUISDK.StartSDK and must be called only once. After RUISDK.StopSDK is called, the various event tracking APIs are no longer available. The only API available is RUISDK.GetState. The RUI SDK cannot be re-started with a subsequent call to RUISDK.StartSDK.

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

Parameters:

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

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Function successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  :csharp:meth:`RUISDK.StopSDK` and RUISDK destructor are possible.
* sdkPermantelyDisabled                  The RUI Server has instructed a permanent disable.
* configNotCreated                       Configuration has not been successfully created.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidDoSyncValue                     The doSync manual sync flag/limit violates its allowable range.

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

// Create instance
bool registerDefaultReachOut = true;
String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";
mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);
// Other initialization.....


private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
    mySDK.StopSDK(5);
}

Recommendation: If you are using a windows forms application, the best location to place the RUISDK.StopSDK 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 RUISDK.StopSDK usually takes just a few milliseconds to execute, in case of a slow network connection, the user could experience a small lag from when they hit your application close button until the time the form actually closes. By placing RUISDK.StopSDK in the location below, this delay is completely invisible to the user since the form would have been already closed.

// Create instance
bool registerDefaultReachOut = true;
String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";
mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);
// Other initialization.....


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

RUIResult RUISDK.StartSession (String sessionID)

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

RUISDK.StartSession can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.StartSession 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.

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Function successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  :csharp:meth:`RUISDK.StopSDK` and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* functionNotAvail                       Function is not available.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDAlreadyActive          The sessionID is already currently in use.

RUIResult RUISDK.StopSession (String sessionID)

Stops an explicit session started with RUISDK.StartSession. Explicit sessions are allowed only if RUISDK.CreateConfig was called with multiSessionEnabled = true. Any explicit sessions not ended with a call to RUISDK.StopSession are automatically ended when RUISDK.StopSDK 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.

RUISDK.StopSession can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.StopSession 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 RUISDK.StartSession.

Return Type:

GenericReturn enum value with the following possible values:

* ok                                     Function successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* functionNotAvail                       Function is not available.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              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 RUISDK.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 RUISDK.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 RUISDK.Sync function.

RUIResult RUISDK.Sync (Boolean getReachOut)

Performs a manual synchronization with the RUI Server. The RUI SDK periodically performs automatic synchronizations with the RUI Server. RUISDK.Sync 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 (RUISDK.CreateConfig), the ReachOutTM will not be requested if there is no registered handler (RUISDK constructor and RUISDK.SetReachOutHandler).

RUISDK.Sync can be called between RUISDK.StartSDK and RUISDK.StopSDK and can be called zero or more times. NOTE: RUISDK.Sync will not be successful if a New Registration is in progress (i.e. RUISDK.CreateConfig and RUISDK.StartSDK). A manual synchronization with the RUI Server can be associated with RUISDK.StopSDK.

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

Parameters:

getReachout (bool) - 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.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* syncAlreadyRunning                     A sync with the RUI Server is already running.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidDoSyncValue                     The doSync manual sync flag/limit violates its allowable range.
* timeThresholdNotReached                The API call frequency threshold (set by the RUI Server) has not been reached.