iPhone Documentation

Pinch Analytics provides detailed application usage reporting through a simple web-based administration panel. Setting up your application to take advantage of the reporting system is a simple, straightforward process requiring just a few modifications to your code. Pinch Analytics enables you to keep track of the statistics that matter most to you.

Table of Contents

1. Quick Start
2. Detailed Instructions
   1. Get the Pinch Analytics library
   2. Add the files to your Xcode project
   3. Add libsqlite3.dylib, SystemConfiguration.framework, and CoreLocation.framework to your project
   4. Start and stop the main Beacon
   5. Add sub-beacons to your application (optional)
   6. Integrate Facebook Connect for demographic reporting (optional)
   7. Optimize CoreLocation (optional)

Detailed Instructions

1. Get the Pinch Analytics library.

   The current version of the library can be found here. Inside the zip file, you'll find three files:

   • Beacon.h - the main header file for Beacon
   • Beacon+FBConnect.h - a category of Beacon that adds support for sending a Facebook session to Beacon for demographic reporting
   • libPMAnalytics-(version).a - the compiled analytics library (a fat binary that works on both the device and the simulator)

2. Add the files to your Xcode project.

   The easiest way to do this is to simply highlight the files in the Finder and drag them into the "Groups & Files" pane in Xcode. First, add the headers, and ensure that "Copy items into destination group's folder" is checked.

   

   Then add the library, again ensuring that "Copy items into destination group's folder" is checked.

   

   Your project should look something like this:

   

3. Add libsqlite3.dylib, SystemConfiguration.framework, and CoreLocation.framework to your project.

   The Pinch Analytics code requires a few iPhone system frameworks to function — frameworks you may already be using. While there are a few ways to add system libraries to your project, the easiest way we've found is to right click (or control-click) your Target under the Groups & Files pane and select Get Info.

   Then click the + button near the bottom of the General tab and select the following frameworks:

   
   

   • SQLite (libsqlite3.dylib)

     Beacon uses a SQLite database to cache analytics data on the device when network connectivity is not available.

     SDK 3.x Update: libsqlite3.0.8.6.dylib (as pictured) no longer exists. Choose libsqlite3.dylib instead.

   • SystemConfiguration (SystemConfiguration.framework)

     The SystemConfiguration framework is used to determine network connectivity.

   • CoreLocation (CoreLocation.framework)

     If enabled, CoreLocation will report your users' latitude and longitude for detailed regional statistics.

     Note: Even if you have disabled CoreLocation, since our library references it, it must be present in your project. Since it is a system library that comes installed on the device, it doesn't add any size to your application.

   
   

   After adding the required frameworks, the "Link Binary With Libraries" build phase for your target should have the four libraries you've added (libPMAnalytics, libsqlite, SystemConfiguration, and CoreLocation). If you don't see all four of these, but they have been added to your project (likely in the Frameworks folder), you can add them to the target by dragging them under "Link Binary With Libraries."






4. Start and stop the main Beacon.

   The Pinch Analytics Beacon must be started and stopped along with your application. To do this, you must add a few lines of code to your project's AppDelegate.

   1. Add a header file

      Add the following import to your application's AppDelegate .m file.

      #import "Beacon.h"

      If you're integrating Facebook Connect, you should import this instead:

      #import "Beacon+FBConnect.h"

   2. Initialize the beacon

      Add the following code to your UIApplication delegate's applicationDidFinishLaunching: method. If the method does not exist, you should create it.

      Be sure to fill in your application code!

      - (void)applicationDidFinishLaunching:(UIApplication *)application {
          NSString *applicationCode = @"REPLACE THIS WITH YOUR APPLICATION CODE";
          [Beacon initAndStartBeaconWithApplicationCode:applicationCode
                                        useCoreLocation:NO
                                            useOnlyWiFi:NO
                                        enableDebugMode:YES];
          ....
      }

      Beacon's init method has a few parameters:

      • useCoreLocation: supply NO or YES.
        • If you specify YES, Beacon will create a CLLocationManager to get geolocation data. This will pop up a dialog asking the user to allow your app to use location data. Please read Should I enable Core Location in the Pinch Analytics library? in our FAQ for more information.
        • If you specify NO, Beacon will not create a CLLocationManager. You will still get country-level location reporting based on the device's IP address. Furthermore, if your application already uses CoreLocation, you can specify NO here and then pass in a CLLocation object.
      • useOnlyWiFi: supply NO or YES. We strongly recommend NO.

        This feature exists for developers who distribute applications in regions where cellular bandwidth isn't readily available as part of a service plan, so that their users aren't charged per kilobyte to transmit analytics data.

      • enableDebugMode: (optional), supply NO or YES. Don't distribute your app with this enabled!

        If enabled, Debug Mode will print verbose information about what's going on inside the Beacon library. You'll see these messages along with your app's NSLog()s or printf()s in Xcode's Debugger Console (command-shift-R). This is a feature our users have been asking for for a long time, and we hope you find it useful -- please post feedback on the forum.
        
        We think you'll find that the most useful information is about networking. With Debug Mode enabled, you'll see when your app is attempting to send Beacon sessions to our servers, and whether the connection was successful. Combined with our new Analytics Status feature on the developer site's "application info" page, which tells you when our servers successfully received and processed your first packet of analytics data, it will be much easier for you to know that you've correctly integrated our SDK.

   3. Terminate the beacon

      Add the following code to the end of your AppDelegate's applicationWillTerminate: method. Again, if the method does not exist you should create it.

      - (void)applicationWillTerminate:(UIApplication *)application {
          // Put your app's cleanup code here -- closing databases,
          // synchronizing NSUserDefaults, etc.
          
          // Call this last: Why? See this FAQ entry for more info.
          [Beacon endBeacon];
      }

5. Add sub-beacons to your application (optional)

   Sub-beacons allow you to collect statistics on individual parts of your application, and are useful to gain insight into how your customers actually use your app. Does anybody ever look at the High Scores view? How long does it take people to run a search and find what they're looking for?

   Starting a sub-beacon is easy: just call startSubBeaconWithName: at the start of any block of code you want usage data for. A sub-beacon's name can be any 32 characters, and we recommend that you be as descriptive as possible so your stats make sense when you're analyzing them later on.

   This example shows how you would track an action -- in this case, showing a High Scores list:

   - (void)showHighScores {
       [[Beacon shared] startSubBeaconWithName:@"High Scores" timeSession:NO];
   }

   The next snippet illustrates how to time an action with a sub-beacon:

   - (void)startLongTask {
       [[Beacon shared] startSubBeaconWithName:@"Long Task" timeSession:YES];
   }
   - (void)endLongTask {
       [[Beacon shared] endSubBeaconWithName:@"Long Task"];
   }

   While it is normally your responsibility to end your timed sub-beacons, any that are still running when [Beacon endBeacon] is called (at applicationWillTerminate) will be terminated automatically. Untimed sub-beacons do not need to be terminated.

   Allowed Characters: Below is a comprehensive list of characters that are allowed in sub-beacon names. Unfortunately, the current release of our analytics SDK doesn't check for invalid characters, so you'll have to do it manually. A good rule of thumb is to stick to ASCII characters. You'll notice a number of unicode characters at the end of the list — these are valid as well.

   '\t' '\n' '\r' ' ' '!' '"' '#' '$' '%' '&' "'" '(' ')' '*' ',' '-' '.' '/' '0' '1' '2' '3' '4' '5' '6' '7' '8' '9' ':' ';' '<' '=' '>' '?' '@' 'A' 'B' 'C' 'D' 'E' 'F' 'G' 'H' 'I' 'J' 'K' 'L' 'M' 'N' 'O' 'P' 'Q' 'R' 'S' 'T' 'U' 'V' 'W' 'X' 'Y' 'Z' '[' '\\' ']' '^' '_' '`' 'a' 'b' 'c' 'd' 'e' 'f' 'g' 'h' 'i' 'j' 'k' 'l' 'm' 'n' 'o' 'p' 'q' 'r' 's' 't' 'u' 'v' 'w' 'x' 'y' 'z' '{' '|' '}' '~' '' '€' '' '‚' 'ƒ' '„' '…' 'Œ' '' '‘' '’' '—' '˜' '™' 'ž' ' ' '¢' '£' '¥' '¦' '§' '¨' '©' '«' '¬' '°' '±' '¶' '¸' '»' '¼' '¿' 'Â' 'Ã' 'Å' 'Æ' 'â'

6. Integrate Facebook Connect for demographic reporting (optional)

   If your app uses Facebook Connect for iPhone, we've made it really easy to integrate with Pinch Analytics so you can collect anonymous demographic information like age and gender. You'll have to make just a few changes to your code:

   1. Use Beacon+FBConnect.h

      Import Beacon+FBConnect.h instead of Beacon.h: (Note: you'll need to have Beacon+FBConnect.h added to your project. Check out step 4.)

      #import "Beacon.h"
      
      #import "Beacon+FBConnect.h"
      

      Don't actually delete Beacon.h from your project, though, because Beacon+FBConnect.h depends on it. Beacon+FBConnect.h just exposes another method on Beacon - setFBConnectSession.

   2. Pass the Facebook session to Beacon

      Once the user has successfully logged into Facebook, your FBSessionDelegate will receive the message session:didLogin:, and you can pass the FBSession object to Beacon:

      - (void)session:(FBSession *)session didLogin:(FBUID)uid {
          [[Beacon shared] setFBConnectSession:session];
          ...
      }
      

      That's it! Be sure that your class conforms to the FBSessionDelegate protocol, and that you are setting it as the delegate when you create your session. Your code will likely look something like this:

      // SomeViewController.h
      
      #import "FBConnect/FBConnect.h"
      
      @interface SomeViewController : UIViewController
          <FBDialogDelegate, FBSessionDelegate, FBRequestDelegate> {
        FBSession *session;
      }
      @end
      

      // SomeViewController.m
      
      #import "Beacon+FBConnect.h"
      
      @implementation SomeViewController
      
      - (void)loadView {
        session = [FBSession sessionForApplication:kApiKey secret:kApiSecret delegate:self];
        ...
      }
      - (void)session:(FBSession *)session didLogin:(FBUID)uid {
        [[Beacon shared] setFBConnectSession:session];
        ...
      }
      
      @end
      

      For more information about Facebook sessions and authentication, see http://wiki.developers.facebook.com/index.php/Facebook_Connect_for_iPhone#Logging_In.

7. Optimize CoreLocation (optional)

   If your application already makes use of CoreLocation, you can replace Beacon's locator with your own. To do so, set useCoreLocation to NO when initializing Beacon, and pass in your CLLocation object once you've obtained the data:

   - (void)locationManager:(CLLocationManager *)manager
       didUpdateToLocation:(CLLocation *)newLocation
              fromLocation:(CLLocation *)oldLocation
   {
       // (your app's code)
       [[Beacon shared] setBeaconLocation:newLocation];
   }
   

That's it!

Your application is now ready to use Pinch Analytics. You will soon see activity in the developer site; as your application is executed, our servers collect and aggregate your beacons, crunching tons of raw data into useful reports.

One thing to keep in mind when first integrating the Beacon SDK is that collecting and aggregating data are separate processes.

Collecting data is just receiving packets from devices, doing some pre-processing, and placing them in a queue for the next step (aggregation). You can confirm that your data is being collected by enabling debug mode and watching your app's console output, and by checking the Analytics Status feature on the developer site's "application info" page, which tells you when our servers successfully received and processed your first packet of analytics data.

Aggregating data is the next step. This is where our multitude of servers crunch numbers on all your app's historical data and create the various reports you see on the developer site. This is a process that essentially runs in an infinite loop, aggregating reports as fast as we can. Some reports take longer than others.

The point we're trying to make here is that, even if you've implemented our SDK properly, there will be a delay before our various charts and graphs show your data. This is normal. Now, with Debug Mode and Analytics Status, you'll quickly know whether things are working.