Paul Hart

While it’s nice to know how many people have acquired your app, whether through iTunes Connect or with a third-party application like AppViz, neither of those will tell you about how your app is being used. For that kind of information you’ll need a metrics library that sits inside your application and measures usage patterns. Fortunately, Pinch Media offers a great solution called Pinch Metrics. Here’s a quick guide on setting it up for your app.

Jump Into The Pool

As with so many services online, you can’t play until you’ve registered. Cleverly, the folks at Pinch Media recognize that the entire point of a developer signing up with them is to put the Pinch Metrics library into their app, so the registration process includes a step to add an initial application. After this, and once you’ve confirmed your email address, you’ll be provided with a unique key to identify your application, as well as a link to download the metrics library.

Project Configuration

Now that we’ve got the basics available, it’s time to build them into the project. When you crack open the zip file that contains the metrics library (at least as of version 69), you’ll find a couple of header files and a library ‘.a’ file. If you’re using Facebook Connect, you’ll want to use the Beacon+FBConnect.h file; otherwise, or if the last few words made no sense to you, use the Beacon.h file.

Drag the header file from the finder into the Classes folder of your project in Xcode, and check the ‘copy items’ box before clicking ‘Add’. Do the same process with with the libPMAnalytics file, but copy that to the Frameworks folder.

Next you’ll need to add a few more frameworks that the Pinch Metrics library depends on. These are CoreLocation, SystemConfiguration, and libsqlite3.a. You should be able to find these by control-clicking on the Frameworks folder, selecting Add… Existing Frameworks…, and then highlighting the required items from the list.

Initial Code Updates

The foundations are now in place for you to track user habits, and your code needs to build on them. The first thing to do is to import your selected header file into your application delegate’s header (something like ‘blahblahAppDelegate.h).

To start gathering metrics, you need to call the Beacon object’s initAndStartBeaconWithApplicationCode class method. This call should be made in your applicationDidFinishLaunching method. You can pass parameters to configure whether or not to collect the user’s location, and whether or not to send metrics over a WiFi connection only.

While you don’t have to stop the Beacon cleanly, it will consider closures of the application without a clean shutdown as crashes. To close the Beacon, call the endBeacon instance method. You’ve now done enough to start collecting useful data about the number of times your users run your app, where they are (either based on physical location or by IP address), and how long they had your app open.

Getting Granular

While it’s nice to know that people used your app, it’s better to know what they were doing with it. You can add as many ’sub-beacons’ to your app as you like. No configuration is required at Pinch Metrics to create more sub-beacons, you can just create them in your code as needed. Each sub-beacon requires a unique name of 32 characters or less. A sub-beacon is created by calling the startSubBeaconWithName instance method.

You can specify whether or not you want your sub-beacon to be timed. In some circumstances you want to know how long a user accessed a particular activity, such as playing a game. In other cases, you’re simply interested to know whether or not something was accessed at all, perhaps an in-app purchase screen (or better yet, a purchase confirmation screen). If you create a timed sub-beacon, you’re responsible for stopping the timer by calling the endSubBeaconWithName instance method. Any sub-beacons you forget to stop will automatically be stopped when the application exits.

Knowing Is Half The Battle

With the addition of a tool like Pinch Metrics, you’ll get a better idea of how your users are interacting with your application. This kind of knowledge can help inform your plans for further development.