Integrating DeskMetrics Analytics into your Objective-C application - The three minute version

This short tutorial will guide you through the basics of our API for Objective-C based applications. The examples were made using XCode 3.2.6 on OSX 10.6.7, but it should work well with XCode 4.

Don’t forget to check the Complete DeskMetrics Objective-C API reference.

In this example, we’ll show you how to make a simple Cocoa application. Are you ready?

1 - The first minute - Hello, DeskMetrics!

This first minute is basic stuff. Create XCode Project and Download the DeskMetrics Analytics library (https://github.com/downloads/deskmetrics/ObjectiveMetrics/ObjectiveMetrics%201.0.zip)

Drag and drop the ObjectiveMetrics.framework to the Framework group, just like the image below:

Select the option “Copy items into destination group’s folder”, just like show in the image below:

Warning

You need to add a Copy Files build phase which copies ObjectiveMetrics.framework to the Framework path

Next, you need to add your application ID to your Info.plist file with the key DMAppId, like this:

In the next step, we finally add code to our application. To do so, open your AppDelegate file (HelloDeskMetricsAppDelegate.m in this case) and add the following lines:

#import <ObjectiveMetrics/ObjectiveMetrics.h>

//...

//inside applicationDidFinishLauching

DMTracker *tracker = [DMTracker defaultTracker];
[tracker startApp]

Note

Unlike another DeskMetrics Analytics libraries, you don’t need to add the [tracker stopApp], because it is called automatically when your application finishes.

The final code will look like this:

//  HelloDeskMetricsAppDelegate.m
//  HelloDeskMetrics
//
//  Created by XPTO on 24/05/11.
//  Copyright 2011 __MyCompanyName__. All rights reserved.
//

#import "HelloDeskMetricsAppDelegate.h"

#import <ObjectiveMetrics/ObjectiveMetrics.h>

@implementation HelloDeskMetricsAppDelegate

@synthesize window;

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {

        // Insert code here to initialize your application
        DMTracker *tracker = [DMTracker defaultTracker];
        [tracker startApp];
}

@end

Where is my app id?

You need the app id for the Start method. This ID identifies your application on DeskMetrics Analytics. Go to http://analytics.deskmetrics.com/ and you’ll see something like this:

You can find this on DeskMetrics’ Analytics page (http://analytics.deskmetrics.com/)

2 - Second minute - Running the app and checking the results

Just run the app and close it in sequence. Yeah, it will be an empty form, but it is enough for you to see the impact on your DeskMetrics Analytics.

After you run and successfully close your application, you’ll be able to see the data on your Analytics page:

Mission complete, your first integration was done! You can see this data on your application’s Dashboard

3 - Third minute - Adding some event tracking

DeskMetrics provide a full-featured framework for you to track any user action inside your software. Want to know how much time an user takes to fill a form? No problem, just use the trackEventInCategory method with secondsSpent parameter. Do you want to know how many times a specific button was clicked? No problem, just use the trackEventInCategory method and it’s done. In our sample app, we can do something like this:

//  HelloDeskMetricsAppDelegate.m
//  HelloDeskMetrics
//
//  Created by XPTO on 24/05/11.
//  Copyright 2011 __MyCompanyName__. All rights reserved.
//

#import "HelloDeskMetricsAppDelegate.h"

#import <ObjectiveMetrics/ObjectiveMetrics.h>

@implementation HelloDeskMetricsAppDelegate

@synthesize window;

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
        // Insert code here to initialize your application
        DMTracker *tracker = [DMTracker defaultTracker];
        [tracker startApp];

        [tracker trackEventInCategory:@"Features"
                 withName:@"ManualUpdate"];

        [tracker trackEventInCategory:@"Features"
                             withName:@"URLShortener"
                                value:@"bit.ly"];

        [tracker trackEventInCategory:@"Operations"
                             withName:@"Scanning"
                         secondsSpent:37
                            completed:YES];

        [tracker trackLog:@"Error when getting new definitions"];

        [tracker trackCustomDataWithName:@"ApiKey"
                                   value:@"09123aef42"];

        // Here Realtime means that it's sent when you call this, instead of when
        // the app shuts down / enough data has been aggregated.
        [tracker trackCustomDataRealtimeWithName:@"ApiKey"
                                           value:@"09123aef42"];

        [tracker trackException:someException];
}

@end

4 - What is next?

We hope that this basic tutorial was useful to you. If you missed anything, you can download the entire project and make things works by yourself :-)

By now, you already have some knowledge on the DeskMetrics Analytics platform. If you want to know more, we recommend reading the Complete DeskMetrics Objective-C API reference.