Swiftpack.co - Package - mixpanel/mixpanel-swift

Mixpanel Swift Library

Build Status Average time to resolve an issue Percentage of issues still open CocoaPods Compatible Carthage compatible Swift Package Manager compatible Apache License Documentation

Table of Contents


Welcome to the official Mixpanel Swift Library

The Mixpanel Swift library for iOS is an open-source project, and we'd love to see your contributions! We'd also love for you to come and work with us! Check out Jobs for details.

If you are using Objective-C, we recommend using our Objective-C Library.

Current supported features

Our master branch and our releases are now on Swift 5.

If you wish to use our Swift 4.2 implementation, please point to the v2.6.1 release. For Swift 4/4.1 implementation, please point to the v2.4.5 release. For Swift 3 implementation, please point to the v2.2.3 release. For Swift 2.3 implementation, please point to the v1.0.1 release.

Our Swift library fully supports all of the Mixpanel features and has full parity with the Objective-C Library.


Swift Package Manager

It requires Xcode 12+ and v2.8.0+ release

Important: we only have support for iOS, for now, if you need integrations for other platforms(tvOS or macOS), please use other integration methods instead

  1. In Xcode, select File > Swift Packages > Add Package Dependency.
  2. Follow the prompts using the URL for this repository and a minimum semantic version of v2.8.0

Check out our swift integration guide » for more info.


Our current release only supports CocoaPods version 1.4.0+

Mixpanel supports CocoaPods for easy installation. To Install, see our swift integration guide »

For iOS, tvOS, macOS, and App Extension integrations:

pod 'Mixpanel-swift'


Mixpanel also 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.

Manual Installation

To help users stay up to date with the latest version of our Swift SDK, we always recommend integrating our SDK via CocoaPods, which simplifies version updates and dependency management. However, there are cases where users can't use CocoaPods. Not to worry, just follow these manual installation steps and you'll be all set.

Step 1: Add as a Submodule

Add Mixpanel as a submodule to your local git repo like so:

git submodule add git@github.com:mixpanel/mixpanel-swift.git

Now the Mixpanel project and its files should be in your project folder!

Step 2: Drag Mixpanel to your project

Drag the Mixpanel.xcodeproj inside your sample project under the main sample project file:

alt text

Step 3: Embed the framework

Select your app .xcodeproj file. Under "General", add the Mixpanel framework as an embedded binary:

alt text

Initializing and Usage


Import Mixpanel into AppDelegate.swift, and initialize Mixpanel within application:didFinishLaunchingWithOptions: alt text

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
    Mixpanel.initialize(token: "MIXPANEL_TOKEN")

You initialize your Mixpanel instance with the token provided to you on mixpanel.com.

Start tracking

After installing the library into your iOS app, Mixpanel will automatically collect common mobile events. You can enable/ disable automatic collection through your project settings.

To interact with the instance and track additional events, you can either use the mixpanel instance given when initializing:

mixpanel.track(event: "Tracked Event!")

or you can directly fetch the instance and use it from the Mixpanel object:

Mixpanel.mainInstance().track(event: "Tracked Event!")

You're done! You've successfully integrated the Mixpanel Swift SDK into your app. To stay up to speed on important SDK releases and updates, star or watch our repository on Github.

Have any questions? Reach out to support@mixpanel.com to speak to someone smart, quickly.

Using Mixpanel Push Notifications

First enable Mixpanel push notifications in your app. Then for Rich Push Notifications, you'll need to integrate your application with the MixpanelNotificationServiceExtension.

Integrating the MixpanelNotificationServiceExtension

The Mixpanel SDK comes with a custom Notification Service Extension used to render rich media, custom action buttons, and track when push notifications are received. To enable these features, you will need to integrate it into your application.

1. Create a new Notification Service Extension Target

Screenshot 2020-02-13 14 45 23 Screenshot 2020-02-13 14 44 38 Screenshot 2020-02-13 14 46 53

2. Add Mixpanel-swift as a dependency

Add the following to the end of your Podfile:

target 'NotificationService' do
  pod 'Mixpanel-swift'

Then run pod install

3. Extend your NotificationService from MixpanelNotificationServiceExtension

Replace the contents of your NotificationService.swift file with the following:

import Mixpanel

class NotificationService: MixpanelNotificationServiceExtension {}

4. Delegate the handling of the notification response to the Mixpanel SDK

In your AppDelegate.swift file, you need to call MixpanelPushNotifications.handleResponse when a push notification response is received:

@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
    if MixpanelPushNotifications.isMixpanelPushNotification(response.notification.request.content) {
        debugPrint("Handling Mixpanel push notification response...")
        MixpanelPushNotifications.handleResponse(response: response, withCompletionHandler: completionHandler)
    } else {
        // not a Mixpanel push notification
        debugPrint("Not a Mixpanel push notification.")

This will make sure the tap actions are appropriately handled (open URL, deeplink, etc) as well as track whether a notification was tapped or dismissed.

5. Run the app and send a test push notification from Mixpanel that includes an image or buttons

That's it! Your app should now be able to receive rich push notifications from Mixpanel.


Stars: 278


Used By

Total: 0


v2.8.0 - Swift Package Manager support - 2020-10-15 20:23:01

Add support for Swift Package Manager

  • https://github.com/mixpanel/mixpanel-swift/pull/411, special thanks to @gsabran @MarcSteven and @JonathanDowning!

Important: v2.8.0 release only supports iOS, if you need integrations for other platforms, please use other integration methods instead, we will add support for all platforms soon

Integration steps:

  1. In Xcode, select File > Swift Packages > Add Package Dependency.
  2. Follow the prompts using the URL for this repository and a minimum semantic version of v2.8.0

v2.7.7 - Remove IFA/IDFA - 2020-08-07 23:27:56

Removing using IFA as distinct id https://github.com/mixpanel/mixpanel-swift/pull/389

Beginning with this version, Mixpanel no longer uses the IFA(ID for Advertisers) but uses a randomly generated UUID as the default distinct ID instead. After you call reset, Mixpanel generates a new distinct_id by default. This ensures that multiple users on the same device are not assigned the same alias.

If you want to use IFV(identifierForVendor) as the distinct_id, you can set MIXPANEL_UNIQUE_DISTINCT_ID=1 in build settings Active Compilation Conditions on the Mixpanel framework target. After you call reset, the IFV will not change. However, when a user removes and then re-installs the app, the IFV will change with each installation.

v2.7.6 - Bug fixes - 2020-07-16 18:13:08

  • Change deployment target to iOS 9 to support Xcode 12 https://github.com/mixpanel/mixpanel-swift/pull/397

  • Concurrency improvement https://github.com/mixpanel/mixpanel-swift/pull/396

v2.7.5 - Bug fixes - 2020-07-14 20:33:42

Convert objc_sync_enter lock to GCD https://github.com/mixpanel/mixpanel-swift/pull/393

v2.7.4 - Bug fixes - 2020-07-07 00:08:02

Fix crash with CTTelephonyNetworkInfo in setCurrentRadio https://github.com/mixpanel/mixpanel-swift/pull/388

v2.7.3 - Bug fixes for flushing large event queues - 2020-05-14 18:55:47

  • fix potential issues with large event queues due to the unstable network and too many events being tracked within a short period of time. https://github.com/mixpanel/mixpanel-swift/pull/373
  • fix bug for sending Bool value as NSNumber, the server should now receive Bool value properly https://github.com/mixpanel/mixpanel-swift/pull/373

v2.7.2 - Bug fixes - 2020-05-07 21:10:29

  • add NSNumber support as a property value type  https://github.com/mixpanel/mixpanel-swift/pull/371
  • add a new public property trackAutomaticEventsEnabled to Mixpanel https://github.com/mixpanel/mixpanel-swift/pull/370
  • fix potential crash from check decide  https://github.com/mixpanel/mixpanel-swift/pull/366
  • Fix deprecated currentRadioAccessTechnology in CTTelephonyNetworkInfo https://github.com/mixpanel/mixpanel-swift/pull/369
  • Fix two minor build warnings for Xcode 11.4b3, thanks @bengottlieb https://github.com/mixpanel/mixpanel-swift/pull/351

v2.7.1 - Several critical bug fixes - 2020-04-24 00:03:26

  • Add support for macOS Catalyst https://github.com/mixpanel/mixpanel-swift/pull/362

  • Fix compile error when decide is off for tracking push notifications https://github.com/mixpanel/mixpanel-swift/pull/363

  • Optimize persistence logic to reduce cpu and memory overhead https://github.com/mixpanel/mixpanel-swift/pull/364 thanks @RamblinWreck77

  • Fix the issue where events not being able to be flushed beyond the batch size. https://github.com/mixpanel/mixpanel-swift/pull/365

v2.7.0 - Rich push notifications and new push tracking events - 2020-02-13 17:13:32

  • Additional support for rich push notifications including a bundled Notification Service Extension for rendering media and buttons https://github.com/mixpanel/mixpanel-swift/pull/340
  • New push notification tracking events: $push_notification_received, $push_notification_tap, $push_notification_dismissed for notifications sent from Mixpanel https://github.com/mixpanel/mixpanel-swift/pull/345

v2.6.11 - Bug fixes - 2020-01-17 21:26:59

Respect checkForVariantsOnActive and checkForNotificationOnActive https://github.com/mixpanel/mixpanel-swift/pull/344

v2.6.10 - Bug fixes - 2020-01-17 19:42:02

  • Fix extension api compile issue https://github.com/mixpanel/mixpanel-swift/pull/341

v2.6.9 - In-app notification fixes for iOS 13 - 2020-01-10 16:06:15

  • Fix mini notification not showing properly in some devices.
  • Fix In-apps not showing up for iOS 13 with Scenes. https://github.com/mixpanel/mixpanel-swift/pull/338

v2.6.8 - Bug fixes - 2020-01-07 01:01:27

Prevent users from seeing duplicate inapps when logging out and back in https://github.com/mixpanel/mixpanel-swift/pull/337

v2.6.7 - bug fixes - 2019-10-23 01:41:03

  • Fix in offline mode some time the events not being archived properly https://github.com/mixpanel/mixpanel-swift/pull/334

  • Crash when deploying to WatchOS 5 from Xcode 11 https://github.com/mixpanel/mixpanel-swift/pull/334

v2.6.6 - Xcode 11 and bug fixes - 2019-10-04 01:13:22

  • Xcode 11 and iOS 13 ready
  • Fix the crash in archiveToFile's NSKeyedArchiver, thanks @RamblinWreck77 https://github.com/mixpanel/mixpanel-swift/pull/330
  • Fix the crash for Mixpanel Logger https://github.com/mixpanel/mixpanel-swift/pull/330

v2.6.5 - bug fixes - 2019-08-23 07:19:24

Fix duplicate triggered inapps shown between app sessions https://github.com/mixpanel/mixpanel-swift/pull/324

v2.6.4 - race condition bug fixes - 2019-08-19 07:50:29

PR: https://github.com/mixpanel/mixpanel-swift/pull/322

  • Crash with Set.contains(_:) https://github.com/mixpanel/mixpanel-swift/issues/321
  • MixpanelInstance.checkDecide crash https://github.com/mixpanel/mixpanel-swift/issues/312
  • Crash in Persistence https://github.com/mixpanel/mixpanel-swift/issues/310
  • Bad Access in Global Lock https://github.com/mixpanel/mixpanel-swift/issues/309

PR: https://github.com/mixpanel/mixpanel-swift/pull/317 Thanks @RamblinWreck77 !

  • Crash in Network.swift https://github.com/mixpanel/mixpanel-swift/issues/314

PR: https://github.com/mixpanel/mixpanel-swift/pull/305

  • A/B Developer tweaks won't update https://github.com/mixpanel/mixpanel-swift/issues/302

v2.6.3 - Improved identity management support and bug fixes - 2019-06-07 07:15:44

mixpanel.identify() now sends a special $identify event to the API. This is not treated like a regular tracking event, but will aid in future platform improvements to support advanced identity management (linking anonymous and logged-in usage, multiple users on one system, etc.).

if more than one user can be identified in your app (ie log-out/log-in scenarios) make sure you call reset() when a user logs-out and that you add MIXPANEL_RANDOM_DISTINCT_ID Active Complilation Conditions in your build settings so anonymous users don't have the same distinct_id (IFA/IFV by default) https://github.com/mixpanel/mixpanel-swift/pull/306

fix a potential crash issue by fetching the current super properties https://github.com/mixpanel/mixpanel-swift/pull/304

fix deadlock in readwrite lock https://github.com/mixpanel/mixpanel-swift/pull/307 thanks @RamblinWreck77

Missing case in makeObjectSerializable() : NaN or infinity cannot be serialized as JSON https://github.com/mixpanel/mixpanel-swift/pull/303 thanks @tonysung

Prefix swizzled method name https://github.com/mixpanel/mixpanel-swift/pull/289 thanks @ChrisGriffiths

v2.6.2 - Xcode 10.2 and swift 5 support - 2019-04-01 19:03:03

  • Xcode 10.2 and swift 5 support https://github.com/mixpanel/mixpanel-swift/pull/296

v2.6.1 - Bug fixes - 2019-03-28 18:55:37

  • Include super properties during display trigger evaluation
  • Fix bug while comparing string types https://github.com/mixpanel/mixpanel-swift/pull/291

v2.6.0 - Apple Watch Support and Automatic Events for Apple TV - 2019-03-26 08:04:06

  • Add Apple watch support

  • Enable automatically track common mobile events($ae_session, $ae_updated, $ae_first_open) for Apple TV. to turn it off, please remove the TV_AUTO_EVENTS flag in Active Compilation Conditions in build settings. image More details about Default Mobile Events Collection: https://help.mixpanel.com/hc/en-us/articles/115004596186-Default-Mobile-Events-Collection

  • GDPR fix: Change the default behavior for setting optOutTrackingByDefault in the Mixpanel initialization method. We will not override opt out persistence with optOutTrackingByDefault the flag since opt-out default state is supposed to be used as an initial state while GDPR information is being collected https://github.com/mixpanel/mixpanel-swift/pull/290

v2.5.9 - Support for account-level analytics - 2019-03-22 08:39:14

New Features

  • Set, add, and remove groups the user belongs to.
  • Track events with specific groups
  • Support for group-level profiles—set, update, and remove properties on account/group objects in Mixpanel
  • Allow to remove All device push tokens, thanks @asiliuk for providing this PR https://github.com/mixpanel/mixpanel-swift/pull/288

Bug fix

  • Fix EXC_BAD_ACCESS crash in background thread and a complete audit for async dispatch, special thanks to @RamblinWreck77 for providing this PR https://github.com/mixpanel/mixpanel-swift/pull/285

v2.5.8 - Event triggered in-app notifications support - 2019-03-15 00:04:59

  • Add the feature: Event triggered in-app notifications support

Currently users have no control over when an in-app notification shows up. With this release users can now control when an in-app gets displayed based on an event that they track within their app. This "trigger" event is defined during message creation at www.mixpanel.com.

You can additionally filter the event based on properties that are tracked along with the event for even finer controls. https://github.com/mixpanel/mixpanel-swift/pull/287

v2.5.7 - Bug fixes - 2019-01-25 22:42:38

  • Store total app sessions, total app session length and first app open date as user properties, parity with ObjC https://github.com/mixpanel/mixpanel-swift/pull/283

  • Add NSString as MixpanelType thanks @eXhausted https://github.com/mixpanel/mixpanel-swift/pull/265

  • Fix crashes https://github.com/mixpanel/mixpanel-swift/pull/282 thanks @RamblinWreck77 https://github.com/mixpanel/mixpanel-swift/pull/273 thanks @drfindley https://github.com/mixpanel/mixpanel-swift/pull/188 thanks @kevinchau

  • Optimize .reduce usage on Array, thanks @asiliuk https://github.com/mixpanel/mixpanel-swift/pull/281

v2.5.6 - Bug fixes - 2019-01-11 23:55:11

  • Pass flag to backend indicating when $distinct_id might have been set to a pre-existing $distinct_id value instead of a generated UUID (used when resolving aliases) https://github.com/mixpanel/mixpanel-swift/pull/276

v2.5.5 - Bug fixes - 2018-11-07 03:59:55

  • Fix the issue where in some rare cases events could potentially be sent more than once. https://github.com/mixpanel/mixpanel-swift/pull/264

v2.5.4 - Send device_id and user_id with event/people updates - 2018-10-19 18:56:39

  • Events will have properties $user_id which is identified user and $device_id which is how anonymous events are tracked as before identify was called. https://github.com/mixpanel/mixpanel-swift/pull/262

  • People updates will also contain fields $user_id and $device_id. https://github.com/mixpanel/mixpanel-swift/pull/262

v2.5.3 - Bug fixes - 2018-10-14 19:12:00

  • Fix codeless tracking not able to track UITextField in iOS 12 https://github.com/mixpanel/mixpanel-swift/pull/260

  • Unset VALID_ARCH setting, thanks @krbarnes https://github.com/mixpanel/mixpanel-swift/pull/258

  • Remove collectionName and groupName from Tweak init public params, they are not meant to be exposed https://github.com/mixpanel/mixpanel-swift/pull/261

  • Enable an Active Compilation Condition NO_AB_TESTING_EDITOR to disable ab testing web editor support(disable gesture recognizer) explicitly. Otherwise, it is enabled by default. https://github.com/mixpanel/mixpanel-swift/pull/260

v2.5.2 - Bug fix - 2018-10-08 16:13:46

  • Fix crash on tapping notification when built by Xcode 10 (Thanks @squarelab-jwlee) ! https://github.com/mixpanel/mixpanel-swift/pull/256

v2.5.1 - Bug fixes - 2018-10-08 05:41:03

  • Fix notification tracking crash related to @noescape, thanks @Macmee
  • Fix OSAtomicAdd32 deprecated warning in iOS 10 https://github.com/mixpanel/mixpanel-swift/pull/253/