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:

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.

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.

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.

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…

Select libsqlite3.dylib and click Add.

Do the same for the SystemConfiguration.framework.

Lastly, do the same for CoreLocation.framework.

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.

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.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q4: All Eyes Were on Android, 4G and the Rising Tablet Tide
• Report: A Mobile Video Market Overview
• In Q3, the Tablet and 4G Were the Big Stories

You’ve seen all the different drum apps, right? Well, they’re really easy to make. In this iPhone Dev Sessions article, I want to teach you how to make Bickboxx, an actual app that’s in the iTunes App Store.

Grab Bickboxx (FREE) from the iTunes App Store if you want to see this puppy in action so you have an idea of what you’re building. Also, I’ve opened up the source code for free at Github. Feel free to download it, report issues, or even fork your own version and change it as you see fit.

More info on the open-source community project at Bickbot’s Bickboxx page.

Note: You don’t need to download the code from Github to get through the tutorial.

An On-going Project

I plan on adding more tutorials with enhancements to this project. Here are a couple of things that could be featured in future iPhone Dev Sessions.

• Key logger
• Adding analytics tracking
• Adding application preferences
• Track recorder and editor
• Vibration feedback
• Add your own custom sounds
• Access your iPod library as a background track

Leave a comment with other enhancements you want to learn.

OK, let’s get to creating Bickboxx!

Get Started

Create a new View-based project in XCode. Name the project “Bickboxx”.

Download this zip file and unzip it. These are all the sounds, images, and icons you need for Bickboxx. Drag all these files to the Resources. Hat tip to John Ellenich for the graphics/sounds.

You need to copy the item to the project’s directory, so put a check mark next to “Copy items into destination group’s folder (if needed).” Your settings should look similar to this. Click Add.

Adding the background image in Interface Builder

Double-click BickboxxViewController.xib to open it in Interface Builder. Drag an Image View (UIImageView) from the Library to the View window. This will act as a placement holder for our background image.

Bring up the Attributes Inspector. Set the Image to Background.png.

Creating the Button in Interface Builder

Drag a Round Rect Button (UIButton) to the View.

Bring up the Attributes Inspector. We don’t want the button to look like an ugly white rectangle. Set the Type to Custom.

Further down the Attributes Inspector, set the button’s state to Normal (or Default State Configuration depending on your version of Xcode). This is what the button looks like when it’s not doing anything.

Set the button’s Image to B Inactive.png. You need to resize the button in the View to make sure the “B” button is fully shown.

Now, change the button’s state to Highlighted (or Highlighted State Configuration depending on your version of Xcode). This is what the button looks like when it’s pressed down.

Set the button’s Image to B Active.png.

Drag another Round Rect Button (UIButton) to the View and repeat this section for the letters “E”, “A”, and “T”. Your View should now look like this:

Close Interface Builder for now.

Build and Go to make sure everything is still working. Touch the buttons, and they should light up.

Adding the Sounds Code

We have an interface that doesn’t do anything. Let’s fix that. The audio framework we need isn’t added by default. We have to add the AudioToolbox framework.

Control+Click the Frameworks folder on the left. Go to Add → Existing Frameworks…

Select the AudioToolbox.framework from /System/Library/Frameworks.

Click OK and add it to the project.

Open BickboxxViewController.h and add this code to it.

#import <UIKit/UIKit.h>
#import <AudioToolbox/AudioServices.h>

@interface BickboxxViewController : UIViewController {
    CFURLRef        bNoteFileURLRef;
    SystemSoundID    bNoteFileObject;
    CFURLRef        eNoteFileURLRef;
    SystemSoundID    eNoteFileObject;
    CFURLRef        aNoteFileURLRef;
    SystemSoundID    aNoteFileObject;
    CFURLRef        tNoteFileURLRef;
    SystemSoundID    tNoteFileObject;
}

@property (readwrite)    CFURLRef        bNoteFileURLRef;
@property (readonly)    SystemSoundID    bNoteFileObject;
@property (readwrite)    CFURLRef        eNoteFileURLRef;
@property (readonly)    SystemSoundID    eNoteFileObject;
@property (readwrite)    CFURLRef        aNoteFileURLRef;
@property (readonly)    SystemSoundID    aNoteFileObject;
@property (readwrite)    CFURLRef        tNoteFileURLRef;
@property (readonly)    SystemSoundID    tNoteFileObject;

@end

At the top, we’re referencing AudioServices.h from the AudioToolbox framework we imported earlier.

Below that is the declaration of properties for four sounds for the “B”, “E”, “A” and “T” buttons.

bNoteFileURLRef is the file location reference for the bNoteFileObject. This is the sound the “B” button will make.

These are the properties for the “E”, “A” and “T” sounds as well.

The BickboxxViewController.m File

Open BickboxxViewController.m. We need to synthesize the getters/setters for our properties.

You can do this by adding this after @implementation BickBoxxViewController:

@synthesize bNoteFileURLRef, bNoteFileObject, eNoteFileURLRef,
eNoteFileObject, aNoteFileURLRef, aNoteFileObject,
tNoteFileURLRef, tNoteFileObject;

Changing the viewDidLoad Method

Locate the viewDidLoad method. It will be commented out. You want to uncomment it to activate it.

The viewDidLoad method gets called after all the UI components are created. This is a good place for any startup code you need your app to perform. In this case, we’ll need to set our properties to the correct sounds.

The first thing we need to do in viewDidLoad is get the main bundle for the app. The main bundle allows you to use a folder hierarchy to organize and locate many types of application resources including images, sounds, localized strings, and executable code.

After [super viewDidLoad];, add this code to get the main bundle for the app.

// Get the main bundle for the app
CFBundleRef mainBundle;
mainBundle = CFBundleGetMainBundle ();

To build the sound for the “B” button, we need to get the path of the sound file we want to play. The name of the sound file is B.aifc. This is the code to get the URL to the found file to play. Put this code after the code where you get the main bundle.

// Get the URL to the sound file to play
bNoteFileURLRef  =    CFBundleCopyResourceURL (
                                             mainBundle,
                                             CFSTR ("B"),
                                             CFSTR ("aifc"),
                                             NULL
                                             );

Note that valid system sound packages are .wav, .aif and .caf files.

Now that we have bNoteFileURLRef set we can associate the sound file with the system sound object bNoteFileObject. The AudioServicesPlaySystemSound function lets you very simply play short sound files.

Add this code after the code that gets the sound file URL.

// Create a system sound object representing the sound file
AudioServicesCreateSystemSoundID (bNoteFileURLRef, &bNoteFileObject);

We finished loading up the sound for the “B” button. We’ll need to load up the sounds for the “E”, “A” and “T” buttons.

Try to code this part yourself. If you get stuck, the viewDidLoad method should look like this when you’re done.

// Implement viewDidLoad to do additional setup after loading the view, typically from a nib.
- (void)viewDidLoad {
    [super viewDidLoad];

    // Get the main bundle for the app
    CFBundleRef mainBundle;
    mainBundle = CFBundleGetMainBundle ();

    // Get the URL to the sound file to play
    bNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("B"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (bNoteFileURLRef, &bNoteFileObject);

    // Get the URL to the sound file to play
    eNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("E"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (eNoteFileURLRef, &eNoteFileObject);

    // Get the URL to the sound file to play
    aNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("A"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );
    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (aNoteFileURLRef, &aNoteFileObject);

    // Get the URL to the sound file to play
    tNoteFileURLRef  =    CFBundleCopyResourceURL (
                                                 mainBundle,
                                                 CFSTR ("T"),
                                                 CFSTR ("aifc"),
                                                 NULL
                                                 );

    // Create a system sound object representing the sound file
    AudioServicesCreateSystemSoundID (tNoteFileURLRef, &tNoteFileObject);
}

Creating Our IBActions

Our BEAT buttons need to be associated with IBActions to make them do something. First, let’s declare the methods. Open BickboxxViewController.h and add this code before the @end line.

- (IBAction)bSound:(id)sender;
- (IBAction)eSound:(id)sender;
- (IBAction)aSound:(id)sender;
- (IBAction)tSound:(id)sender;

Your BickboxxViewController.h should now look like:

#import <UIKit/UIKit.h>
#import <AudioToolbox/AudioServices.h>

@interface BickBoxxViewController : UIViewController {
    CFURLRef        bNoteFileURLRef;
    SystemSoundID    bNoteFileObject;
    CFURLRef        eNoteFileURLRef;
    SystemSoundID    eNoteFileObject;
    CFURLRef        aNoteFileURLRef;
    SystemSoundID    aNoteFileObject;
    CFURLRef        tNoteFileURLRef;
    SystemSoundID    tNoteFileObject;
}

@property (readwrite)    CFURLRef        bNoteFileURLRef;
@property (readonly)    SystemSoundID    bNoteFileObject;
@property (readwrite)    CFURLRef        eNoteFileURLRef;
@property (readonly)    SystemSoundID    eNoteFileObject;
@property (readwrite)    CFURLRef        aNoteFileURLRef;
@property (readonly)    SystemSoundID    aNoteFileObject;
@property (readwrite)    CFURLRef        tNoteFileURLRef;
@property (readonly)    SystemSoundID    tNoteFileObject;

// The new code you added
- (IBAction)bSound:(id)sender;
- (IBAction)eSound:(id)sender;
- (IBAction)aSound:(id)sender;
- (IBAction)tSound:(id)sender;

@end

Close the file and open BickboxxViewController.m. Add the implementation to make the IBAction methods make the appropriate system sounds by invoking the AudioServicesPlaySystemSound method.

To play the “B” sound, the implemented method should make a call to AudioServicesPlaySystemSound and use the bNoteFileObject we created above. Add this after the property synthesis code:

- (IBAction)bSound:(id)sender {
AudioServicesPlaySystemSound (self.bNoteFileObject);
}

Add similar implementations for the “E”, “A” and “T” sounds as well.

For reference, the top of BickboxxViewController.m should look like:

#import "BickBoxxViewController.h" 

@implementation BickBoxxViewController

@synthesize bNoteFileURLRef, bNoteFileObject, eNoteFileURLRef,
eNoteFileObject, aNoteFileURLRef, aNoteFileObject,
tNoteFileURLRef, tNoteFileObject;

- (IBAction)bSound:(id)sender {
    AudioServicesPlaySystemSound (self.bNoteFileObject);
}

- (IBAction)eSound:(id)sender {
    AudioServicesPlaySystemSound (self.eNoteFileObject);
}

- (IBAction)aSound:(id)sender {
    AudioServicesPlaySystemSound (self.aNoteFileObject);
}

- (IBAction)tSound:(id)sender {
    AudioServicesPlaySystemSound (self.tNoteFileObject);
}

For the last piece of code, we need to clean up our mess so we don’t have memory leaks. At the bottom of BickboxxViewController.m, add these lines to your dealloc method:

- (void)dealloc {
    [super dealloc];
    AudioServicesDisposeSystemSoundID (self.bNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.eNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.aNoteFileObject);
    AudioServicesDisposeSystemSoundID (self.tNoteFileObject);
    CFRelease (bNoteFileURLRef);
    CFRelease (eNoteFileURLRef);
    CFRelease (aNoteFileURLRef);
    CFRelease (tNoteFileURLRef);
}

We’re done coding. Build and Go the project to make sure nothing is on fire. Your buttons won’t make any sounds yet. We’ll need to link our code to our interface.

Linking the buttons to the code in Interface Builder

Now that our code is done, we can link our buttons to our code. We’ll start with the “B” button link it with the bsound method. To do this, open up BickboxxViewController.xib.

Control+Click on the File’s Owner object so we can link our “B” button to our bsound.

Drag from the bSound in File’s Owner to the “B” button in the View.

An overlay should pop up. Choose Touch Down. The normal default is to execute the action when the finger is lifted from the button. We don’t want that. Soundboards don’t work that way. This will call the bSound IBAction method when the button is pressed down.

Do this linking with the rest of the buttons. When you’re done, Control+Clicking File’s owner should look like this.

Here’s a video of me using Bickboxx to practice for my opening act for Paul Oakenfold.

You’re done!

That’s it — you’re done! Compile and run this and you’ll be DJ-ing parties with Moby in no time.

Again, you can download the source from social coding site Github. Feel free to file issues here if the code needs fixing or enhancing.

Homework

Are you ready to apply your newfound knowledge? Solidify it with this extra credit assignment.

Your homework: Add a new button and a new sound to the project.

If there are any typos, problems, suggestions, or questions, let me know here in the comments.

Related research and analysis from GigaOM Pro:
Subscriber content. Sign up for a free trial.

• Mobile Q4: All Eyes Were on Android, 4G and the Rising Tablet Tide
• Report: A Mobile Video Market Overview
• In Q3, the Tablet and 4G Were the Big Stories