Developer Zone

Quick-Start Guide

System Requirements

The Revulytics Usage Intelligence C/C++ SDK for Linux has been tested with RedHat 5, RedHat 6, CentOS 6.7, Debian 8.4, Debian 8.5, and Ubuntu 14.04. Both 32-bit and 64-bit builds of the Revulytics Usage Intelligence shared library are provided. The Revulytics Usage Intelligence shared library loads in any dependent libraries automatically.

Registering Your Product

Before you can use the Revulytics Usage Intelligence Software Analytics service or integrate the Revulytics Usage Intelligence SDK with your software, you must first register an account by visiting: https://www.revulytics.com/register . Once you register a username and create a new product account for tracking your application, you can get your Product ID, CallHome URL, and AES Key from the Administration page (within the Usage Intelligence dashboard). From here you can also download the latest version of the SDK.

Importing the SDK Files

Upon downloading the Revulytics Usage Intelligence C/C++ SDK, you find two header files - ruiSDKC.h and ruiSDKDefines.h plus two shared libraries librui_<version>.x64.so and librui_<version>.x86.so . The <version> element will reflect the current shipping version of the libraries.

The .h files and the shared library of choice (x64 for 64-bit or x86 for 32-bit) should be copied into your source directory. You must also do an #include to include the header files. The shared library (x86 or x64) must be copied to your binary path, depending on the architecture that you are targeting.

NOTE: If you plan to integrate the Revulytics Usage Intelligence SDK into a plug-in framework and expect to have plug-ins that are also using Revulytics Usage Intelligence there are special considerations on how this integration is to be done. Please contact Revulytics Usage Intelligence support (support-rui@revulytics.com) for more information.

In order to download the Revulytics Usage Intelligence SDK, please go to the download page at http://devzone.revulytics.com .

Basic Integration Steps

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

  1. Download the latest SDK (http://devzone.revulytics.com) and extract it to your preferred project location.

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

    bool registerAutoReachOut = false;
    
    RUIINSTANCE* mySDK = ruiCreateInstance(registerAutoReachOut);
    
  3. Create the configuration point to the directory where the Revulytics Usage Intelligence SDK will create and update files. The application using Revulytics Usage Intelligence will need read and write access rights to this directory. 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. 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. For further details, refer to Single vs. Multiple session modes. The ReachOut Auto Sync flag indicates whether or not a ReachOutTM should be requested as part of each RUI SDK Automatic Sync. A ReachOutTM request will be made only if a ReachOutTM handler has been set by registering the default graphical handler (ruiCreateInstance()) or a custom handler (ruiSetReachOutHandler()).

    RUIRESULT rc = RUI_OK;
    char* myPath = "<path to directory for RUI 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...
    }
    
  4. Initialize the SDK with your product information. This is most conveniently done via the ruiSetProductData() call.

    char* myProductEdition = "Professional";
    char* myLanguage = "US English";
    char* myVersion = "5.0.0";
    char* myBuildNumber = "17393";
    
    rc = ruiSetProductData(mySDK, myProductEdition, myLanguage, myVersion, myBuildNumber);
    
  5. Call the function ruiStartSDK(). You must call this function first, before making any other RUI API tracking calls. It is recommended that you place this call at the entry point of your application so the RUI 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 which you will then also use for closing the session or for Feature / Event Tracking.

  6. Call ruiStopSDK() when closing your application so the RUI SDK knows when your application runtime session has been closed. 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.

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

  8. 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 Revulytics 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 = false;
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...
}

//Inform Revulytics 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 Revulytics Usage Intelligence that this runtime session is closing down and sync.

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

Text encoding

In all cases where a text value is used, char* is the data type that is used. Also, if non-ASCII values are returned, they are encoded by the SDK in UTF-8. If a non-ASCII text value needs to be passed as a parameter, it should be encoded in UTF-8 by the user application.

Next Steps

In the above section, we covered the basic integration steps. While these steps would work for most software products, it is recommended to do some further reading in order to get the most of what Revulytics Usage Intelligence has to offer. It is recommended to go into more detail by reading the pages SDK Initialization and Configuration and Basic SDK Control. Once you are familiar with the RUI SDK, you may look at the advanced features.

Advanced Features

By following the Basic Integration Steps above, the RUI SDK will be able to collect information about how often users run your product, how long they are engaged with your software as well as which versions and builds they are running. The RUI SDK also collects information on what platforms and architectures your software is being run (i.e. OS versions, language, screen resolution, etc.). Once you have implemented the basic features, you may choose to use Revulytics Usage Intelligence for more advanced features that include: