This article will describe how to integrate the Analytics iOS monitor in an iOS application.

The integration consists of three steps:

1. Add the monitor-library to your project
2. Optionally modify your project's C++ settings
3. Create and start the monitor

Before getting started you must also have created an application so you have a product id. You will need that in the integration. Read more about how to Add Analytics to Your Application.

Requirements

These are the requirements for adding Analytics into your iOS app:

• iOS Deployment Target: minimum iOS 5.0
• Targeted Device Family: minimum iPhone 3GS and iPad 1
• Valid Architectures: armv7, armv7s, arm64, i386 (simulator) (no armv6/3G support)

Step 1: Add the monitor-library

The monitor is added as a framework to your XCode project.

Drag and drop the downloaded EQATECAnalyticsMonitoriOS.framework folder into the Frameworks folder:

You will most likely want to copy the framework into your project's folder because otherwise your XCode project will simply point to the framework's original path, which is probably your Download-folder. So either copy the framework to another preferred location prior to importing it, or select the option to have it copied into your project:

Once imported, try to Build your project again. If it builds without problems then proceed to Step 3. If you see errors like those below then proceed with Step 2 to modify your project's C++ settings:

Step 2: Optionally modify C++ project settings

The monitor for iOS is written in C++ and relies on Apple's LLVM C++ standard library libc++ to be linked into your application. If your application is already using that C++ library you don't need to do anything. If not then you need to explicitly link with libc++. Open Build Phases and click + to add the library libc++.dylib to your project:

Technical note: On iOS there are two standard C++ libraries: Apple's libc++ (the compiler default now) and GNU's stdlib++ (the compiler default up until 2012). The iOS monitor uses Apple's libc++ which therefore needs to be explicitly linked into your app, even if your app may already be using (i.e. linking with) GNU's stdlib++ library. Yes, this can be a bit confusing. Check out http://libcxx.llvm.org/ for more info.

Step 3: Create and start the monitor

By now you should have added the monitor framework to your project and it should build without problems. Before proceeding, please verify that this is the case.

Next step is creating the starting the monitor, as described in the Monitor Integration article. After that, when running your iOS app on a device or the simulator, you will see data from it appear in the Analytics client dashboard.

Precisely how you wish to use the monitor into your source is up to you and your coding-preferences. Your app needs to create a monitor object and it needs to call Start and Stop on that object and later on you will most likely want to call other API methods on it, too.

Use a Singleton pattern for the monitor

The simplest approach is to add the monitor as a singleton object. It will handle the creation of the monitor and make it accessible from all over you application. So that is what we will do here, inspired by the recommended patterns for creating singletons in iOS 5.

Changes to your project

Here are the changes that we will make to your application project:

• Add the monitor-singleton as two new files, Analytics.m and Analytics.h (marked in red)
• Set your unique product id for this project (marked in blue)

• Edit your existing code to access and start the monitor (marked in green)

  

First, add the two new files to your project and change the productId to your own, e.g. "b32badb....ee82a9ce7".

One header file, Analytics.h:

#import <EQATECAnalyticsMonitoriOS/EQATECAnalyticsMonitor.h>

@interface Analytics : NSObject
+(EQATECAnalyticsMonitor*) Monitor;
@end

And the implementation file, Analytics.m:

@implementation Analytics
+ (EQATECAnalyticsMonitor *)Monitor
{
  static NSString *productId = @"YOUR-PRODUCT-ID";

  static EQATECAnalyticsMonitor *monitor = nil;
  static dispatch_once_t _singletonPredicate;
  dispatch_once(&_singletonPredicate, ^{
    NSString *version = [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleVersion"];
    EQATECAnalyticsMonitorSettings *settings =
         [EQATECAnalyticsMonitorSettings settingsWithProductId:productId version:version];
    settings.loggingDelegate = [EQATECTraceLogger traceLogger];
    monitor = [EQATECAnalyticsMonitor monitorWithSettings:settings];
  });
  return monitor;
}
@end

Next, add Analytics.h to your precompiled header file so it is available throughout you entire project, without you having to do #import "Analytics.h" everywhere:

//  Prefix header
//  The contents of this file are implicitly included at the beginning of every source file.
//  .....

// Import Analytics monitor singleton
#import "Analytics.h"

Finally, extend your existing code. The most appropriate place to control the monitor lifetime is in your application's main window code::

@implementation TESTAppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [[Analytics Monitor] start];
  // existing code
}
- (void)applicationDidEnterBackground:(UIApplication *)application
{
  // existing code
  [[Analytics Monitor] stop];
}
- (void)applicationWillEnterForeground:(UIApplication *)application
{
  [[Analytics Monitor] start];
  // existing code
}
- (void)applicationWillTerminate:(UIApplication *)application
{
  // existing code
  [[Analytics Monitor] stop];
}
@end

Conclusion

After completing the integration steps in this guide, Analytics should be integrated into your application. When you run it, you should see data within 5 minutes on the Analytics client dashboard. If not then please check the article on Your First Data.

See Also

• Your First Data
• Troubleshooting
• Main Dashboard