17 Comments

Summary:

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, […]

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.

#import “Beacon.h”

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.

#import <UIKit/UIKit.h>
#import "Beacon.h"

@class BickBoxxViewController;

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

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

@end

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

NSString *applicationCode = @"REPLACE THIS WITH YOUR APPLICATION CODE";

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.

[Beacon initAndStartBeaconWithApplicationCode:applicationCode
    useCoreLocation:YES useOnlyWiFi:NO];

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.

- (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];
}

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.

- (void)applicationWillTerminate:(UIApplication *)application {
  [[Beacon shared] endBeacon];
}

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.

You’re subscribed! If you like, you can update your settings

  1. Question: I have a great idea for a iPhone app., but I don’t know anything about programming. How can I take my idea to the next level? Or who can I contact to help me?

    Blue skies!!
    Jerry

  2. Hi everyone – great blog write up and set-up walk through. I work for Flurry and our set-up is equally easy, and we believe we offer great reporting of the data collected, in addition to things no one else has, including “User Pats” that show you the order in which user complete actions inside your application. Before you set anything up, for any company, you can take a look at our demo, which shows a live application reporting data. This way you can know what you could get, before you go through the trouble integrating with any solution. Take a look. App Store Top Paid Games category from September 2008 through July 2009. http://flurry.com/demo/

  3. I haven’t done a feature comparison matrix lately, but Pinch Media offers many reports that I don’t believe are available from any other analytics provider, including jailbroken and cracked application reporting, unlimited custom action tracking, action duration measurements, demographic reporting and Facebook Connect integration, and our new audience lifecycle reporting, which shows audience retention over time.

    The PInch Media demo is available at http://demo.pinchmedia.com.

  4. But it’s basically making your app into spyware. Unless you give the user the option to opt-in to this it’s going to go and report all kinds of data back to the mothership without the user ever knowing. I’d certainly be very reluctant to install anything I knew was using Pinch Media.

    1. Pretty much the entire internet works this way. How is this any different?

  5. A few reasons. There’s a lot more identifiable info being taken here, stuff like your GPS position. This isn’t just gathering data about what browser you’re running. Secondly, it varies from country to country how much data over the phone network costs, but here in Aus it’s quite expensive and limited. Some plans even charge per connection. It’s one thing to have an app send of some data in amongst a lot of traffic, but Pinch Media gets used by some apps that have no reason to make a data connection at all.
    For the record, Pinch Media gathers:
    – iPhone’s unique ID
    – iPhone Model
    – OS Version
    – Application version
    – If the application is cracked/pirated
    – If your iPhone is jailbroken
    – time & date you start the application
    – time & date you close the application
    – your current latitude & longitude
    – your gender (if app Facebook enabled)
    – your birth month (if app Facebook enabled)
    – your birth year (if app Facebook enabled)

  6. SeaWolf is spot-on, further to his previous comments, I would like to add the following (ref : http://i-phone-home.blogspot.com/)

    – Without consent, it is spyware

    – UUID is far too unique and cannot be compared against tracking through a web browser. Pinchmedia have visibility across all Pinchmedia applications & tracking is consistent regardless of your location or connection, it is not anonymous tracking

    – GeoIP on the web is only roughly accurate, at best sometimes it can get your rough city or suburb. Pinchmedia reports your location to 8 decimal places, do they need to know what side of the bed you sleep on?

    – Pinchmedia runs at the application layer, the same layer that a web-browser runs already Pinchmedia stats involve information which has nothing to do with user metrics or usage, expect this to continue to be increasingly invasive

    – Nobody said Google analytic’s or similar services aren’t spyware =) I don’t see the comparison of Vendor A does something bad VS Vendor B does something bad being relevant.

    Apologies for the shameless cut’n’paste, I’m weary from analysing & outing pinch-media enabled applications =p

    0th3lo

  7. iPhone Dev Sessions: Adding Analytics to Your App | IPhoneMate Wednesday, August 12, 2009

    [...] Here is the original post:  iPhone Dev Sessions: Adding Analytics to Your App [...]

  8. I dont get how this is allowed!

    You even say that this will make users mad AND make YOU responsible for users’ to go over on their cell phone plans!

    There MUST be an opt-in, full disclosure, proper toggles, anonyminity, and benefits to the END USER.

    This is criminal and deceptive. Go ahead and brag about similar methods/vendors. I’m banning those products and companies.

    I could even understand something like this running on FIRST EVER running an app… But no more than the ONE time, with full disclosure up front. Some apps already do this.

    What makes you think this isn’t invasion of privacy?

    And if illegal installs is your argument, why not try innovating instead of abusing your customers?

    Apple’s drm sucks, so why not use a one-time transmission to authorize your app on first run, complete with “Register Now” form to complete?

    The current state of this whole “analytics” is absolute criminal.

    1984, anyone?

  9. iPhone Dev Sessions: Adding Analytics to Your App | IPhoneMate Wednesday, August 12, 2009

    [...] more here: iPhone Dev Sessions: Adding Analytics to Your App Share and [...]

  10. Deaddude is right on the money too..

    And ironically “The current state of this whole “analytics” is absolute criminal.” it actually is in the EU, Japan? comes to mind too.

    Well great news for users, is thanks to the information age this issue just keeps rising in profile, eventually it will come to light and be legally tested.

    In the meantime, enjoy the ever increasing angry userbase =)

    Cheerio

Comments have been disabled for this post