Developer Zone

Quick-Start Guide

System Requirements

The Revulytics Usage Intelligence Objective C SDK for Macintosh OS X has been tested with Macintosh OS X 10.10 and Macintosh OS X 10.11 but should work with Macintosh OS X 10.7 or greater. Only a 64-bit build of the Revulytics Usage Intelligence Mac OS X shared library is provided.

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 and CallHome URL and AES Encryption Key from the Administration page (within the Usage Intelligence dashboard). From here you can also download the latest version of the SDK.

API Overview

The Revulytics Usage Intelligence Objective-C SDK is built on top of the Revulytics Usage Intelligence Mac OS X C++ SDK.

In order to download the Revulytics Usage Intelligence SDK, visit the download page at: http://devzone.revuyltics.com

Importing the SDK Files

Upon downloading the Revulytics Usage Intelligence V4 Objective-C SDK, you find one shared library in the x64 directory:

  • librui_<version>.x64.dylib - The shared library supporting C++ and Objective-C

where <version> is the latest RUI SDK version (N.N.N) where N is a numeric digit.

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. Add a reference to librui_<version>.x64.dylib in your project.

  3. Create an instance of the RUISDKOBJC object.

    RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.
    
    if (!mySDK) {
        //Your program logic to handle failure of Revulytics Usage Intelligence SDK to initialize.
    }
    
  4. Initialize the SDK configuration similar to the below example. Your CallHome URL, product ID, and AES Encryption Key can be retrieved from the Administration page (within the Usage Intelligence dashboard). “Multiple Sessions Enabled” (multiSessionsEnabled parameter) is a boolean value where you specify whether your application can have multiple user sessions per runtime session. This is normally false for desktop applications. For further details, refer to Single vs. Multiple session modes.

    NSString* myURL = @"CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";
    NSString* myProductID = @"INSERT-YOUR-PROD-ID";
    NSString* myPath = @"<Path name to RUI writable directory>";
    int32 myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;
    NSString* myKey = @"0123456789abcdeffedcba9876543210";
    NSString* myAppName = "<YOUR APP NAME>";
    BOOL      myReachOutAutoSyncSetting = YES;
    BOOL      myMultiSessionSetting = NO;
    
    RUIRESULTOBJC rc = [mySDK createConfig:myPath productID:productID appName:myAppName serverURL:myURL protocol:myProtocol aesKeyHex:myKey multiSessionEnabled:myMultiSessionSetting reachOutOnAutoSync:myReachOutAutoSyncSetting];
    
    if (rc != RUI_OK) {
            //Your program logic to handle error...
     }
    
  5. Initialize the SDK with your product information. This is most conveniently done via the setProductData call.

    NSString* myProductEdition = @"Professional";
    NSString* myLanguage = @"US English";
    NSString* myVersion = @"5.0.0";
    NSString* myBuildVersion = @"17393";
    
    rc = [mySDK setProductEdition:myProductEdition productLanguage:myProductLanguage productVersion:myVersion productBuildNumber:myBuildNumber];
    
  6. Call the method startSDK. You must call this method first, before making any other Revulytics Usage Intelligence API calls. 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 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.

  7. Call stopSDK: in the closing event of your application so the Revulytics Usage Intelligence SDK knows when your application runtime session has been closed. If using multi-session mode, when user sessions are closed, you should call stopSession and send the ID of the session that is being closed as a parameter.

  8. Before running your application, copy the shared library file librui_<version>.x64.dylib to a location in your library path. This file is required by the Revulytics Usage Intelligence SDK and must be included with your application installation.

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

 //OS X / ObjC Example.
 //Initialize the Revulytics Usage Intelligence Configuration
 RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.

 if (!mySDK) {
     //Your program logic to handle failure of Revulytics Usage Intelligence SDK to initialize.
 }

 RUIRESULTOBJC rc = 0;

 NSString* myURL = @"CALLHOME-URL-WITHOUT-PROTOCOL-PREFIX";
 NSString* myProductID = @"INSERT-YOUR-PROD-ID";
 NSString* myPath = @"<Path name to RUI writable directory>";
 int32 myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;
 NSString* myKey = @"0123456789abcdeffedcba9876543210";
 NSString* myAppName = "<YOUR APP NAME>";
 BOOL      myReachOutAutoSyncSetting = YES;
 BOOL      myMultiSessionSetting = NO;

 RUIRESULTOBJC rc = [mySDK createConfig:myPath productID:productID appName:myAppName serverURL:myURL protocol:myProtocol aesKeyHex:myKey multiSessionEnabled:myMultiSessionSetting reachOutOnAutoSync:myReachOutAutoSyncSetting];

 if (rc != RUI_OK) {
          //Your program logic to handle error...
 }

//Inform Revulytics Usage Intelligence that a new runtime session has been started.
 rc = [mySDK startSDK];

 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.
 [mySDK stopSDK:RUI_SDK_STOP_SYNC_INDEFINITE_WAIT];

 //Clean-up resources used by Revulytics Usage Intelligence SDK
 //  [mySDK release];  //Either release or use ARC.

 //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: