iPhone iOS 4 Integration

These instructions are for integrating iPhone applications which will be run on iOS4 devices. Take a look at the iPhone Integration guide for instructions on pre iOS 4 apps. These instructions assume you are using xCode to build your project and will work whether you choose to integrate with the binary library file, or by adding the source code directly to your application.

1) Go to the Localytics Registration Page and create an account if you do not already have one.

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

3) Download the iOS 4 Library as Source.

4) Copy libLocalytics.a and LocalyticsSession.h from the binary package, or the entire 'src' folder from the source package, which you downloaded in step 3 to your application's project directory.

5) Open Xcode and select “Add to Project” from the Project menu. In the open dialog, select the files from step 4, and click ok. On the next dialog which appears make sure “Recursively create groups for any folders” is selected and click 'Add'.

6) In your application's delegate file (The file whose default name is <YourApplication>AppDelegate.m) add the line:

#import "LocalyticsSession.h"

under any existing imports.

7) In the same file, add the following line to the end of applicationDidFinishLaunching. This opens the session on app start.

[[LocalyticsSession sharedLocalyticsSession] startSession:@"APP KEY FROM STEP 2"];

8) 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. If you do not have this function simply copy the definition below:

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

9) 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). If you do not have this function simply copy the definition below:

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

10) 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. If you do not have this function create it from the definition below:

[[LocalyticsSession sharedLocalyticsSession] close];
[[LocalyticsSession sharedLocalyticsSession] upload];

If you do not have an applicationWillTerminate function, add it, along with the above code by pasting the following into the end of your delegate .m file:

- (void)applicationWillTerminate:(UIApplication *)application {
    // Close Localytics Session
    [[LocalyticsSession sharedLocalyticsSession] close];
    [[LocalyticsSession sharedLocalyticsSession] upload];
}

11) Test your app. Launch the simulator (or even better, compile, sign, and run on 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.

12) By default sessions are closed if they are in the background for more than 15 seconds. You may change this timeout by changing the value of the backgroundSessionTimeout member of the session. This variable is expressed in seconds. For example. To change the background time to one minute do the following:

[LocalyticsSession sharedLocalyticsSession].backgroundSessionTimeout = 60;

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

[[LocalyticsSession sharedLocalyticsSession] tagEvent:@"INTERESTING_EVENT"];

where INTERESTING_EVENT 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.

11) Add Attributes to 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 sharedLocalyticsSession] tagEvent:@"Options saved" attributes:dictionary];

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. See our introductory [http://www.localytics.com/index.php/blog/post/new-feature-explored-event-attributes/ blog post] for more information.

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 "Localytics_TestAppDelegate.h"
#import "Localytics_TestViewController.h"
 
// Pre defined event text.
#define EVENT_RESET_BUTTON @"RESET_BUTTON"
 
@implementation Localytics_TestAppDelegate
 
@synthesize window, viewController;
- (void)applicationDidFinishLaunching:(UIApplication *)application {
    [window addSubview:viewController.view];
    [window makeKeyAndVisible];
 
    // Open Localytics Session
    [[LocalyticsSession sharedLocalyticsSession] 
         startSession:MY_APP_KEY];
}
 
- (void)applicationWillEnterForeground:(UIApplication *)application {
    // Attempt to resume the existing session or create a new one.
    [[LocalyticsSession sharedLocalyticsSession] resume];
    [[LocalyticsSession sharedLocalyticsSession] upload];
}
 
- (void)applicationDidEnterBackground:(UIApplication *)application {
    // close the session before entering the background
    [[LocalyticsSession sharedLocalyticsSession] close];
    [[LocalyticsSession sharedLocalyticsSession] upload];
}
 
- (void)applicationWillTerminate:(UIApplication *)application {
    // Close Localytics Session in the case where the OS terminates the app
    [[LocalyticsSession sharedLocalyticsSession] close];
    [[LocalyticsSession sharedLocalyticsSession] upload];
}
 
// An action tied to a button which is defined in the view controller. 
// Shown here for an example of when to use tags
- (void)restButtonClicked(id)sender {
        [[LocalyticsSession sharedLocalyticsSession] tagEvent:EVENT_RESET_BUTTON];
}
 
- (void)dealloc {
    [viewController release];
    [window release];
    [super dealloc];
}
@end

• Developer's Integration Guide - More detailed information about using Localytics including tips and best practices.
• iPhone iOS 4 header docs