Developer Zone

Quick-Start Guide

System Requirements

The Revulytics Usage Intelligence Java SDK can be used with Java 8 and later versions.

Registering Your Product

Before you can use the Revulytics Usage Intelligence 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.

API Overview

When using the Revulytics Usage Intelligence API, there is one main class that you will have to integrate with SDKImpl(boolean). You need to instantiate this class in the application. All Revulytics Usage Intelligence methods use this class.

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

Importing the SDK Files

Upon downloading the Java SDK, you find one .jar file:

  • rui-sdk-<version>.jar - The jar file containing the Java SDK implementation and supporting dependencies

Where <version> is the RUI SDK release version number in form N.N.N.N where N is a number.

This JAR file can be incorporated into any Java 8 or later application.

Basic Integration Steps

The most basic Revulytics Usage Intelligence 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. Include the rui-sdk-<version>.jar file in the build environement for your Java application.

  3. Add the directives import com.revulytics.rui.sdk.* and import com.revulytics.rui.sdk.core.* to any file that will be using the Java SDK.

  4. Create an instance of the RUISDK object.

    boolean registerDefaultReachOut = false;
    RUISDK mySDK = new SDKImpl(registerDefaultReachOut); // note no default graphical ReachOut available in Java SDK. Must be false. Value true is ignored.
    
  5. 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 Administration page (within the Usage Intelligence dashboard). The protocol choice is based on the application and environment needs. Setting protocol to RUIProtocol.HTTP_PLUS_ENCRYPTION (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 (SDKImpl(boolean)) or a custom handler (setReachOutHandler(RUIReachOutHandler)).

    String myPath = "<path to directory for RUI SDK logging>";
    String myProductId = "<Product ID>";
    String myAppName = "<AppName>";
    String myURL = "<CallHome URL without protocol prefix>";
    String myKey = "<Your AES HEX Key>";
    RUIProtocol myProtocol = RUIProtocol.HTTP_PLUS_ENCRYPTION;
    boolean myMultiSessionSetting = false;
    boolean myReachOutAutosyncSetting = false;
    
    mySDK.createConfig(myPath, myProductId, myAppName, myURL, myProtocol, myKey, myMultiSessionSetting, myReachOutAutosyncSetting);
    
  6. Initialize the SDK with your product information. This is most conveniently done via the setProductData(String, String, String, String) method. This must be done BEFORE calling startSDK().

    String myProductEdition = "Professional";
    String myLanguage = "US English";
    String myVersion = "5.0.0";
    String myBuildNumber = "17393";
    
    RUIResult result = mySDK.setProductData(mySDK, myProductEdition, myLanguage, myVersion, myBuildNumber);
    
  7. Initialize the SDK with any optional custom properties by calling the method setCustomProperty(int, String)

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

    Before making any other RUI API tracking calls, you MUST call startSDK(). It is recommended that you place this call at the entry point of your application so the Revulytics Usage Intelligence SDK knows exactly at what time your application runtime session was started. If using multi-session mode, you also need to call startSession(String) 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 stopSDK(int) 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 RUI server. If necessary, add a sleep of 5 seconds before calling stopSDK(int).

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

  10. Package your application by including the rui-sdk-<version>.jar file.

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

import com.revulytics.rui.sdk.*;
import com.revulytics.rui.sdk.core.*;


class MyApplication {
   RUISDK mySDK;
   public MyApplication()
   {
     //Create instance of RUISDK
     boolean registerDefaultReachOut = false;  // Java SDK does not support Default ReachOut
     mySDK = new SDKImpl(registerDefaultReachOut);
     //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>";
     RUIProtocol myProtocol = RUIProtocolType.HTTP_PLUS_ENCRYPTION;
     boolean myMultiSessionSetting = false;
     boolean myReachOutAutosyncSetting = false;

     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(mySDK, 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 close()
   {
    //Program closing - 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 TimeUnit.SECONDS.sleep()
    // or Thread.sleep() or other mechanism to provide enough time to send captured events to RUI Server

            // values to pass stopSDK include :  -1 - No manual sync as part of stop;
            //                                    0 - perform manual sync and wait indefinitely for stop to finish
            //                                   >0 - perform manual sync and wait x seconds to completion
    mySDK.stopSDK(0);        // sync and wait indefinitely

    //Your program logic...
       }
}

Next Steps

In the above section, we covered the basic integration steps. While these steps will 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. Refer to the following sections for more information: SDK Configuration and Basic SDK Control. Once you are familiar with the SDK, you may look at the advanced features.

Advanced Features

By following the Basic Integration Steps above, the Revulytics Usage Intelligence 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 what versions and builds they are running. The 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: