Mixpanel SDKs: iOS (Swift)

Getting Started

The Full API Reference, Library Source Code, and an Example Application is documented in our GitHub repo.

Installing the Library

You can install the Swift library by using CocoaPods, Carthage, or Swift Package Manager.

Install CocoaPods by typing the following in your command line:

# install CocoaPods
gem install cocoapods

After install CocoaPods, create a local CocoaPods spec mirror by running the following:

# Create CocoaPods spec mirror
pod setup

Then navigate to your Xcode project directory and create a Podfile by running the following:

# create Podfile in project directory
pod init

Open the Podfile that was generated and add the Mixpanel library to your dependencies:

target 'MyApp' do
  pod 'Mixpanel-swift'
end

Install the Mixpanel library and create a new Xcode workspace by running the following in the Xcode project directory:

// install library in your dependencies
pod install

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

# add Mixpanel library to your dependencies
github "mixpanel/mixpanel-swift"

After installing the library, import Mixpanel into AppDelegate.swift and initialize Mixpanel within application:didFinishLaunchingWithOptions: using your project token.

/// import Mixpanel class from the library
import Mixpanel
 
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    ...
    /// initialize Mixpanel using your project token
    Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", 
        trackAutomaticEvents: false
        )
    ...
}

Library Configuration

The Mixpanel instance can be customized with different configurations. The .initialize() method accepts arguments that sets some configurations on your instance upon initialization.

After initialization, you can further customize the instance using the configuration options here.

Example Usage

/// import Mixpanel class from the library
import Mixpanel
 
func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    ...
    /// set instance name to "currentInstance" at initialization
    Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN",
        trackAutomaticEvents: false,
        instanceName: "currentInstance"
        )
 
    //enable debug log after initialization
    Mixpanel.mainInstance().loggingEnabled = true
    ...
}

Sending Events

Use .track(event:properties:) to send an event by providing the event name and any event properties. This will trigger a request to the /track API endpoint to ingest the event into your project.

The /track endpoint will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.

Example Usage

/// track "some_event" 
/// with "plan" event prop set to "Premium"
Mixpanel.mainInstance().track(event: "some_event",
    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.

/// start the timer for the event "Image Upload"
Mixpanel.mainInstance().time(event: "Image Upload")
 
/// 20 seconds later...
 
/// track "Image Upload" event with "Duration" event prop set to 20
Mixpanel.mainInstance().track(event: "Image Upload")

Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn’t send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call .flush() manually if you want to force a flush at a particular moment.

Example Usage

/// flush batched events for ingestion immediately
Mixpanel.mainInstance().flush()

Flush Interval

You can update the default flush interval from 60 seconds to another interval using flushInterval.

Example Usage

/// set the flush interval to every 120 seconds
Mixpanel.mainInstance().flushInterval = 120

Importing Historical Events

The Swift SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling .track(event:properties:) triggers a request to our /track API endpoint, which will validate for events with a timestamp that is within the last 5 days of the request. Events older than 5 days will not be ingested.

For bulk import of historical events older than 5 days, we will need to use the /import API endpoint which is optimized for scripting and supports ingesting historical data. We recommend the Python SDK (see the .import_data() function) and mixpanel-utils module (see the import_events() function) which both leverages the /import API for event ingestion.

Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

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

Use .registerSuperPropertiesOnce(_:) to register super properties without overwriting existing values.

Example Usage

/// register a "name" super property
Mixpanel.mainInstance().registerSuperProperties(["name": "Sam"])
 
/// track "some_event"
/// "name" is automatically added as an event prop
Mixpanel.mainInstance().track(event: "some_event")
 
// this is ignored because "name" already exists
Mixpanel.mainInstance().registerSuperPropertiesOnce(["name": "Samantha"])
 
/// register a "location" super property
Mixpanel.mainInstance().registerSuperPropertiesOnce(["location": "us"])

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

See more methods related to super properties in the complete library reference here.

Managing User Identity

You can handle the identity of a user using the .identify() and .reset() methods. Learn more about identity management and identifying users.

Identify

⚠️

We recommend against calling .identify() for anonymous visitors to your site.

Call .identify() when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

/// your user signs in and tracks a sign in event
Mixpanel.mainInstance().track(event: "sign in")
 
/// upon sign in, identify the user with their ID
/// ensure future events sent from the user have distinct_id 12345
Mixpanel.mainInstance().identify(distinctId: "12345");

Call Reset on Logout

Call .reset() to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle multiple users on a single device.

Example Usage

/// your user signs out and tracks a log out event
Mixpanel.mainInstance().track(event: "log out")
 
/// upon logout, call reset to clear local storage
/// new distinct_id is generated for events moving forward
Mixpanel.mainInstance().reset()

Since v2.7.7, Mixpanel stopped using the IFA(ID for Advertisers) as a distinct_id, meaning calls to reset will generate a new random UUID.

If you want to use IFV(identifierForVendor) as the distinct_id, you can set MIXPANEL_UNIQUE_DISTINCT_ID in build settings Active Compilation Conditions on the Mixpanel framework target. The IFV will not change when you call reset, but will change upon app uninstalls/reinstalls.

Storing User Profiles

Once your users are identified, create user profiles by setting profile properties to describe them. Example profile properties include “name”, “email”, “company”, and any other demographic details about the user.

The Swift SDK provides a few methods for setting profile properties under the People class accessible via .people(). These methods will trigger requests to the /engage API endpoint.

Setting Profile Properties

You must call .identify() before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.

You can set properties on a user profile with people.set(property:to:).

If a profile property already exist, if will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

Example Usage

/// You must call identify to associate the profile update with the user
Mixpanel.mainInstance().identify(distinctId: "12345")
 
/// Set user's "Plan" profile prop to "Premium"
Mixpanel.mainInstance().people.set(properties: ["plan":"Premium", "$email":"joe.doe@example.com"])
 
/// Update "plan" to "Enterprise"
Mixpanel.mainInstance().people.set(properties: ["plan":"Enterprise"])

Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods here

A few commonly used people methods are highlighted below:

The setOnce(properties:) method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set profile properties without the risk of overwriting existing data.

Example Usage

/// set profile properties for user "12345"
Mixpanel.mainInstance().identify(distinctId: "12345")
Mixpanel.mainInstance().people.set(properties: ["name":"Sam"])
 
/// will be ignored since "name" already exists
Mixpanel.mainInstance().people.setOnce(properties: ["name":"Samantha"])
 
/// set "location" property since it does not exist
Mixpanel.mainInstance().people.setOnce(properties: ["location":"us"])

The append(properties:) method append values to a list profile property.

Use this method to add additional values to an existing list property instead of redefining the entire list.

Example Usage

/// set profile properties for user "12345"
Mixpanel.mainInstance().identify(distinctId: "12345")
Mixpanel.mainInstance().people.set(properties: [
    "roles":["sales","engineer"]
    ])
 
 
/// add "legal" to "roles"
/// new "roles" values are ['sales','engineer','legal']
Mixpanel.mainInstance().people.append(properties: [
    "roles":"legal"
    ])
 
/// append() allows duplicates
// new "roles" values are ['sales','engineer','legal','legal']
Mixpanel.mainInstance().people.append(properties: [
    "roles":"legal"
    ])

The union(properties:) method append new values to a list property, excluding duplicates.

Use this method to create a list profile property that only contains unique values without duplicates.

Example Usage

/// set profile properties for user "12345"
Mixpanel.mainInstance().identify(distinctId: "12345")
Mixpanel.mainInstance().people.set(properties: [
    "roles":["sales","engineer"]
    ])
 
/// will be ignored since "engineer" already exists in "roles"
Mixpanel.mainInstance().people.union(properties: [
    "roles":"engineer"
    ])
 
/// add "legal" to "roles"
/// "roles" = ['sales','engineer','engineer']
Mixpanel.mainInstance().people.union(properties: [
    "roles":"legal"
    ])

The increment(property:by:) method increments a numeric property by a whole number.

Use this method to add to or subtract from your numeric property based on its current value.

Example Usage

/// set profile properties for user "12345"
Mixpanel.mainInstance().identify(distinctId: "12345")
Mixpanel.mainInstance().people.set(properties: ["age":25])
 
/// increment "age" by 2
Mixpanel.mainInstance().people.increment(property: "age", by: 2)
 
/// use negative number to decrement
/// decrement "age" by 5
Mixpanel.mainInstance().people.increment(property: "age", by: -5)

Group Analytics

Read more about Group Analytics before proceeding. You will need to have the group key defined in your project settings first.

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the group_key and group_id.

group_key is the event property that connects event data to a group. (e.g. company)
group_id is the identifier for a specific group. (e.g. mixpanel,company_a,company_b, etc.)

The Swift SDK provides a few method for adding individual users to a group and setting group profile properties.

Adding Users to a Group

All events must have the group key as an event property in order to be attributed to a group. Without the group key, an event cannot be attributed to a group.

Call the setGroup(groupKey:groupIDs:) to register the current user to a group, which would add the group_key as an event property set to the group_id value to all events moving forward.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// track "some_event"
/// event prop "company" = ["mixpanel"] is added automatically
Mixpanel.mainInstance().track(event: "some_event")
 
 
/// alternatively you can define the group key manually
Mixpanel.mainInstance().track(event: "some_event", properties: [
    "company": ["mixpanel"]])

Multiple Groups

An event can be attributed to multiple groups by passing in the group_key value as a list of multiple group_id values.

Call addGroup(groupKey:groupID:) to add additional group_ids to an existing group key property.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// add "mp-us" as an additional company group
Mixpanel.mainInstance().addGroup(groupKey: "company", groupID: "mp-us")
 
/// track "some_event"
/// event prop "company" = ["mixpanel","mp-us"] is added automatically
Mixpanel.mainInstance().track(event: "some_event")

Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the group_key and group_id as a user profile property using the .people.set() call.

Example Usage

/// You must call identify to associate the profile update with the user
Mixpanel.mainInstance().identify(distinctId: "12345")
 
/// set group key "company" as a user prop
/// with group id "mixpanel" as value
Mixpanel.mainInstance().people.set(properties: ["company":"mixpanel", "$email":"joe.doe@example.com"])

Setting Group Profile Properties

Create a group profiles by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as “ARR”, “employee_count”, and “subscription”.

To set group profile properties, specify the group that needs to be updated by calling getGroup(groupKey:groupID:), then set the group properties by chaining the set(properties:) method, which will trigger a request to the /groups API endpoint.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// specify the target group using the group_key and group_id using getGroup()
/// set "industry" as a group profile prop to "analytics" using set()
Mixpanel.mainInstance().getGroup(groupKey: "Company", groupID: “mixpanel”).set(properties: [
    "industry": "analytics"
])

Other Group Profile Methods

See all of the methods under the MixpanelGroup class here.

A few commonly used group methods are highlighted below:

The setOnce(properties:) method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set group profile properties without the risk of overwriting existing data.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// set group profile properties
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
    "name": "Mixpanel"])
 
/// ignored since "name" is already exists
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).setOnce(properties: [
    "name": "mp"])
 
/// set "country" group prop since it does not exist
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).setOnce(properties: [
    "country": "us"])

The unset(property:) method removes a group property from a group profile.

Use this method to delete unwanted group profile properties from a specific group profile.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// set group profile properties
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
    "name": "Mixpanel",
    "employee_count": 100
])
 
/// delete "employee_count" from the group profile
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).unset(properties: "employee_count")
 
/// The group only has the "name" property remaining

The union(key:values:) method append new values to a list property, excluding duplicates.

Use this method to create a list profile property that only contains unique values without duplicates.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// set group profile properties
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
    "name": "Mixpanel",
    "features": ["reports","alerts","cohorts"]
])
 
/// add "data pipeline" to "features" prop
/// ignore "alert" since it is a duplicate value
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).union(key: "features",
    values: ["data pipeline","alerts"])

The remove(key:value:) method removes a value from a list-valued group profile property.

Use this method to remove specific values from a list without affecting all of the other values in the list.

Example Usage

/// assign the current user to the "mixpanel" company group
Mixpanel.mainInstance().setGroup(groupKey: "company", groupID: ["mixpanel"])
 
/// set group profile properties
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).set(properties: [
    "name": "Mixpanel",
    "features": ["reports","alerts","cohorts"]
])
 
/// remove "alerts" from "features"
Mixpanel.mainInstance().getGroup(groupKey: "company", groupID: “mixpanel”).remove(
    key: "features", value: "alerts")
 
/// "features" = ["reports","cohorts"]

Debugging and Logging

Enable debug mode by setting the loggingEnabled configuration to true.

Example Usage

/// enable debug log
Mixpanel.mainInstance().loggingEnabled = true

Learn more about debugging.

Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Swift SDK provide methods to help you protect user data.

Learn more about Privacy.

Opt Out of Tracking

The Swift SDK is initialized with tracking enabled by default. Use the optOutTracking() method to opt the user out of data tracking and local storage for the current Mixpanel instance.

Example Usage

/// send "some_event"
Mixpanel.mainInstance().track(event: "some_event")
 
/// opt user out of tracking
/// SDK is prevented from sending any data
Mixpanel.mainInstance().optOutTracking()
 
/// this track call will not work
Mixpanel.mainInstance().track(event: "some_event")

Opt Out by Default

You can initialize the library with users opted out of tracking by default using the optOutTrackingByDefault configuration in initialize(). Once the user is ready to be tracked, call optInTracking() to start tracking.

Example Usage

/// create Mixpanel instance with users opt out of tracking by default
/// SDK is prevented from sending data
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN", 
    outOutTrackingByDefault: true)
 
/// this track call will not work
Mixpanel.mainInstance().track(event: "some_event")
 
///opt user into tracking
Mixpanel.mainInstance().optInTracking()
 
/// send "some_event"
Mixpanel.mainInstance().track(event: "some_event")

EU Data Residency

Route data to Mixpanel’s EU servers by setting the serverURL property after initializing the client.

Example Usage

/// initialize Mixpanel
Mixpanel.initialize(token: "MIXPANEL_TOKEN")
 
/// Set request URL to Mixpanel's EU domain
Mixpanel.mainInstance().serverURL = "https://api-eu.mixpanel.com"

India Data Residency

Route data to Mixpanel’s India servers by setting the serverURL property after initializing the client.

Example Usage

/// initialize Mixpanel
Mixpanel.initialize(token: "MIXPANEL_TOKEN")
 
/// Set request URL to Mixpanel's India domain
Mixpanel.mainInstance().serverURL = "https://api-in.mixpanel.com"

Disable Geolocation

The Swift SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, set the useIPAddressForGeoLocation flag to false.

Example Usage

/// initialize Mixpanel
Mixpanel.initialize(token: "MIXPANEL_TOKEN")
 
/// Set request URL to Mixpanel's EU domain
Mixpanel.mainInstance().useIPAddressForGeoLocation = false

Legacy Automatically Tracked Events

Mixpanel’s SDKs have a legacy feature to automatically collect common mobile events. We don’t recommend enabling this, as these events rely on client-side state and can be unreliable.

Ensure autotracked mobile events are disabled by setting trackAutomaticEvents to false during initialization.

Example Usage

// initialize Mixpanel with autotrack disabled
Mixpanel.initialize(token: "YOUR_PROJECT_TOKEN",
        trackAutomaticEvents: false,)

Raw Name	Display Name	Description
$ae_first_open	First App Open	Tracks the first time the user has opened the app. This event is retriggered if the user reinstalls the app or clears local storage. A user property First App Open Date (`$ae_first_app_open_date`) is tracked to indicate the date when app was first opened.
$ae_updated	App Updated	Executes when a user updates the app from the previous version. A Version Updated (`$ae_updated_version`) property is tracked to store the new app version.
$ae_session	App Session	Executes when a user spends more than 10 seconds in the app. A Session Length (`$ae_session_length`) property is tracked to reflect the number of seconds user spent in the session. In addition, there are two user properties tracked: Total App Sessions (`$ae_total_app_sessions`) and Total App Session Length (`$ae_total_app_session_length`).
$ae_iap	In App Purchase (IAP)	Executes when a user conducts an in-app purchase through your app. Mixpanel provides three properties for this event: Product Name (`$ae_iap_name`), Product Quantity (`$ae_iap_quantity`), and Product Price (`$ae_iap_price`).

Release History

See All Releases.

iOS (Objective-C)Flutter

Was this page useful?