iPhone Dev Sessions: Adding Analytics to Your App

2009-08-09_1936

Welcome to another episode of TheAppleBlog’s iPhone Dev Sessions. We left off with a drum app tutorial called Bickboxx. For this tutorial, we’re building off of the first Bickboxx project, so go back and finish it if you haven’t already. Or if you want to cheat, grab the Bickboxx code from Github.

The Story

The Boss is happy we’ve released Bickboxx, the iPhone drum app, but now he wants to know how it’s doing. Not just sales-wise.

How many people use our app? How many times have they used the app? How much time do they spend using our app? How many users do we have in each city, state and country? How many illegal haxored versions are out there? How many people open the app once and never use it again?

Yikes. That’s a lot of questions.

Lucky for us, we don’t have to write hundreds of lines of code and roll our own analytics server to track the answer to these questions.

There are dozens of iPhone analytics APIs that will do all of the heavy lifting for us. Flurry, Mobclix, and Medialets come to mind.

There isn’t a clear leader in iPhone analytics yet but for this tutorial we’ll be using Pinch Analytics. It has comprehensive documentation and its reporting is detailed as well.

Signing Up for a Pinch Media Account

The first thing you want to do is sign up for a Pinch Media account. The first part of registration is the usual username/email/password page. The second part detailing your app takes you to this:

2009-08-09_1248

Since Bickboxx isn’t a real app that you’ll be distributing, you don’t have to fill out any of this. You can skip this part by clicking the “I’ll do it later” button.

When you are adding analytics to your real-life app, I’ve filled out some sample data for you to go by. Note that if you don’t add an app into Pinch Media, you won’t be able to view any analytics reports.

Download and Install the Pinch Media SDK

After you’ve signed up for an account, download and unzip the SDK.

Open up the Bickboxx project in Xcode. Drag the Beacon+FBConnect.h and Beacon.h files into the Classes directory in the Xcode project.

2009-08-09_1433

Make sure the “Copy items into destination group’s folder (if needed)” checkbox is checked. Click Add. We do this so our code knows how to access the Pinch Media methods in the libPMAnalytics-rXX.a library.

2009-08-09_1430

We’ll need to import the libPMAnalytics-rXX.a library next. Do this by dragging the libPMAnalytics-rXX.a file to the Frameworks folder in Xcode. Again, make sure the “Copy items into destination group’s folder (if needed)” checkbox is checked. Click Add.

2009-08-09_1433a

Install the Supporting SDKs

We need a few more frameworks to get going. We may not use these frameworks directly, but Pinch Analytics does.

Ctrl-Click the Frameworks folder and choose Add ? Existing Frameworks…

2009-08-09_1441

Select libsqlite3.dylib and click Add.

2009-08-09_1442

Do the same for the SystemConfiguration.framework.

2009-08-09_1501

Lastly, do the same for CoreLocation.framework.

2009-08-09_1502

Build the project to make sure everything is in place. It should compile. Got it? Good.

Adding the Pinch Analytics Code

Add this import statement for the Beacon.h file into BickBoxxAppDelegate.h.

[sourcecode language=’csharp’]
#import “Beacon.h”
[/sourcecode]

Adding this will allow us access to the Pinch Analytics methods from inside our BickBoxxAppDelegate.m file. Your BickboxxAppDelegate.h file should now look like this. Our change is in line 2.

[sourcecode language=’csharp’]
#import
#import “Beacon.h”

@class BickBoxxViewController;

@interface BickBoxxAppDelegate : NSObject {
UIWindow *window;
BickBoxxViewController *viewController;
}

@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet BickBoxxViewController *viewController;

@end
[/sourcecode]

Open up BickBoxxAppDelegate.m and locate the applicationDidFinishLaunching method. Add this line of code.

[sourcecode language=’csharp’]
NSString *applicationCode = @”REPLACE THIS WITH YOUR APPLICATION CODE”;
[/sourcecode]

Replace the REPLACE THIS WITH YOUR APPLICATION CODE with your Application Code from Pinch Media. You can find your application code in your Pinch Media account.

2009-08-09_1559

This is your unique ID that Pinch Media uses to identify which app is sending data to them. If you opted to not setup an app during registration, you need to do this to get an Application Code. If you don’t put in a valid Application Code, you won’t get any analytics reports and you’re wasting your time.

We’re going to use this applicationCode NSString to activate our analytics beacon. Add this line of code to the applicationDidFinishLaunching method.

[sourcecode language=’csharp’]
[Beacon initAndStartBeaconWithApplicationCode:applicationCode
useCoreLocation:YES useOnlyWiFi:NO];
[/sourcecode]

This fires up the analytics code when the app launches. Note that we’re sending in the applicationCode NSString that we inserted in the previous step. Also note the useCoreLocation parameter. You can set this to YES or NO depending on whether you want to capture location statistics.

Use this with caution. If you think you’ll offend your users by asking for their location, set this to NO.

Another parameter is useOnlyWiFi. Not everyone in the world has an unlimited data plan. They’ll be none to happy if your app is sending data over the mobile network when they don’t want it to.

Like the useCoreLocation parameter, use this parameter with caution. If set to YES, the analytics data will be sent to Pinch Media only when they’re connected to Wi-Fi. This way, the people who pay their mobile carrier per kilobyte won’t get mad. The downside is that you will miss usage statistics if they never connect to Wi-Fi.

If you’re not worried about being responsible for someone’s data overages, set this to NO.

Your code in BickBoxxAppDelegate.m for the applicationDidFinishLaunching method should now look like this.

[sourcecode language=’csharp’]
– (void)applicationDidFinishLaunching:(UIApplication *)application {

// New code below this
NSString *applicationCode = @”REPLACE THIS WITH YOUR APPLICATION CODE”;
[Beacon initAndStartBeaconWithApplicationCode:applicationCode
useCoreLocation:YES useOnlyWiFi:NO];

// Old code below this
[[UIApplication sharedApplication] setStatusBarHidden:YES animated:NO];

// Override point for customization after app launch
[window addSubview:viewController.view];
[window makeKeyAndVisible];
}
[/sourcecode]

Finally, when we exit the app or your app crashes (your apps never crash right?), we need to stop the analytics beacon.

Add this method to the BickBoxxAppDelegate.m file.

[sourcecode language=’csharp’]
– (void)applicationWillTerminate:(UIApplication *)application {
[[Beacon shared] endBeacon];
}
[/sourcecode]

Build and run your app.

You’re Done!

That’s it — you’re done! Go to lunch and have a sandwich. Nothing’s changed to the user except it’s going to ask if it’s okay that Bickboxx uses their location. You can now login to Pinch Media’s site and see all your pretty statistics and graphs. Worth noting is that the data isn’t real-time — it’s only updated twice a day.

Homework

The Boss is happy now that we can measure the performance of our app. He wants more detail on which buttons are pressed the most. You can do this by adding sub-beacons, which you can read about at the documentation site.

BickBoxx On Github and the iTunes App Store

Like last time, the code is open-sourced on Github. You can check your code against the code here if you start to stumble.

We’re here to show you how to build actual apps. You can download the app as it’s built at the iTunes App Store. More info on the open-source/open-tutorialized efforts on the BickBoxx website.

loading

Comments have been disabled for this post