Revulytics Usage Intelligence SDK v3 for Mac OS (Objective-C)
Quick-Start Guide

In this guide you will find the information needed to integrate the SDK.

At the bottom of this page, you can find the Class Reference of the SDK.

System Requirements

The Objective-C SDK can run on Mac OS 10.6 and later.

You will have to link your application against the following frameworks:

  • Cocoa.framework
  • Foundation.framework
  • CoreFoundation.framework
  • AppKit.framework
  • Security.framework
  • SystemConfiguration.framework
  • WebKit.framework
  • libz.dylib
  • IOKit.framework

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

Importing the SDK Files

Upon downloading the Revulytics Usage Intelligence Objective-C SDK, you get 7 files - TrackerbirdSDK.h, TBApp.h, TBConfig.h, TBLicenseResult.h, TBMessageResult.h, TBVersionResult.h and libTrackerbirdSDK-MacOS.a.

These must be copied into your source directory. You must do an #import of the TrackerbirdSDK.h file, wherever you will use the SDK, or in YourProjectName-Prefix.pch file. You must also link you application against libTrackerbirdSDK-MacOS.a.

Basic Integration Steps

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

  1. Download the latest SDK and extract it to your preferred project location.
  2. Include the Trackerbird SDK into your application (see Importing the SDK Files).
  3. Initialize the SDK configuration similar to below:
     TBConfig *config = [[TBConfig alloc] initWithURL:<Callhome URL>
                                            productID:<Product ID>
                                       productVersion:<Your product's version> productBuildNumber:<Your product's build number>
                                   productBuildNumber:<Your product's build number>
                                  multiSessionEnabled:<Multiple Sessions Enabled>
                                       productEdition:<Your product's edition>
                                      productLanguage:<Your product's language>
                                      filePath:<SDK working files path>];
    

Your callhome URL and product ID can be retrieved from the Trackerbird 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 in TBConfig.

Call the method [TBApp start:completionBlock:] and provide your config object. You must call this method first, before making any other Trackerbird API calls. It is recommended that you place this call at the entry point of your application, like -applicationDidFinishLaunching: of your application delegate, so the Trackerbird SDK knows exactly at what time your application runtime session was started.

If using multi-session mode, you also need to call [TBApp sessionStartWithID:completionBlock:] 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.

Call on [TBApp stop:] when closing your application so the Trackerbird SDK knows when your application runtime session has been closed. It is recommended that you place this call at the end point of your application, like -applicationWillTerminate: of your application delegate, so the Trackerbird SDK knows exactly at what time your application runtime session was ended.

If using multi-session mode, when user sessions are closed, you should call [TBApp sessionStopWithID:completionBlock:] and send the ID of the session that is being closed as a parameter.

All of the other functions in the Trackerbird API can be called at any point in your application as long as the Trackerbird SDK has been initialized by calling [TBApp start:completionBlock:].

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

    //Initialize the Trackerbird Configuration
    NSString *url = @"http://INSERT-YOUR-URL";
    NSString *productID = @"INSERT-YOUR-PROD-ID";
    NSString *productVersion = @"1.2.3";
    NSString *productBuild = @"5AC234";
    BOOL multiSessionEnabled = NO;
    NSString *productEdition = @"Beta";
    NSString *productLanguage = @"en";
    NSString *filePath = nil;

    TBConfig *config = [[TBConfig alloc] initWithURL:url
                                           productID:productID
                                      productVersion:productVersion
                                  productBuildNumber:productBuild
                                 multiSessionEnabled:multiSessionEnabled
                                      productEdition:productEdition
                                     productLanguage:productLanguage
                                     filePath:filePath];

    //Inform Trackerbird that a new runtime session has been started.
    [TBApp start:config completionBlock:nil];

    //Your program logic...

    //Program closing - inform Trackerbird that this runtime session is closing down.
    [TBApp stop:nil];

    //Your program logic...

File Path

The filePath parameter is optional and in most cases there is no need to provide it.

This is the location where the Trackerbird SDK will create and save its working files. It is important to remember that the calling process should have read/write accessibility to the location.

The default location is as following:

  • For non-sandboxed apps: ~/Library/Application Support/
  • For sandboxed apps: ~/Library/Containers/<Bundle Identifier>/Data/Library/Application Support/

The SDK will create and keep its working files within the following direcotry structure: <filePath>/TrackerbirdSDK/<PorductID Hash>/

Note
If you wish to share the SDK functionality between multiple apps, you have to make sure that they are using the exact same filePath and productID. .

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 Trackerbird has to offer. It is recommended to go into more detail by reading the pages SDK Configuration and Basic SDK Control, respectively found in TBConfig and TBApp reference. Once you are familiar with the SDK, you may look at the advanced features.

Advanced Features

By following the Basic Integration Steps above, the Trackerbird 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 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 Trackerbird for more advanced features which include:

Feature / Event Tracking
ReachOut™ direct-to-desktop messaging service
Checking for Software Updates
Exception Tracking
License Management

You can find more information about these in TBApp reference