Logging data on the iOS

If you want to track user behavior on your iPhone\iPad application, first download the Mixpanel iOS API by cloning the git repository:

git clone http://github.com/mixpanel/mixpanel-iphone.git

or download the latest version from http://github.com/mixpanel/mixpanel-iphone/zipball/master and extract the files. The respository has two folders:

1. MPLib - The Source code for the Mixpanel API and its dependencies
2. MixpanelEventSample - A sample application that tracks events using Mixpanel.
3. Docs - Documentation for the Project.

Setup

Adding Mixpanel to your Xcode project is as easy as:

1. Drag and drop the MPLib folder into your project.
2. Check the "Copy items into destination Group's folder" and select Recursively create groups for any added folders.

And that's it.

Initializing Mixpanel

The first thing you need to do in order to use Mixpanel is to initialize the MixpanelAPI object. We recommend doing this in applicationDidFinishLaunching: of application:didFinishLaunchingWithOptions in your Application delegate.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {    
    // Override point for customization after application launch.
	mixpanel = [MixpanelAPI sharedAPIWithToken:MIXPANEL_TOKEN];
    // Add the view controller's view to the window and display.
    [window addSubview:viewController.view];
    [window makeKeyAndVisible];
    return YES;
}

Tracking Events

After initializing the MixpanelAPI object, you are ready to track events. This can be done with the following code snippet:

- (IBAction) registerEvent:(id)sender {
	MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
	[mixpanel track:@"Player Create"];
}

If you want to add properties to the event you can do the following:

- (IBAction) registerEvent:(id)sender {
	MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
	[mixpanel track:@"Player Create" 
		 properties:[NSDictionary dictionaryWithObjectsAndKeys:[genderControl titleForSegmentAtIndex:genderControl.selectedSegmentIndex], @"gender",
															[weaponControl titleForSegmentAtIndex:weaponControl.selectedSegmentIndex], @"weapon", nil]];
}

This code snippet is taken from the MixpanelEventSample Project. Line 15-20 of the MixpanelEventSampleViewController.m file.

Super Properties

Super properties are an easy way to store data about your users. They are global properties that get attached to everything you are tracking. More information can be found here.

If you want to register a super property for your current user, you can do it as follows:

MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
[mixpanel registerSuperProperties:[NSDictionary dictionaryWithObject:@"Paid" forKey:@"User Type"]];

This call will register the "User Type" property with a value of @"Paid" for the current user on both events and funnels. The permitted values for the eventType parameter are:

If the "User Type" property was previously registered, its value will be overwritten. As a shortcut, you can use registerSuperProperties: to attach super properties to all events. If you do not want to overwrite existing values of a super property you can use the following call:

MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
[mixpanel registerSuperPropertiesOnce:[NSDictionary dictionaryWithObject:@"Paid" forKey:@"User Type"]];

After this call, the value of the "User Type" property will be written only if it did not exist. There is another flavor of registerSuperPropertiesOnce:eventType and it can be used as follows:

MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
[mixpanel registerSuperPropertiesOnce:[NSDictionary dictionaryWithObject:@"Paid" forKey:@"User Type"]
						 defaultValue:@"Free"];

This call will write out the new value for the "User Type" property if it does not exist or if its current value is "Free". As a shortcut, you can use registerSuperPropertiesOnce: to attach super properties to all events without overwriting their current values.

Identifying a User

MixpanelAPI uses a one-way hash of the MAC address of the current device as its default identifier. You can easily change the identifier with the following call:

MixpanelAPI *mixpanel = [MixpanelAPI sharedAPI];
[mixpanel identifyUser:username];

Where username is an NSString.

Using multiple MixpanelAPI instances

It is now possible to use multiple MixpanelAPI instances in a single application. This makes it easy to send events to multiple Mixpanel projects. To iniitialize a new, non singleton instance of MixpanelAPI, use the initWithToken: method as follows:

MixpanelAPI *mixpanel = [[MixpanelAPI alloc] initWithToken:MIXPANEL_TOKEN];

The developer is responsible for the lifecycle of this object. The recommended way of using this is to initialize all of your MixpanelAPI instances in application:didFinishLaunchingWithOptions: and deallocate them in the dealloc method of your Application Delegate. If you chose to dispose of this object before the end of the application's lifetime, you need to call the stop method. This removes the instance as an observer to the application's lifecycle events and invalidates any internal timers. Below is a code snippet that does this:

[mixpanel stop];
[mixpanel release];