Developer Quick Start

This guide walks you through the steps to implement the Mac OS X library and start sending measurement data.

Get the Library

Visit to download the Mac OS X AppMeasurement library.

The download contains the following software components:

  • ADMS_Measurement.h: The Objective-C header file used for Mac OS X AppMeasurement.
  • admsAppLibrary.a: a fat binary containing the library builds.
  • Examples/TrackingHelper.h, Examples/TrackingHelper.m: Optional class that is designed to keep tracking code separate from your application logic.

Add the Library to your Project

  1. Launch the Xcode IDE.
  2. Copy the ADMS_AppLibrary folder from the ADMS_AppLibrary-*.DMG you downloaded to your project folder or another location on your drive.
  3. Drag and Drop the ADMS_Measurement folder on your Xcode project, and confirm the following settings:
    • Select Copy items into destination group's folder (if needed).
    • Select Create groups for any added folders.
    • Select the targets where you want to use AppMeasurement code.
  4. Click Finish.

A Quick Word on the TrackingHelper

The SDK includes an additional, optional class, called TrackingHelper. TrackingHelper provides a way to separate your measurement code from your application logic.

Consider the following example: In your application, you want to send an event that tracks each login. You could add the following code directly after your login code to send this event (don't worry about the code details, we'll get to those later):

ADMS_Measurement *measure = [ADMS_Measurement sharedInstance];
NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
[contextData setObject:@"username_value" forKey:@"username"];  
//add additional key:value pairs to this dictionary...

[measure trackEvents:@"event1" withContextData:contextData];

This direct approach is OK, but wouldn't you rather put this code somewhere else so it is out of your way while you are developing your application? The TrackingHelper is that "somewhere else".

Inside of TrackingHelper, you could place this code in a method called trackLogonEvent:

+ (void)trackLogonEvent:(NSString *)username_value{
NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
[contextData setObject:username_value forKey:@"username"];
//add additional key:value pairs to this dictionary...

[measure trackEvents:@"event1" withContextData:contextData];

Now, in your application code, you can track a logon event with a simple call to trackLogonEvent:

[TrackingHelper trackLogonEvent:@"username_value"];

The measurement call in your application code is down to a single line. Plus, if the underlying measurement logic needs to change, you'll need to update only the TrackingHelper. If another developer adds to your code, he or she can use the simplified methods you've defined without taking a crash course in the AppMeasurement library.

We think you'll prefer using the TrackingHelper for new implementations. The remaining steps in this guide walk you through the steps to set up TrackingHelper and start sending measurement data.

If you'd rather implement without TrackingHelper, you can safely remove TrackingHelper.h and TrackingHelper.m from your project.


  1. Open TrackingHelper.m and update the report suite ID and tracking server:

    These values are required, and must be correct or measurement won't work. If you are unsure about these values, ask your SiteCatalyst expert.

  2. Find the + (void)configureAppMeasurement method. This is where you enable SSL, enable offline tracking, and make other global changes to your configuration. Debug logging is turned on by default, so before you publish your app, you need to come back here and set debugLogging = NO.
  3. Open your AppDelegate.m file and add the following line to import the TrackingHelper header file:
    #import "TrackingHelper.h"
  4. Add a call to TrackingHelper configureAppMeasurement to your application:didFinishLaunchingWithOptions method:

    -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{
    [TrackingHelper configureAppMeasurement];

    That's it! You've now implemented basic app tracking in your Mac OS X app. Your Mac OS X app will now send lifecycle metrics, including launches, upgrades, crashes, and daily and monthly users.

    Where to go from here:

(Recommended) Track Lifecycle Events

By default, each time your app is launched, a single hit is sent to track installs, upgrades, engaged days, and the other Lifecycle Metrics.

We can't think of a reason you'd want to disable this, but we added an option to do it anyway. To disable lifecycle tracking, in TrackingHelper.m, find the line that contains setAutoTrackingOptions and uncomment the following line:

[measure setAutoTrackingOptions:ADMS_AutoTrackOptionsNone];

(Optional) Track Custom Events

Custom events are success metrics that are unique to your application. You might send a custom event when a user logs in, initiates an in-app purchase, or clicks a link to your Facebook page. The tracking helper class contains an example that shows how to track a custom event. You can use this method as a template to add additional event tracking methods.

In TrackingHelper.m, define a custom event track method:

+ (void)trackCustomEvents {
	NSMutableDictionary *contextData = [NSMutableDictionary dictionary];
	[contextData setObject:@"value" forKey:@"contextKey"];
	[[ADMS_Measurement sharedInstance] trackEvents:events withContextData:contextData];

After you update this function to send your events, make sure the signature appears in TrackingHelper.h:

+ (void)trackCustomEvents;

Throughout your code, you can call this method to track a custom event:

[TrackingHelper trackCustomEvents];

Use this process to add as many event tracking methods as you need. A Quick Word on the TrackingHelper contains an example method to track a login event.

(Optional) Manually Track Custom States

The tracking helper class also contains an example that shows how to track an application state. Tracking a custom state is very similar to tracking an event, the only difference is you use the trackAppState method instead of trackEvents.

[measure trackAppState:@"name" withContextData:contextData];

From a reporting standpoint, trackAppState increments page views, while trackEvents does not.