iOS - Swift 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. If this is your first time using CocoaPods, run pod setup to create a local CocoaPods spec mirror.
  3. Create a file in your Xcode project called Podfile and add the following line: pod 'Mixpanel-swift'
  4. 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.


Mixpanel supports Carthage to package your dependencies as a framework. Include the following dependency in your Cartfile:

 github "mixpanel/mixpanel-swift"

Check out the Carthage docs for more info.

You can also get the library by downloading the latest version from Github and copying it into your project. We have step-by-step instructions on how to manually install our library.

Initializing the library

To start tracking with the Mixpanel Swift library, you must first initialize it with your project token. Find your project token by clicking your name in the upper righthand corner of your Mixpanel project and selecting Settings from the dropdown.

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

To initialize the library, first add import Mixpanel and call Mixpanel.initialize(token:) with your project token as its argument. Once you've called this method, you can access your instance throughout the rest of your application with mainInstance().

Mixpanel.initialize(token: "MIXPANEL_TOKEN")

Automatically track events

After installing the library into your iOS app, Mixpanel allows you to use our in-browser editor to add tracking on the fly. No code or app-store re-submission$

Navigate to our editor by clicking your name in the upper righthand corner of your Mixpanel project and selecting Set up tracking from the dropdown.

Watch this short video to learn more about automatic event tracking.

Sending events

We recommend tracking only five to seven events in your application instead of tracking too many things to start. Ideally, you track people going through your initial user experience and one key metric that matters for your application (e.g. YouTube might choose "Watched Video" as a key metric).

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

Mixpanel.mainInstance().track(event: "Plan Selected",
        		properties: ["Plan" : "Premium"])

Timing events

You can track the time it took for an action to occur, such as an image upload or a comment post, using time(event:) This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

Mixpanel.mainInstance().time(event: "Image Upload")
//...some time later
Mixpanel.mainInstance().track(event: "Image Upload")

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. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties here.

To set super properties, call registerSuperProperties(_:).

// Send a "Plan: Mega" property will be sent
// with all future track calls.
Mixpanel.mainInstance().registerSuperProperties(["Plan": "Mega"])

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

Mixpanel.mainInstance().track(event: "Signup",
	properties:["Source": "Twitter"])

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

Mixpanel.mainInstance().track(event: "Signup",
	properties:[ "Plan" : "Mega", "Source": "Twitter"])

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(_:defaultValue:). This function behaves like registerSuperProperties(_:) and has the same interface, but it doesn't override super properties you've already saved.

Mixpanel.mainInstance().registerSuperPropertiesOnce(["Source": "ad-01"])

This means that it's safe to call registerSuperPropertiesOnce(_:defaultValue:) 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(distinctId:).

// Associate all future events sent from
// the library with the distinct_id 13793
Mixpanel.mainInstance().identify(distinctId: "13793")

Calling identify(distinctId:) with a new ID will change the ID being sent with future 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(_:distinctId), which sends an update to our server linking the current ID with a new ID.

let mixpanel = Mixpanel.mainInstance()
// This makes the current ID (an auto-generated GUID)
// and '13793' interchangeable distinct ids.
	distinctId: mixpanel.distinctId);
// You must call identify if you haven't already
// (e.g., when your app launches).
mixpanel.identify(distinctId: mixpanel.distinctId)

The recommended usage pattern is to call both createAlias(_:distinctId) and identify(distinctId:) (with the Mixpanel generated distinctId, as shown in the example above) when the user signs up, and only identify(distinctId:) (with the aliased user ID) on future log ins. This will keep your signup funnels working correctly.

If you use createAlias(_:distinctId), 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(distinctId:). 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(property:to:).

// Sets user 13793's "Plan" attribute to "Premium"
Mixpanel.mainInstance().people.set(property: "Plan", 
	to: "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(property:by:) 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.mainInstance().people.increment(property: "point count",
	by: 500)

// Pass an NSDictionary to increment multiple properties
	["dollars spent": 17, "credits remaining": -34])

Other types of profile updates

There are a few other types of profile updates. To learn more, please review the full MixpanelPeople 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(amount:). This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

// Tracks $100.77 in revenue for user 13793
Mixpanel.mainInstance().people.trackCharge(amount: 100.77)

// Refund this user 50 dollars
Mixpanel.mainInstance().people.trackCharge(amount: -50)

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(_:)

func application(application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: NSData) {
	// This sends the deviceToken to Mixpanel
	let mixpanel = Mixpanel.mainInstance()

Push notifications quick start guides

There is a step by step guide to integrating Mixpanel Push notifications with your app available to help you get started with push notifications in your app. It includes instructions for provisioning your app to use the Apple Push Notification service (APNs), preparing your push SSL certificate from Apple and configuring your app for push notifications using Mixpanel.

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 Swift 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.

A/B testing experiments


Getting started with A/B testing is quick and easy. Just include the latest version of the Mixpanel iOS library in your app and you are ready to start experimenting.

Make sure that you have already:

  1. Included the latest version of the Mixpanel Swift library in your app (v2.1+)
  2. Created an experiment on the A/B Testing tab of the Mixpanel website

To use the UI's visual experiment creator, please ensure that you're in the project appropriate to your app's current build (i.e., Production or Development). While not required, it's a good idea to connect your mobile device to WiFi while using the A/B designer.

Once you have created an experiment and, optionally, decided which users you wish to target, simply turn on the experiment to start serving your A/B test to customers. It is that simple!

Planning to run an experiment on the initial view of your app? It can take several seconds for experiments to be applied on first app open; as a result, we recommend against putting UX changes or developer Tweaks on the first view of your app. If you wish to A/B test on the initial app view you will need to take delivery latency into account. We recommend enabling the option checkForVariantsOnActive (to grab data when the app is opened) and joinExperiments(callback:) method (to apply the variant data to the view).

Notes on experiment delivery

Mixpanel checks for any new experiments asynchronously on applicationDidBecomeActive. After the response is received, experiment changes and Tweaks are applied or removed where appropriate. To handle network availability, each experiment is cached on the device so they can be re-applied when the API call cannot be successfully made.

If you'd like more control over when this check for new experiments occurs, you can use the checkForVariantsOnActive flag and the joinExperiments(callback:) method to download and apply experiments manually.

The $experiment_started event is fired when a given experiment (both changes and/or Tweaks) is first started on a device. The event will contain an $experiment_id property with the given experiment id which we encourage use within funnels, and our other reports.

A/B developer tweaks

For more complex changes that you want to A/B test, you can include small bits of code in your apps called Tweaks. Tweaks allow you to control variables in your app from your Mixpanel dashboard. For example, you can alter the difficulty of a game, choose different paths through the app, or change text. The possibilities are endless.

To use Tweaks in Swift you will initially need to define your Tweaks by extending the class MixpanelTweaks and then setting the Tweaks in the SDK. As an example here we are extending MixpanelTweaks and defining a few Tweaks of different types:

extension MixpanelTweaks {
    public static let floatTweak = 
      Tweak(tweakName: "floatTweak", 
            defaultValue: 20.5, min: 0, max: 30.1)
    public static let intTweak = 
      Tweak(tweakName: "intTweak", 
            defaultValue: 10, min: 0)
    public static let boolTweak = 
      Tweak(tweakName: "boolTweak", 
            defaultValue: true)
    public static let stringTweak = 
      Tweak(tweakName: "stringTweak", 
            defaultValue: "hello")
And then right after initializing the Mixpanel Library with the project token, we set the Tweaks (it makes sense to do this in application(_:didFinishLaunchingWithOptions:))

 Mixpanel.initialize(token: "MIXPANEL_TOKEN")
 let allTweaks: [TweakClusterType] = 
 MixpanelTweaks.setTweaks(tweaks: allTweaks) 

Value Tweaks

A value Tweak allows you to assign a value to a variable that can be changed later. The simplest Tweak looks like this:
let numLives = MixpanelTweaks.assign(

and we define it like so:

extension MixpanelTweaks {
    public static let numberOfLives =
      Tweak(tweakName: "number of lives",
            defaultValue: 5)
Once you add this line, you will see a Tweak called number of lives with a default value of 5 in the Mixpanel A/B test designer. You can then create an A/B test with a different value for number of lives. For example, you could set up an experiment where 50% of your users start a game with 5 lives, and 50% start with 10 lives. When the experiment is not running, the value of numLives will simply be the default of 5.

Flow Control Tweaks

Value Tweaks can also be used to control flow in your app.
if MixpanelTweaks.assign(MixpanelTweaks.showAlterateView) {
     // Show alternate view.
 } else {
     // Show original view

and we define it like so:

extension MixpanelTweaks {
    public static let showAlternateView =
      Tweak(tweakName: "show alternate view",
            defaultValue: false)
By default, the alternate view will not show. But you can now set up an A/B test that flips this value to true for a percentage of your users.

If you have more than 2 options, you could use a switch.

switch MixpanelTweaks.assign(MixpanelTweaks.actionToTake) {
     case 1:
         // Do something
     case 2:
         // Do something else
     case 3:
         // Do a third thing

and we define it like so:

extension MixpanelTweaks {
     public static let actionToTake =
       Tweak(tweakName: "action to take",
             defaultValue: 1)
You can use Tweaks to assign values to UI elements too.
let label = UILabel()
label.text = MixpanelTweaks.assign(MixpanelTweaks.labelText)
label.hidden = MixpanelTweaks.assign(MixpanelTweaks.labelHidden))
and we define it like so:
extension MixpanelTweaks {
    public static let actionToTake =
      Tweak(tweakName: "text label",
            defaultValue: "Hello World")
    public static let actionToTake =
      Tweak(tweakName: "text hidden",
            defaultValue: false)

Binding Tweaks

When designing an A/B test in Mixpanel, MixpanelTweaks.assign changes will only apply when the code block they are in is executed. For example if you have an MixpanelTweaks.assign to assign text to a label on viewDidLoad, and you made changes to the Tweak in the A/B test designer, you would not see the changes apply until the next time viewDidLoad was called. If you would like to see your changes applied immediately when designing a test, you can use MixpanelTweaks.bind to accomplish this.

let label = UILabel()
  binding: { label.text = $0 })

and we define it like so:

extension MixpanelTweaks {
    public static let labelText =
      Tweak(tweakName: "text label",
            defaultValue: "Hello World")
Whenever the Tweak is changed in the A/B test designer, you will immediately see the new value of the Tweak applied to the given object and property, in this case label.text.

Multiple Instances

If you want to use multiple Mixpanel projects in your app, you can initialize multiple times using different tokens and interact with each instance separately

let mixpanel1 = Mixpanel.initialize(token: "MIXPANEL_TOKEN1") 
let mixpanel2 = Mixpanel.initialize(token: "MIXPANEL_TOKEN2")
You can also give each instance a different name:

Mixpanel.initialize(token: "MIXPANEL_TOKEN1", launchOptions: nil, flushInterval: 60, instanceName: "Project1")
Mixpanel.initialize(token: "MIXPANEL_TOKEN2", launchOptions: nil, flushInterval: 60, instanceName: "Project2")
Then interact with each Mixpanel instance by its name:

Mixpanel.getInstance(name: "Project1").track(event: "Tracked Event!")
(The mainInstance() is always the last instance that is initialized, and can be configured using setMainInstance(name:))

Additional Features

Mixpanel Mobile Surveys are deprecating in March 2017 and are no longer supported.

Surveys are not supported at this time, but are available in our Objective-C Library.