Developer Zone

Quick-Start Guide

System Requirements

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

Registering Your Product

Before you can use the Usage Intelligence service or integrate the Revulytics Usage Intelligence SDK with your software, you must first register an account by visiting: http://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 from the Developer Zone (within the login area). From here you can also download the latest version of the SDK.

API Overview

The Usage Intelligence V4 Objective-C SDK is a shim layer built on top of the Usage Intelligence V4 Mac OS X C++ SDK.

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

Importing the SDK Files

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

  • libtrackerbird_4.0.7.dylib - The shared library supporting C++ and Objective-C

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.

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

  2. Add a reference to libtrackerbird_4.0.7.dylib in your project.

  3. Create an instance of the TBCTrackerbirdOBJC object.

    //Initialize the Usage Intelligence Configuration
    TBCTrackerbirdOBJC* tbcInstance = [[TBCTrackerbirdOBJC alloc] init];
    
    if (!tbcInstance) {
        //Your program logic to handle failure of Revulytics Usage Intelligence SDK to initialize.
    }
    
  4. Set the directory path for the configuration.

    NSString* filePath = @"INSERT-YOUR-ABSOLUTE-OR-RELATIVE-FILEPATH";
    TBCRESULT rc = 0;
    rc = [tbcInstance setFilePath:filePath];
    if (rc != TBC_OK) {
        //Your program logic to handle error...
    }
    
  5. Initialize the SDK configuration similar to the below example. Your CallHome URL and product ID can be retrieved from the Usage Intelligence Developer Zone (inside your login area). “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.

    tb.CreateConfig("<CallHome URL starting with http://>", "<Product ID>", "<Your product's version>",
                          "<Your product's build number>", <Multiple Sessions Enabled>);
    
  6. Call the method startWithSync. You must call this method first, before making any other 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 stopWithSync 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 libtrackerbird_4.0.7.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 Usage Intelligence Configuration
 TBCTrackerbirdOBJC* tbcInstance = [[TBCTrackerbirdOBJC alloc] init];

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

 NSString* filePath = @"INSERT-YOUR-ABSOLUTE-OR-RELATIVE-FILEPATH";
 TBCRESULT rc = 0;
 rc = [tbcInstance setFilePath:filePath];
 if (rc != TBC_OK) {
     //Your program logic to handle error...
 }

 NSString* url = @"http://INSERT-YOUR-URL";
 NSString* productID = @"INSERT-YOUR-PROD-ID";
 NSString* productVersion = @"1.2.3";
 NSString* productBuildNumber = @"4567";
 BOOL      multiSessionEnabled = NO;

[tbcInstance createConfigWithURL:url productID:productID productVersion:productVersion productBuildNumber:productBuildNumber multiSessionEnabled:multiSessionEnabled];

//Inform Usage Intelligence that a new runtime session has been started.
[tbcInstance startWithSync:TBC_START_SYNC];

//Your program logic...

//Program closing - inform Usage Intelligence that this runtime session is closing down.
[tbcInstance stopWithSync:TBC_STOP_SYNC];
//Clean-up resources used by Revulytics Usage Intelligence SDK
//  [tbcInstance 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 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 Usage Intelligence for more advanced features that include: