iOS API Integration

Installing the library

The easiest way to get Mixpanel into your iOS project is to use CocoaPods.

  1. Install CocoaPods using gem install cocoapods
  2. Create a file in your Xcode project called Podfile and add the following line:
    pod 'Mixpanel'
    
  3. Run pod install in your Xcode project directory. CocoaPods should download and install the Mixpanel library, and create a new Xcode workspace. Open up this workspace in Xcode.

You can also get the library by downloading the latest version from Github and copying it into your project.

Compatibility

Versions of Mixpanel greater than 2.1.1 will work for a deployment target of iOS 6.0 and above. You need to be using Xcode 5 and a Base SDK of iOS 7.0 for your app to build. If you are still using XCode 4.x or building against an earlier SDK version, you need to use a previous version of the mixpanel library. You can do this in cocoapods by changing your Podfile to read:

pod 'Mixpanel', '< 2.1.1'

Initializing the library

To start tracking with the Mixpanel iOS library, you must first initialize it with your project token. You can find your project token in your settings dialog on the Mixpanel website.

To initialize the library, call sharedInstanceWithToken: with your project token as its argument. Once you've called this method once, you can access your instance throughout the rest of your application with sharedInstance.

#define MIXPANEL_TOKEN @"YOUR_TOKEN"

// Initialize the library with your
// Mixpanel project token, MIXPANEL_TOKEN
[Mixpanel sharedInstanceWithToken:MIXPANEL_TOKEN];

// Later, you can get your instance with
Mixpanel *mixpanel = [Mixpanel sharedInstance];

In most cases, it makes sense to do this in application:didFinishLaunchingWithOptions:.

Sending events

Once you've initialized the library, you can track an event by calling track:properties: with the event name and properties.

Mixpanel *mixpanel = [Mixpanel sharedInstance];

[mixpanel track:@"Plan Selected" properties:@{
    @"Gender": @"Female",
    @"Plan": @"Premium"
}];

Super properties

It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event—for example, the user's age, gender, or source.

To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app.

To set super properties, call registerSuperProperties:.

Mixpanel *mixpanel = [Mixpanel sharedInstance];

// Send a "User Type: Paid" property will be sent
// with all future track calls.
[mixpanel registerSuperProperties:@{@"User Type": @"Paid"}];

Going forward, whenever you track an event, super properties will be included as properties. For instance, if you call

Mixpanel *mixpanel = [Mixpanel sharedInstance];

[mixpanel track:@"signup" properties:@{
    @"signup_button": @"test12"
}];

after making the above call to registerSuperProperties:, it is just like adding the properties directly:

Mixpanel *mixpanel = [Mixpanel sharedInstance];

[mixpanel track:@"signup" properties:@{
    @"signup_button": @"test12",
    @"User Type": @"Paid"
}];

Setting super properties once and only once

If you want to store a super property only once (often for things like ad campaign or source), you can use registerSuperPropertiesOnce:. This function behaves like registerSuperProperties: and has the same interface, but it doesn't override super properties you've already saved.

Mixpanel *mixpanel = [Mixpanel sharedInstance];

[mixpanel registerSuperPropertiesOnce:@{@"source": @"ad-01"}];

This means that it's safe to call registerSuperPropertiesOnce: with the same property on every app load, and it will only set it if the super property doesn't exist.

Managing user identity

The Mixpanel library will assign a default unique identifier (we call it a "distinct ID") to each unique user who installs your application. This distinct ID is saved to device storage so that it will persist across sessions.

If you choose, you can assign your own user IDs. This is particularly useful if a user is using your app on multiple platforms (both web and mobile, for example). To assign your own distinct_ids, you can use identify:.

Mixpanel *mixpanel = [Mixpanel sharedInstance];

// Associate all future events sent from
// the library with the distinct_id 13793
[mixpanel identify:@"13793"];

Calling identify: will change the ID being sent with your events. If you change the ID in the middle of a funnel, the funnel will break - we won't be able to associate the old ID with the new.

Linking two user IDs

In situations where you want to link the two IDs (in practice, this really just means when the user signs up) you should use createAlias:, which sends an update to our server linking the current ID with a new ID.

// This makes the current ID (an auto-generated GUID)
// and 'joe@example.com' interchangeable distinct ids.
[mixpanel createAlias:@"joe@example.com"
    forDistinctID:mixpanel.distinctId];
// You must call identify if you haven't already
// (e.g., when your app launches).
[mixpanel identify:mixpanel.distinctId];

The recommended usage pattern is to call both createAlias: and identify: when the user signs up, and only identify: (with their new user ID) when they log in. This will keep your signup funnels working correctly.

If you use createAlias:, you should only call it once during the lifetime of the user.

Storing user profiles

In addition to events, you can store user profiles in Mixpanel's People Analytics product. Profiles are persistent sets of properties that describe a user—things like name, email address, and signup date. You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send notifications, such as emails, SMS, or push notifications.

Before you send profile updates, you must call identify:. This ensures that you only have actual registered users saved in the system.

Setting profile properties

You can set properties on a user profile with people set:.

Mixpanel *mixpanel = [Mixpanel sharedInstance];

// mixpanel identify: must be called before
// people properties can be set
[mixpanel identify:@"13793"];

// Sets user 13793's "Plan" attribute to "Premium"
[mixpanel.people set:@{@"Plan": @"Premium"}];

This will set a "Plan" property, with a value "Premium", on user 13793's profile. If there isn't a profile with distinct_id 13793 in Mixpanel already, a new profile will be created. If user 13793 already has a property named "Plan" in their profile, the old value will be overwritten with "Premium".

Incrementing numeric properties

You can use people increment: to change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, messages sent, or points earned.

// Here we increment the user's point count by 500.
[mixpanel.people increment:@"point count" by:500];

// Pass an NSDictionary to increment multiple properties
[mixpanel.people increment:@{
    @"dollars spent": @17,
    @"credits remaining": @-34
}];

Other types of profile updates

There are a few other types of profile updates. To learn more, please follow the links to the full API documentation.

Tracking revenue

Mixpanel makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with people trackCharge:. This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

// Make sure identify has been called before making revenue
// updates
[mixpanel identify:@"13793"];

// Tracks $100 in revenue for user 13793
[mixpanel.people trackCharge:@100];

// Refund this user 50 dollars
[mixpanel.people trackCharge:@-50];

// Tracks $25 in revenue for user 13793 on the 2nd of
// January
[mixpanel.people trackCharge:@25 withProperties:@{
    @"$time": @"2012-01-02T00:00:00"
}];

Registering for push notifications

The Mixpanel library includes support for sending push notification device tokens to Mixpanel. Once you send a device token, you can use Mixpanel to send push notifications to your app.

You can send a device token to Mixpanel using people addPushDeviceToken:

- (void)application:(UIApplication *)application
didRegisterForRemoteNotificationsWithDeviceToken:
        (NSData *)deviceToken
{
    Mixpanel *mixpanel = [Mixpanel sharedInstance];

    // Make sure identify has been called before sending
    // a device token.
    [mixpanel identify:@"13793"];

    // This sends the deviceToken to Mixpanel
    [mixpanel.people addPushDeviceToken:deviceToken];
}

Push notifications quick start guides

There is a quick start guide for iOS push notifications available to help you get started with push notifications in your app. It includes instructions for provising your app to use the Apple Push Notification service (APNs), preparing your push SSL certificate from Apple and configuring your app for push notifications.

There is also a step by step guide to integrating Mixpanel push notifications with your app that covers uploading your push credentials to Mixpanel, registering your user's device token from your app, and handling inbound push notification messages.

In-app notifications

There is a quick start guide for iOS in app notifications to help you get integrated.

Make sure that you have already:

  1. Included the latest version of the Mixpanel iOS library in your app
  2. Made sure you are identifying your users in the app.
  3. Created an in-app notification on the Notifications tab of the Mixpanel website.

Surveys

If you are using our mobile surveys product there are 3 things you need to make sure of.

  1. Include the latest version of the Mixpanel iOS library in your app
  2. Make sure you are identifying your users in the app.
  3. Create a survey for your project in the Surveys tab of the Mixpanel website.

The Mixpanel iOS library will automatically check for a survey when your app loads or resumes from the background. If a survey is available for the current user that they haven't already seen, it will be displayed immediately in an overlay view.

That's it, you're done!

Controlling when to show a survey

You may not want the surveys to show immediately when your app loads. If, for example, you have an app like Skype™, and you want to show a call quality survey at the end of a phone call, you need to turn off the automatic showing of surveys, by setting showSurveyOnActive to NO and call showSurveyWithID: at the appropriate point in your app.

// In application:didFinishLaunchingWithOptions:
Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:
    YOUR_MIXPANEL_TOKEN];
//Turn this off so the survey doesn't pop up automatically.
mixpanel.showSurveyOnActive = NO;

- (void)phoneCallEnded
{
    [mixpanel showSurveyWithID:CALL_QUALITY_SURVEY_ID];
}

If you don't want to specify the survey ID, you can use showSurvey instead, which will show the first available survey targeted at the identified user if there is one. Surveys are never shown twice to the same user, so you don't have to check for yourself if the user already saw the survey before calling showSurveyWithID.

If you don't want mixpanel checking for new surveys when your app becomes active, you can turn it off by setting checkForSurveysOnActive to NO. This means that surveys will not show automatically, and that the network request to retrieve the survey will occur only when you call showSurvey or showSurveyWithID:

Debugging and logging

You can turn on Mixpanel logging by adding the following Preprocessor Macros in Build Settings: MIXPANEL_LOG=1 and MIXPANEL_DEBUG=1. Setting MIXPANEL_LOG=1 will cause the Mixpanel library to log tracked events and set People properties. Setting MIXPANEL_DEBUG=1 will cause Mixpanel to log everything it's doing—queuing, formatting and uploading data—in a very fine-grained way, and is useful for understanding how the library works and debugging issues.

About ARC

As of version 2.2.0 the Mixpanel iOS library uses ARC.

If you are using Mixpanel in a project that does not have ARC enabled, you need to enable ARC for just the Mixpanel source files in your Xcode project settings. This is done by adding the -fobj-arc compiler flag to each Mixpanel file under
Build Phases -> Compile Sources

Document Sections
Learn more