Basic Integration Steps

The most basic Usage Intelligence (RUI) integration can be accomplished by following the steps below. It is however recommended to read the more advanced documentation as Usage Intelligence can do much more than the basic functionality that can be achieved by following these steps.

To perform basic integration:

1.

Download the latest SDK from the following page in the Revenera Community, and extract it to your preferred project location:

Usage Intelligence SDK Download Links and API Documentation 

2.

Create a Usage Intelligence SDK object. The object returned from the call will be used in all subsequent Usage Intelligence API calls.

bool registerAutoReachOut = true;

RUIINSTANCE* mySDK = ruiCreateInstance(registerAutoReachOut);

3.

Create the configuration point to the directory where the Usage Intelligence SDK will create and update files. The application using Usage Intelligence will need read and write access rights to this directory.

RUIRESULT rc = RUI_OK;

char* myPath = "<path to directory for SDK logging>";

char* myProductId = "<Product ID>";

char* myAppName = "<Your App Name>";

char* myURL = "<CallHome URL>";

char* myKey = "<Your AES HEX Key>";

int32_t myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;

bool myMultiSessionSetting = false;

bool myReachOutAutoSyncSetting = true;

 

rc = ruiCreateConfig(mySDK, myPath, myProductId, myAppName, myURL, myProtocol, myKey, myMultiSessionSetting, myReachOutAutoSyncSetting);

if (rc != RUI_OK) {

//Your program logic to handle error...

}

Note the following:

•

The Call Home URL, the Product ID and the AES Key can be retrieved from the RUI Dashboard via your registered account.

•

The protocol choice is based on the application and environment needs. Normally, HTTP protocol (port 80) will give applications the greatest chance of success in most environments.

•

The Multiple Session flag is a boolean value where you specify whether your application can have multiple user sessions per runtime session. This is normally false.

Note:For further details, refer to Single vs. Multiple Session Modes.

•

The ReachOut Auto Sync flag indicates whether or not a ReachOut should be requested as part of each SDK Automatic Sync. A ReachOut request will be made only if a ReachOut handler has been set by registering the default graphical handler, ruiDestroyInstance(), or a custom handler, ruiSetReachOutHandler().

4.

Initialize the SDK with your product information. This is most conveniently done via the ruiSetProductData() call. This must be done BEFORE calling ruiStartSDK().

char* myProductEdition = "Professional";

char* myLanguage = "US English";

char* myVersion = "5.0.0";

char* myBuildNumber = "17393";

 

rc = ruiSetProductData(mySDK, myProductEdition, myLanguage, myVersion, myBuildNumber);

5.

Initialize the SDK with any optional custom properties by calling the function ruiSetCustomProperty().

6.

Call the function ruiStartSDK().

Note:You must set all known values for product data and custom properties BEFORE calling ruiStartSDK() otherwise you risk having null values for fields not specified. Once these calls are completed, you can safely call ruiStartSDK().

Before making any other Usage Intelligence API tracking calls, you MUST call ruiStartSDK(). It is recommended that you place this call at the entry point of your application so the SDK knows exactly at what time your application runtime session was started. If using multi-session mode, you also need to call ruiStartSession() when a user session is started, and also provide a unique user session ID that you will then also use for closing the session or for Feature / Event Tracking.

7.

Call ruiStopSDK() when closing your application so the SDK knows when your application runtime session has been closed.

Important:You must allow at least 5 seconds of application runtime to allow event data to be written to the log file and synchronized with the Server. If necessary, add a sleep of 5 seconds before calling ruiStopSDK().

If using multi-session mode, when user sessions are closed, you should call ruiStopSession() and send the ID of the session that is being closed as a parameter.

8.

All of the other functions in the Usage Intelligence API can be called at any point in your application as long as the Usage Intelligence SDK has been initialized by calling ruiStartSDK().

9.

Call ruiDestroyInstance() to shut down the SDK and free the memory.

The following is an example of the basic integration outlined below. This example uses single-session mode.

//Initialize the Usage Intelligence Configuration

char* myURL="CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";

char* myProductId="INSERT-YOUR-PROD-ID";

char* myPath="INSERT-YOUR-ABSOLUTE-OR-RELATIVE-FILEPATH";

char* myVersion="1.2.3";

char* myBuildVersion="4567";

bool myMultiSessionSetting = false;

bool myReachOutAutoSyncSetting = true;

char* myKey = "<Your AES HEX Key>";

 

bool registerAutoReachOut = true;

RUIINSTANCE* mySDK = ruiCreateInstance(registerAutoReachOut);

 

RUIRESULT rc = RUI_OK;

 

rc = ruiCreateConfig(mySDK, myPath, myProductId, myAppName, myURL, RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION, myKey, myMultiSessionSetting, myReachOutAutoSyncSetting);

 

if (rc != RUI_OK) {

    //Your program logic to handle error...

}

 

// Set your product data information

 

char* myProductEdition = "Professional";

char* myLanguage = "US English";

char* myVersion = "5.0.0";

char* myBuildNumber = "17393";

 

rc = ruiSetProductData(mySDK, myProductEdition, myLanguage, myVersion, myBuildNumber);

 

if (rc != RUI_OK) {

    //Your program logic to handle error...

}

 

// If you have any custom properties set them here.

 

//Inform Usage Intelligence that a new runtime session has been started.

rc = ruiStartSDK(mySDK);

 

if (rc != RUI_OK) {

    // Your program logic to handle error....

}

 

//Your program logic...

 

//Program closing - inform Usage Intelligence that this runtime session is closing down and sync.

//Must allow at least 5 seconds between ruiStartSDK() and this call. If less than that, add Sleep() call

//to provide enough time to send captured events to Server

 

rc = ruiStopSDK(mySDK, RUI_SDK_STOP_SYNC_INDEFINITE_WAIT);

 

if (rc != RUI_OK) {

    // Your program logic to handle error....

}

 

rc = ruiDestroyInstance(mySDK);

 

    if (rc != RUI_OK) {

    // Your program logic to handle error....

}

//Your program logic...