Request a Demo Start Trial
Mac Analytics
Download Mac Analytics SDK
version 3.0.0

Objective-C Apps

Introduction

This document will walk you through integrating the DeskMetrics Analytics SDK into an Objective-C application. We’ll be working through the HelloDeskMetricsObjC example, so open up the Xcode project and follow along.

The SDK is compiled as a universal framework containing both 32 bit and 64 bit binaries. It is compiled on the latest XCode with a deployment target of OSX 10.7. Note that the SDK can also be used from a Swift application by including DeskMetricsAnalytics/DeskMetricsAnalytics.h in your project’s bridging header.

Add the SDK to your project

Initialize and start DeskMetrics

At the top AppDelegate.m, include the SDK:

#import <DeskMetricsAnalytics/DeskMetricsAnalytics.h>

The SDK supports two use cases: applications deployed using an installer, and applications that configure themselves on first launch. You’ll need to intialize the SDK differently depending on your use case.

For applications with installers

If your app doesn’t have an installer, skip to the next section.

At the top of AppDelegate.m, define your app key:

// Your app key - this can be found on the applications page of your DeskMetrics dashboard.
#define kAppKey @"<YOUR_APP_KEY_HERE>"

Then, add the following to the top of the applicationDidFinishLaunching: method:

// Initialize the SDK with the app key
[[DeskMetrics shared] initializeWithAppKey:kAppKey];

// Get the path to the application support directory where the installer persisted some values
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSLocalDomainMask, NO);
NSString *appSupport = [paths objectAtIndex:0];

// Load the values persisted by the installer
[[DeskMetrics shared] loadPropertiesFromPath:[appSupport stringByAppendingString:@"/HelloDeskMetricsObjC/.dm.json"]];

// Start the SDK
[[DeskMetrics shared] startSessionType:kDMASessionTypeApplication];

For applications without installers

At the top of AppDelegate.m, define your app key and some of the recommended DeskMetrics properties described in the Data Modelling Guide.

// Your app key - this can be found on the applications page of your DeskMetrics dashboard.
#define kAppKey @"<YOUR_APP_KEY_HERE>"
#define kTrackingId @"<YOUR_TRACKING_ID_HERE>"
#define kSubId @"<YOUR_SUB_ID_HERE>"
#define kChannel @"<YOUR_CHANNEL_HERE>"

Then, add the following to the top of the applicationDidFinishLaunching: method:

// Initialize the SDK with the app key
[[DeskMetrics shared] initializeWithAppKey:kAppKey];

// Get an accurate timestamp to use for install time
NSNumber *ts = nil;
[[DeskMetrics shared] getTimestampWithTimeout:5 timestampOut:&ts];

// Get cloud entity_id
NSString *entityId;
[[DeskMetrics shared] resolveEntityId:&entityId];

// Get the path to the *users's* application support directory (we will have write permissions)
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirectory, NSUserDomainMask, NO);
NSString *appSupport = [paths objectAtIndex:0];

// Load any properties persisted by previous sessions
[[DeskMetrics shared] loadPropertiesFromPath:[appSupport stringByAppendingString:@"/HelloDeskMetricsObjC/.dm.json"]];

// Establish the set of DeskMetrics recommended properties.  Do not overwrite.  This way, the values
// will be established on first launch, but not modified on subsequent launches.
[[DeskMetrics shared] setPropertyValue:kTrackingId forName:@"tracking_id" overwrite:NO];
[[DeskMetrics shared] setPropertyValue:kSubId forName:@"sub_id" overwrite:NO];
[[DeskMetrics shared] setPropertyValue:kChannel forName:@"channel" overwrite:NO];
[[DeskMetrics shared] setPropertyValue:entityId forName:@"dm.entity_id" overwrite:NO];
[[DeskMetrics shared] setPropertyValue:ts forName:@"install_time" overwrite:NO];
[[DeskMetrics shared] setPropertyValue:@"${dm.cohort:install_time}" forName:@"cohort" overwrite:NO];

// Save the properties to the *user's* application support directory
[[DeskMetrics shared] savePropertiesToPath:[appSupport stringByAppendingString:@"/HelloDeskMetricsObjC/.dm.json"]];

// Start the SDK
[[DeskMetrics shared] startSessionType:kDMASessionTypeApplication];

// Since there was no installer session, it's our responsibility to fire an install event
// the first time (and only the first time) we're launched.  The way you identify a first
// launch is left up to you.
if(isFirstApplicationLaunch) {
    // Important:  This event must be called "install", and it must contain a property called "state" with value "succeeded"
    [[DeskMetrics shared] sendEvent:@"install" withProperties:@{@"state": @"succeeded"}];
}

Stop DeskMetrics

At the bottom of the applicationWillTerminate: method in AppDelegate.m, stop the SDK:

// Stop the SDK, waiting until remaining events have been sent
[[DeskMetrics shared] stopSessionWithState:kDMAExitStateSucceeded andWait:kDMAWaitInfinite];

Enable automatic crash reporting

DeskMetrics can optionally capture and report on app crashes. To enable this functionality, you’ll need to make your app an instance of DMACrashReportingApplication (a subclass of the standard NSApplication). Here’s how:

Sending events

The integration we’ve seen so far will automatically fire launch, exit, and heart_beat events. However, you’ll probably want some custom events as well. In this example, we fire a custom event each time the user clicks a button.

Let’s take a look at the handleButtonClick: method in ViewController.m to see how this is achieved:

- (IBAction)handleButtonClick:(id)sender {
    // Just for fun, lets send some real data about the size of the computer's display:
    [[DeskMetrics shared] sendEvent:@"button_click" withProperties:@{
        @"screen_width": [NSNumber numberWithDouble:NSScreen.mainScreen.frame.size.width],
        @"screen_height": [NSNumber numberWithDouble:NSScreen.mainScreen.frame.size.height]
    }];
}

Using a custom domain

If you’ve purchased a custom domain that you would like the SDK to send your events with, then it is possible to do so using the method: setAnalyticsBaseUrl before you start the SDK like so:

[[DeskMetrics shared] setAnalyticsBaseUrl: @"https://custom.mybusiness.com"];

[[DeskMetrics shared] startSessionType:kDMASessionTypeApplication];

Thread safety

The DeskMetrics SDK is threadsafe.

However, it should be noted that: