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

Quick-Start Guide

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

System Requirements

The 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 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 C++ SDK, you get 7 files - TrackerbirdSDK.h, TBApp.h, TBConfig.h, TBLicenseResult.h, TBMessageResult.h, TBVersionResult.h and libTrackerbirdSDK-MacOS-CPP.a.

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

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 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:
1 TrackerbirdSDK::TBConfig config = TrackerbirdSDK::TBConfig(<Callhome URL>,
2  <Product ID>,
3  <Your product's version> productBuildNumber:<Your product's build number>,
4  <Your product's build number>,
5  <Multiple Sessions Enabled>,
6  <Your product's edition>,
7  <Your product's language>,
8  <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 TrackerbirdSDK::TBApp::start 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 TrackerbirdSDK::TBApp::sessionStart 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 TrackerbirdSDK::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 TrackerbirdSDK::TBApp::sessionStop 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 TrackerbirdSDK::TBApp::start.

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

1 //Initialize the Trackerbird Configuration
2 string url = string("http://INSERT-YOUR-URL");
3 string productID = string("INSERT-YOUR-PROD-ID");
4 string productVersion = string("1.2.3");
5 string productBuildNumber = string("5AC234");
6 bool multiSessionEnabled = false;
7 string productEdition = string("Beta");
8 string productLanguage = string("en");
9 string filePath = string();
10 
11 TrackerbirdSDK::TBConfig config = TrackerbirdSDK::TBConfig(url, productID, productVersion, productBuildNumber, multiSessionEnabled, productEdition, productLanguage, filePath);
12 
13 //Inform Trackerbird that a new runtime session has been started.
14 TrackerbirdSDK::TBApp::start(config, NULL);
15 
16 //Your program logic...
17 
18 //perform simple event track
19 TrackerbirdSDK::TBApp::eventTrack("simple event name", NULL);
20 
21 //Program closing - inform Trackerbird that this runtime session is closing down.
22 TrackerbirdSDK::TBApp::stop(NULL);
23 
24 //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