iOS SDK Integration Guide

All Apps Must Run SDK Version 2.17 or Above

All new submissions to the App Store must be running the version 2.17 or greater of the Localytics iOS SDK to ensure they are approved by Apple and support the new advertisingIdentifier. This library is fully compatible with iOS 6 and previous iOS versions. The target platform has to be at least iOS 4.

UDID Removed
Localytics uses the advertisingIdentifier provided by Apple in iOS 6 to help ensure that unique users, retention reports, and other analyses are accurate and consistent for all iPhone and iPad apps. The Unique Device Identifier (UDID) is no longer used. For devices that are upgraded from iOS 5 to iOS 6, the transition will be managed by Localytics to avoid the appearance of “new” users resulting from the re-installation of your app.

Deprecated Libraries
Support for all libraries before version 2.13 has been deprecated and all customers are encouraged to upgrade to a more recent version of the libraries. New features may not be supported and and ongoing support for event and session tracking will be gradually decreased.

Ten Minute Instrumentation Instructions

1) Log into your Localytics account or create an account if you do not already have one.

2) In your account, create a new application and record the application key.

3) Download the latest version of the Localytics SDK.

4) Before starting, delete any existing Localytics source from your project. The included binary will fully replace the capabilities of any existing Localytics source code, providing both analytics and app marketing functionality.

5) Add the unzipped contents of your SDK directory to your Xcode project. You may directly drag the SDK folder from Finder into the Project Navigator in Xcode. Remember to add the new files to the specific target for which you are compiling.

6) Add AdSupport.framework, libz.dylib, libsqlite3.dylib, and SystemConfiguration.framework to your project:

• • Click on the project in the project navigator. This will bring up the project view.
• • From here, select your target and then select the ‘Build Phases’ tab.
• • Open the ‘Link Binaries with Libraries’ expander and click the’+’ button. Find each library from the list and click ‘add’

NOTE: Change the AdSupport.framework library from “Required” to “Optional”. This will provide backwards compatibility for pre-iOS 6 targets where the framework does not exist.

Sessions

1) In your application’s delegate file, the file whose default name is <YourApplication>AppDelegate.m, add the following line under any existing imports:

#import "LocalyticsSession.h"

2) In the same file, add the following line to the start of applicationDidFinishLaunching. This opens the session and causes an upload on app start. If you intend to track screen flow this has to happen before thew rootViewController is changed. In newer projects the function you are adding to may be called didFinishLaunchingWithOptions. If you do not have this, or any other application functions defined, simply create them from the definitions below:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
   [[LocalyticsSession shared] startSession:@"YOUR APP KEY"];

   self.window.rootViewController = self.viewController;
   [self.window makeKeyAndVisible];

   return YES;
}

TIP: Once data is uploaded it cannot be deleted. Therefore it is recommended to create a test app in Localytics and use that while you perfect your instrumentation and then switch the app key for the production app.

3) In the same file, add the following lines to the end of applicationDidEnterBackground. This closes the session when the app goes into the background and attempts an upload.

- (void)applicationDidEnterBackground:(UIApplication *)application 
{
   [[LocalyticsSession shared] close];
   [[LocalyticsSession shared] upload];
}

4) In the same file, add the following lines to the end of applicationWillEnterForeground. This attempts to resume the previous session or create a new one if more than 15 seconds have passed and upload any data (nothing happens if data was successfully uploaded by the applicationDidEnterBackground call).

- (void)applicationWillEnterForeground:(UIApplication *)application 
{
   [[LocalyticsSession shared] resume];
   [[LocalyticsSession shared] upload];
}

5) In the same file, add the following lines to ApplicationWillTerminate. Under normal circumstances this function will not be called but there are some cases where the OS will terminate the app.

- (void)applicationWillTerminate:(UIApplication *)application 
{
   [[LocalyticsSession shared] close];
   [[LocalyticsSession shared] upload];
}

6) Optional – When the screen locks due to idle usage the app is not stopped. As a result, with the above integration time spent on a locked screen contributes to session length. When the screen locks applicationWillResignActive is called by the app delegate, and when the user returns applicationDidBecomeActive is called. In this calls the session can be closed and resumed. This way, if the screen is locked for more than 15 seconds the session is ended and a new session is created when the user comes back:

- (void)applicationWillResignActive:(UIApplication *)application
{
    [[LocalyticsSession shared] close];
    [[LocalyticsSession shared] upload];
}

- (void)applicationDidBecomeActive:(UIApplication *)application
{
    [[LocalyticsSession shared] resume];
    [[LocalyticsSession shared] upload];
}

7) Test your app. Launch the simulator (or even better, a real device), let the data upload, and view it on the webservice to make sure it is there. Remember that the upload is only guaranteed when the session is started so any events you tag may not appear until your second session.

Events (Recommended)

Unsure what events to tag? Check our Event Recommendations

Anywhere in your application where an interesting event occurs you may tag it by adding the following line of code:

[[LocalyticsSession shared] tagEvent:@"Options Saved"];

where “Options Saved” is a string describing the event. It is recommended that you read the Tagging section in the Developer’s Integration Guide in order to get the most value out of your tags.

For some events, it may be interesting to collect additional data about the event. Such as how many lives the player has, or what the last action the user took was before clicking on an advertisement. This is accomplished with the second form of tagEvent, which takes a dictionary of key/value pairs along with the event name:

   NSDictionary *dictionary =
      [NSDictionary dictionaryWithObjectsAndKeys:
         @"miles per hour",
         @"display units",
         @"yes",
         @"blank screen",
         nil];
   [[LocalyticsSession shared] tagEvent:@"Options Saved" attributes:dictionary];

See our introductory blog post for more information. It is recommended that you read the Event Attributes section in the Developer’s Integration Guide in order to get the most value out of your attributes.

Important Note:

Make sure never to upload data from a continuous set or from user-generated values. Consider tagging a file transfer event with the file size and name. If the file can be any size this will cause many buckets to be created on our server. When you look at the data in the charts, there will be many charts each with only a few results and the data will be in-actionable. Instead, it is necessary to bucket this data into groups such as “0 to 1K”, “1K to 50K”, etc. Similarly, if you allow users to create their own name for the file, you will have a list of thousands of unique file names that are also not useful to view in the dashboard. See our blog post for an example.

Screen Flows (Recommended)

When a view is shown, it can be tagged so that all user flows through the application can be tracked. To do this, add a tagScreen call in the viewDidAppear call for each of your views. If your project doesn’t define this function, create it from the definition below. This should live in the view controller code. It is not recommended to append the name ‘screen’ to each screen as this is redundant when viewing the data online. Like events, it is also not recommended to name each screen dynamically. For example, a screen displaying an article should be tagged simply as “Article” instead of the title of the article.

- (void)viewDidAppear:(BOOL)animated
{
   [super viewDidAppear:animated];

   [[LocalyticsSession shared] tagScreen:@"Settings"];
}

Test Mode (Recommended)

Test mode allows you to test marketing campaigns on a limited set of devices before broadcasting them to a larger audience. When creating a new campaign in our marketing dashboard, you may opt to have us send you a special unlock URL via email or SMS. Clicking on this URL from your device will unlock the ability to view test campaigns.

For your app to properly handle this URL, you must perform the following two steps:

1) Modify your app delegate to handle the unlock URL

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
    // If the URL is handled by Localytics, we will return yes.
    if([[LocalyticsAmpSession shared] handleURL:url])
        return YES;

    //	
    // Otherwise, any of your custom URL handling logic goes here.
    //	

    return NO;
}

2) Register your app to handle the unlock URL scheme by setting the “URL Types” in your plist file. The URL scheme is defined as “amp” followed by your application key, as demonstrated below. If you switch between multiple app keys, such as separate testing and production app keys, there is no harm in registering both URL schemes.

Sample Application Skeleton

To see it all at once, here is the skeleton of an instrumented iPhone application. Shown here is the Application’s AppDelegate.m file, because no other files need to be touched in the instrumentation process. (Although it is possible to add the event Tagging code to any file).

// SampleAppDelegate.m
#import "YourAppDelegate.h"
#import "YourViewController.h"

@implementation YourAppDelegate

@synthesize window, viewController;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
{
   [window addSubview:viewController.view];
   [window makeKeyAndVisible];

   // Open Localytics Session
   [[LocalyticsSession shared] startSession:@"YOUR APP KEY"];
}

- (void)applicationWillEnterForeground:(UIApplication *)application {
   // Attempt to resume the existing session or create a new one.
   [[LocalyticsSession shared] resume];
   [[LocalyticsSession shared] upload];
}

- (void)applicationDidEnterBackground:(UIApplication *)application {
   // Close the session before entering the background
   [[LocalyticsSession shared] close];
   [[LocalyticsSession shared] upload];
}

- (void)applicationWillTerminate:(UIApplication *)application {
   // Close the session in the case where the OS terminates the app
   [[LocalyticsSession shared] close];
   [[LocalyticsSession shared] upload];
}

- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url
{
    if([[LocalyticsAmpSession shared] handleURL:url])
        return YES;
    
    //
    // Any custom URL logic goes here
    //

    return NO;
}

// An action tied to a button
- (void)resetButtonClicked(id)sender 
{
   [[LocalyticsSession shared] tagEvent:@"Reset Button Pressed"];
}
@end

Troubleshooting

Having issues seeing your data? Here are some solutions to common problems.

1) Double check the app key. Is it missing a first and last character or does it have an extra space somewhere?

2) Enable tracing. This will show whether the session was successfully opened, and whether the upload returned a 202 as expected or something else.

• SDK 2.14 or older. Debugging traces can be enabled in LocalyticsSession.h by setting

  DO_LOCALYTICS_LOGGING "true";

• SDK 2.15 or newer. Debugging traces can be enabled in your AppDelegate didFinishLaunchingWithOptions by setting

  [[LocalyticsSession shared] setLoggingEnabled:YES];

3) If you are still having trouble contact support@localytics.com and provide the logs from step 2.

If you see the error: /LocalyticsSession.m:830: error: request for member ‘__forwarding’ in something not a structure or union change your compiler to be Apple LLVM compiler 3.1 or above.

Next Steps

Ready to ship? Check our list of common integration mistakes to ensure you get the best reporting experience possible.

For Premium and Enterprise customers, please continue to our Advanced Features Guide for information on how to implement some of our most powerful features.

Alternate SDK version

If you prefer an analytics only version of the Localytics iOS SDK in source code, instructions can be found here

Please note, by using the analytics source code version of the Localytics iOS SDK you will not be able to take advantage of in-app messaging or other marketing related solutions.