Basic Integration Steps

The most basic Usage Intelligence 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.

Add a reference to ruiSDKDotNet_<version>.dll in your project.

3.

Add the directive using RUISDK_<VERSION> to the source files where you will be calling the .NET SDK. <VERSION> is the current version number in the form N_N_N where N is a number.

4.

Create an instance of the RUISDK object.

bool registerDefaultReachOut = true;

String ruiSDKDLLPath = "<path to Usage Intelligence core DLLs>";

RUISDK mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);

5.

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.

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

String myProductId = "<Product ID>";

String myAppName = "<Your App Name>";

String myURL = "<CallHome URL without protocol prefix>";

String myKey = "<Your AES HEX Key>";

Int32 myProtocol = (Int32)RUIProtocolType.httpPlusEncryption;

bool myMultiSessionSetting = false;

bool myReachOutAutoSyncSetting = true;

 

mySDK.CreateConfig(myPath, myProductId, myAppName, myURL, myProtocol, myKey, myMultiSessionSetting, myReachOutAutoSyncSetting);

Note the following:

•

The Call Home URL, the Product ID and the AES Key can be retrieved from the Administration page (within the Usage Intelligence dashboard)

•

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 (RUISDK) or a custom handler, RUISDK.SetReachOutHandler.

6.

Initialize the SDK with your product information. This is most conveniently done via the RUISDK.SetProductData call. This must be done BEFORE calling RUISDK.StartSDK.

String myProductEdition = "Professional";

String myLanguage = "US English";

String myVersion = "5.0.0";

String myBuildNumber = "17393";

 

mySDK.SetProductData(myProductEdition, myLanguage, myVersion, myBuildNumber);

7.

Initialize the SDK with any optional custom properties by calling the method RUISDK.SetCustomProperty.

8.

Call the method RUISDK.StartSDK.

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

Before making any other RUI API tracking calls, you MUST call RUISDK.StartSDK. It is recommended that you place this call at the entry point of your application so the Usage Intelligence SDK knows exactly at what time your application runtime session was started.

If using multi-session mode, you also need to call RUISDK.StartSession when a user session is started, and also provide a unique user session ID which you will then also use for closing the session or for Feature / Event Tracking.

9.

Call RUISDK.StopSDK in the closing event of your application so the Revulytics Usage Intelligence SDK knows when your application runtime session has been closed.

Note: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 Usage Intelligence Server. If necessary, add a sleep of 5 seconds before calling RUISDK.StopSDK.

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

10.

Before running your application, copy the DLL files ruiSDK_<vesion>.x64.dll and runSDK_<version>.x86.dll inside the BinDebug path (or BinRelease if you are compiling for release). These files are required by the Usage Intelligence .NET SDK and must be included with your application. If you are building specifically for x64 or x86, you may then choose to include only the corresponding DLL file.

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

RUISDK mySDK;

 

public Form1()

{

    //Create instance of RUISDK

    bool registerDefaultReachOut = true;

    String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";

    mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);

    //Set the file path and connection information

    String myPath = "<path to directory for RUI SDK logging>";

    String myProductId = "<Product ID>";

    String myAppName = "<Your App Name>";

    String myURL = "<CallHome URL without protocol prefix>";

    String myKey = "<Your AES HEX Key>";

    Int32 myProtocol = (Int32)RUIProtocolType.httpPlusEncryption;

    bool myMultiSessionSetting = false;

    bool myReachOutAutoSyncSetting = true;

 

    mySDK.CreateConfig(myPath, myProductId, myAppName, myURL, myProtocol, myKey, myMultiSessionSetting, myReachOutAutoSyncSetting);

 

    // Set your product information

 

    String myProductEdition = "Professional";

    String myLanguage = "US English";

    String myVersion = "5.0.0";

    String myBuildNumber = "17393";

 

    mySDK.SetProductData(myProductEdition, myLanguage, myVersion, myBuildNumber);

 

    // If you have any custom properties set them here

 

    //Inform Revulytics Usage Intelligence that the application has been started.

    mySDK.StartSDK();

 

    //Your program logic...

}

 

private void Form1_FormClosing(object sender, FormClosingEventArgs e)

{

    //Inform Revulytics 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 a System.Threading.Thread.Sleep()

    //or other mechanism to provide enough time to send captured events to RUI Server

 

    mySDK.StopSDK(0);

 

    //Your program logic...

}