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 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 following example: |
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 = @"0123456789abcdeffedcba98765.5.10";
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...
}
Note the following:
| • | 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. |
| 5. | Initialize the SDK with your product information. This is most conveniently done via the setProductData call. This must be done BEFORE calling startSDK. |
NSString* myProductEdition = @"Professional";
NSString* myLanguage = @"US English";
NSString* myVersion = @"5.5.1";
NSString* myBuildVersion = @"17393";
rc = [mySDK setProductEdition:myProductEdition productLanguage:myProductLanguage productVersion:myVersion productBuildNumber:myBuildNumber];
| 6. | Initialize the SDK with any additional custom properties by calling the method setCustomProperty:. |
| 7. | Call the method startSDK. You must call this method first, before making any other Usage Intelligence API calls. |
Important: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 Usage Intelligence API tracking calls you MUST call 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 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.
| 8. | Call stopSDK: in the closing event of your application so the Usage Intelligence 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 stopSDK:.
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.
| 9. | 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 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 = @"http://INSERT-YOUR-URL";
NSString* myProductID = @"INSERT-YOUR-PROD-ID";
NSString* myPath = @"<Path name to RUI writable directory>";
int32 myProtocol = RUI_PROTOCOL_HTTP_PLUS_ENCRYPTION;
NSString* myKey = @"0123456789abcdeffedcba98765.5.10";
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...
}
NSString* myProductEdition = @"Professional";
NSString* myLanguage = @"US English";
NSString* myVersion = @"5.0.0";
NSString* myBuildVersion = @"17393";
RUIRESULTOBJC rc = [mySDK setProductEdition:myProductEdition productLanguage:myProductLanguage productVersion:myVersion productBuildNumber:myBuildNumber ];
if (rc != RUI_OK) {
//Your program logic to handle error...
}
//If you have custom properties set them here.
//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.
//Must allow at least 5 seconds between ruiStartSDK() and this call. If less than that, add a sleep().
//or [NSThread sleepFoTimeInterval] other mechanism to provide enough time to send captured events to Server
[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...