Swiftpack.co - Package - mParticle/mparticle-apple-sdk
Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.

mParticle Apple SDK

This is the mParticle Apple SDK for iOS and tvOS.

At mParticle our mission is straightforward: make it really easy for apps and app services to connect and allow you to take ownership of your 1st party data. Like most app owners, you end up implementing and maintaining numerous SDKs ranging from analytics, attribution, push notification, remarketing, monetization, etc. However, embedding multiple 3rd party libraries creates a number of unintended consequences and hidden costs.

The mParticle platform addresses all these problems. We support an ever growing number of integrations with services and SDKs, including developer tools, analytics, attribution, messaging, advertising, and more. mParticle has been designed to be the central hub connecting all these services – read the docs or contact us at support@mparticle.com to learn more.


This document will help you:

  • Install the mParticle SDK using CocoaPods or Carthage
  • Add any desired kits
  • Initialize the mParticle SDK

Get the SDK

The mParticle-Apple-SDK is available via CocoaPods, Carthage or Swift Package Manager. Follow the instructions below based on your preference.


To integrate the SDK using CocoaPods, specify it in your Podfile:

# Uncomment the line below if you're using Swift or would like to use dynamic frameworks (recommended but not required)
# use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 8'

Configuring your Podfile with the statement above will include only the Core mParticle SDK.

If your app targets iOS and tvOS in the same Xcode project, you need to configure the Podfile differently in order to use the SDK with multiple platforms. You can find an example of multi-platform configuration here.

If you'd like to add any kits, you can do so as follows:

# Uncomment the line below if you're using Swift or would like to use dynamic frameworks (recommended but not required)
# use_frameworks!

target '<Your Target>' do
    pod 'mParticle-Appboy', '~> 8'
    pod 'mParticle-BranchMetrics', '~> 8'
    pod 'mParticle-Localytics', '~> 8'

In the cases above, the Appboy, Branch Metrics, and Localytics kits would be integrated together with the core SDK.

Working with Static Libraries

mParticle's iOS SDK and its embedded kits are dynamic libraries, meaning their code is loaded into an app's address space only as needed, as opposed to a 'static' library, which is always included in full in the app's executable file. Some mParticle embedded kits rely on static libraries maintained by our partners. A static framework, wrapped in a dynamic library is incompatible with CocoaPods' use frameworks! option. Affected kits are: Appboy, AppsFlyer, comScore, Kahuna, Kochava, Localytics and Radar.

Attempting to use these kits with use_frameworks! will result in the following error message:

[!] The '<your Target>' target has transitive dependencies that include static binaries: (<path to framework>)

If you need to reference these kits' methods from user-level code, you must incorporate them manually. To do this:

  1. Add the partner SDK (for example, Appboy-iOS-SDK or AppsFlyer-SDK) directly to your Podfile.
  2. Remove the embedded kit pod(mParticle-<partner name>) from the Podfile, download the source code from Github and manually drag its .m and .h files directly into your project.

Crash Reporter

For iOS only, you can also choose to install the crash reporter by including it as a separate pod:

pod 'mParticle-CrashReporter', '~> 1.3'

You can read detailed instructions for including the Crash Reporter at its repository: mParticle-CrashReporter

Note you can't use the crash reporter at the same time as the Apteligent kit.


To integrate the SDK using Carthage, specify it in your Cartfile:

github "mparticle/mparticle-apple-sdk" ~> 8.0

If you'd like to add any kits, you can do so as follows:

github "mparticle-integrations/mparticle-apple-integration-branchmetrics" ~> 8.0

In this case, only the Branch Metrics kit would be integrated; all other kits would be left out.

Swift Package Manager

To integrate the SDK using Swift Package Manager, open your Xcode project and navigate to File > Swift Packages > Add Package Dependency

Enter the repository URL https://github.com/mParticle/mparticle-apple-sdk and click Next.

You can leave the version settings as default and click Next one more time to complete adding the package dependency.

Currently Supported Kits

Several integrations require additional client-side add-on libraries called "kits." Some kits embed other SDKs, others just contain a bit of additional functionality. Kits are designed to feel just like server-side integrations; you enable, disable, filter, sample, and otherwise tweak kits completely from the mParticle platform UI. The Core SDK will detect kits at runtime, but you need to add them as dependencies to your app.

Kit CocoaPods Carthage
Branch Metrics
Google Analytics for Firebase
Reveal Mobile
Urban Airship

Initialize the SDK

The mParticle SDK is initialized by calling the startWithOptions method within the application:didFinishLaunchingWithOptions: delegate call. Preferably the location of the initialization method call should be one of the last statements in the application:didFinishLaunchingWithOptions:. The startWithOptions method requires an options argument containing your key and secret and an initial Identity request.

Note that it is imperative for the SDK to be initialized in the application:didFinishLaunchingWithOptions: method. Other parts of the SDK rely on the UIApplicationDidBecomeActiveNotification notification to function properly. Failing to start the SDK as indicated will impair it. Also, please do not use GCD's dispatch_async to start the SDK.


import mParticle_Apple_SDK

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
       // Override point for customization after application launch.
        let mParticleOptions = MParticleOptions(key: "<<<App Key Here>>>", secret: "<<<App Secret Here>>>")
       //Please see the Identity page for more information on building this object
        let request = MPIdentityApiRequest()
        request.email = "email@example.com"
        mParticleOptions.identifyRequest = request
        mParticleOptions.onIdentifyComplete = { (apiResult, error) in
            NSLog("Identify complete. userId = %@ error = %@", apiResult?.user.userId.stringValue ?? "Null User ID", error?.localizedDescription ?? "No Error Available")
       //Start the SDK
        MParticle.sharedInstance().start(with: mParticleOptions)
       return true


For apps supporting iOS 8 and above, Apple recommends using the import syntax for modules or semantic import. However, if you prefer the traditional CocoaPods and static libraries delivery mechanism, that is fully supported as well.

If you are using mParticle as a framework, your import statement will be as follows:

@import mParticle_Apple_SDK;                // Apple recommended syntax, but requires "Enable Modules (C and Objective-C)" in pbxproj
#import <mParticle_Apple_SDK/mParticle.h>   // Works when modules are not enabled

Otherwise, for CocoaPods without use_frameworks!, you can use either of these statements:

#import <mParticle-Apple-SDK/mParticle.h>
#import "mParticle.h"

Next, you'll need to start the SDK:

- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"REPLACE ME"
                                                                   secret:@"REPLACE ME"];
    //Please see the Identity page for more information on building this object
    MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];
    request.email = @"email@example.com";
    mParticleOptions.identifyRequest = request;
    mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
        NSLog(@"Identify complete. userId = %@ error = %@", apiResult.user.userId, error);
    [[MParticle sharedInstance] startWithOptions:mParticleOptions];
    return YES;

Please see Identity for more information on supplying an MPIdentityApiRequest object during SDK initialization.

Example Project with Sample Code

A sample project is provided with the mParticle Apple SDK. It is a multi-platform video streaming app for both iOS and tvOS.

Clone the repository to your local machine

git clone https://github.com/mParticle/mparticle-apple-sdk.git

In order to run either the iOS or tvOS examples, first install the mParticle Apple SDK via CocoaPods.

  1. Change to the Examples/CocoaPodsExample directory
  2. Run pod install
  3. Open Example.xcworkspace in Xcode, select either the iOS_Example or tvOS_Example scheme, build and run.

Read More

Just by initializing the SDK you'll be set up to track user installs, engagement, and much more. Check out our doc site to learn how to add specific event tracking to your app.


Questions? Have an issue? Read the docs or contact our Customer Success team at support@mparticle.com.


Apache 2.0


Stars: 31


Version 8.1.3 - 2021-01-15T23:52:48

  • Fix MPConnector for MPURL
  • Improve UA for Number Values

This resolves an issue where signature headers could be computed improperly with certain network configuration settings.

Version 8.1.2 - 2021-01-06T19:48:25

This release includes a number of bugfixes:

  • Fix incrementUserAttribute UAC Message
  • Refactor UserAttributes
  • Fix potential DB access on main, add finalize
  • Add MPURL to support custom endpoints and overriding subdirectories

Version 8.1.1 - 2020-12-09T17:55:05

  • Fix Other6 Identity Login Issue This resolves an issue where identity login requests that included certain MPIdentities were always returning a 400 response.

Version 7.16.4 - 2020-12-09T17:28:49

  • Fix Other6 Identity Login Issue This resolves an issue where identity login requests that included certain MPIdentities were always returning a 400 response.

Version 8.1.0 - 2020-11-25T00:06:49

Data Blocking

This release adds support for Data Blocking to Kits!

To enable blocking, ensure you are specifying your data plan ID (and optionally version) in MParticleOptions.

This will enable the SDK to download your data plan and use it to block unplanned data from going to kits based on your blocking settings in the platform.

You can also specify blocking settings locally during SDK init using a new property MPDataPlanOptions on your MParticleOptions object.

If you specify local settings, these will override configuration sent by the server.

Note: the current implementation of blocking does not include validation logic to handle e.g. regex, or min/max keywords.

Session API updates

This release includes changes to improve the timing with which MParticle.sharedInstance.currentSession becomes available after starting the SDK, as well as introducing new APIs for managing sessions.

When starting the SDK, you now have the option shouldBeginSession which allows you to easily start a session on SDK init even if you are using manual session tracking otherwise.

This release also introduces the same logic when you log an event. By default, sessions will be created when logging events, but you can set shouldBeginSession to false on the event to prevent this. In most cases, you will want to ensure shouldBeginSession is false if the SDK is launched into the background from e.g. a content-available push notification.

Other items

Several additional bugfixes are included in this release:

  • Add Action Identifier to Notifications
  • Add String Support For Product Price
  • Update JSON Format of User Attributes
  • Remove Deprecated Cart State from Commerce Event Data
  • Fix Content Available Notification Bug
  • Update MPCustomModulePreference

Note: If you have filters that currently depend on the fact that the SDK was previously encoding boolean values as Y and N, you will need to update those to look for true and false before updating to this version of the SDK, otherwise your filters will not take effect.

Version 8.0.1 - 2020-09-16T19:09:28

Official iOS 14 Support & Xcode 12 Support

This release updates the Core SDK and many kits for iOS 14!

Important behavioral and API changes:

  • The SDK no longer queries for IDFA. You must provide the IDFA to the SDK if desired

  • Introduction of the MPIdentity enum, allowing for both device and user identities to be supplied to the identity API

  • Kits have been updated to use the latest iOS 14 betas of their respective SDKs:

    Partner SDK Apple SDK v7 Apple SDK v8
    Adjust ~> 4.20.0 ~> 4.20
    Airship ~> 12.0 ~> 14.0.0
    AppsFlyer ~> 5.0 ~> 6.0
    Apptentive ~> 5.2 ~> 5.3
    Apptimize ~> 3.0 ~> 3.2
    Branch ~> 0.31.2 ~> 0.35
    Braze ~> 3.20 ~> 3.27
    Crittercism '5.6.7' ~> 5.0
    Leanplum ~> 2.6 ~> 3.0
    Localytics ~> 5.2 ~> 6.0
    Primer '3.2.3' ~> 3.6
  • The above are using wildcard dependencies, see here for how to interpret these: https://guides.cocoapods.org/using/the-podfile.html#specifying-pod-versions

  • If you don't see a kit listed here, it was probably already using a wildcard dependency. It has been released as is, as version 8.0.1, and will automatically pull in the latest version of the partner's SDK.

To learn more, please reference the migration guide.

Version 7.16.3 - 2020-08-28T18:54:52


  • Use modular imports for sqlite3


  • None

Version 8.0.0-beta1 - 2020-08-19T19:36:10

This beta release updates the SDK for iOS 14.

Important behavioral and API changes:

  • The SDK no longer queries for IDFA. You must provide the IDFA to the SDK if desired
  • Introduction of the MPIdentity enum, allowing for both device and user identities to be supplied to the identity API
  • Braze, Branch and AppsFlyer kits have been updated to use the latest iOS 14 betas of their respective SDKs

To learn more, please reference the migration guide.

Version 7.16.2 - 2020-07-01T18:49:43


  • Fix Device Token Format

This resolves an issue on iOS 13 where an invalid device token could be sent.


  • Adobe - Update to Media SDK 1.3.0

Version 7.16.1 - 2020-06-22T19:27:16


  • None


  • AppsFlyer - Update to AppsFlyer SDK 5.4
  • Branch - Make CommerceEvent customAttributes Strings Values Only
  • Clevertap - Update to CleverTap SDK 3.8.0

Version 7.16.0 - 2020-05-26T21:33:12


  • Add other5-10 and phone number identity types


  • Appboy - Add type detection
  • Optimizely - Remove Carthage build phase
  • Branch - Include Custom Attributes for Commerce Events

Version 7.15.11 - 2020-05-06T18:37:55


This release adds support for the new Blueshift kit!


  • AppsFlyer - Update Carthage binary manifest URL

Version 7.15.10 - 2020-04-29T21:13:42


This release fixes a bug in the processing of consent filtering rules in cases when no consent state has been set.


  • Iterable - Integrate Iterable SDK 6.2
  • Appboy - Expose ABKURLDelegate
  • Radar - Update to Radar SDK 3.0

Version 7.15.9 - 2020-04-16T17:03:35


  • Guard against NSNull properties in identity requests
  • Add MPUploadBuilder precautions


  • Adjust - Update Adjust SDK to 4.20.0
  • Appboy - Support ABKURLDelegate
  • Apptimize - Update Apptimize SDK to 3.0
  • Branch - Update docs link, Branch SDK to 0.33.0

Version 7.15.8 - 2020-04-03T13:51:35


  • Fix CocoaPods warning


  • None

Version 7.15.7 - 2020-04-01T15:06:14


  • Add support for Swift Package Manager
  • Cleanup deprecated UIApplication calls


  • Optimizely - Fix constant naming

Version 7.15.6 - 2020-03-05T16:23:11


  • Guard against NSNull values in events from webview


  • Optimizely - Add support for other ids

Version 7.15.5 - 2020-02-26T19:01:17


  • None


  • Appboy - Update transaction attributes
  • Apptentive - Guard against non-product-action commerce events
  • Optimizely - Update to Optimizely Swift SDK

Version 7.15.4 - 2020-02-19T16:48:35


  • Fix bug where session start timestamps included time spent waiting for message queue.


  • Appboy - Fix dob parsing Bug

Version 7.15.3 - 2020-02-12T21:31:10


  • Fix bug where data plan id and version would be sent as zero if not specified


  • None

Version 7.15.2 - 2020-02-06T18:07:44


  • Use default URL path to generate x-mp-signature


  • Kochava - Add support for enhanced deeplinking

Version 7.15.1 - 2020-02-03T21:20:17


This release fixes a critical issue in 7.15.0 where invalid modify requests could be created by the SDK.


  • AppsFlyer - Fix custom attribute being set incorrectly in commerce event

Version 7.15.0 - 2020-01-29T19:35:44


This release introduces support for compliance with the California Consumer Privacy Act (CCPA).


  • Appboy - Respect dob user attribute

Version 7.14.0 - 2020-01-10T17:00:00

This release fixes an issue where kit dependencies on the core SDK were not properly updated by the release automation.

No code changes are included.

Version 7.13.0 - 2020-01-08T20:06:54


This release introduces support for Data Planning!

When initializing the SDK, you can now specify your data plan ID and version in MParticleOptions.

For more details, please see the documentation: https://docs.mparticle.com/guides/data-master/#data-plans


  • Braze - Respect user identification type in kit config
  • AppsFlyer - Update to AppsFlyer to version 5.0.0
  • Branch - Update Branch to version 0.31.2

Version 7.12.7 - 2019-11-26T22:10:53


This release addresses an issue where the SDK might crash when logging commerce events, if certain recently-updated kits that support commerce are included.

In addition, a change has been included that should improve SDK responsiveness and prevent the SDK from inadvertently showing up in unrelated stack traces due to unnecessarily waiting to run on the main queue when processing network responses.


  • Adobe - Update to prevent multiple defined symbol linker error

Version 7.12.6 - 2019-11-14T21:54:37


This release includes a number of targeted bug fixes to the SDK.

  • Set device token on message queue
  • Add handling for webview commerce attributes
  • Exclude config endpoint from upload retry logic
  • Deprecate logCommerceEvent: method--please call logEvent: instead.


  • Adobe - Update for Media SDK beta 3

Version 7.12.5 - 2019-10-31T16:43:49


User Agent Collection

This release resolves an issue where user agent collection may not work correctly for certain app configurations.

This is due to a behavior change by Apple that appears to be isolated to Swift projects, where the application state within didFinishLaunching is set to background instead of inactive.

Also included is a change to allow user agent collection in iOS extensions.


  • None

Version 7.12.4 - 2019-10-30T21:14:55


User Agent Collection

  • This release restores support for automatic collection of browser user agent by the SDK.

  • This release also deprecates the Cart API. The Cart API was originally designed to maintain and hold on to product objects to be appended automatically to Commerce events. Over time we have found it to be better practice for the hosting app to maintain shopping cart state rather than the mParticle SDK. In place of the Cart API, please include all of the applicable product objects with each Commerce event.


  • Updates for iOS 13

Version 7.12.3 - 2019-10-17T15:10:18


  • This release fixes a typo that caused MPEvent attributes to return nil if the deprecated info property was used. Due to our kits not yet having been updated to use the new property name, this was resulting in empty event attributes dictionaries being forwarded to kits.