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.

Overview

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.

CocoaPods

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

target '<Your Target>' do
    pod 'mParticle-Apple-SDK', '~> 8'
    
    # If you'd like to use a version of the SDK that doesn't include any location tracking nor links the CoreLocation framework, use this subspec:
    # pod 'mParticle-Apple-SDK/mParticleNoLocation', '~> 8'
end

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:

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

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

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.

Carthage

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


binary "https://raw.githubusercontent.com/mParticle/mparticle-apple-sdk/main/mParticle_Apple_SDK.json" ~> 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 click on your project in the file list on the left, click on your Project name in the middle of the window, click on the "Package Dependencies" tab, and click the "+" button underneath the Packages list.

Enter the repository URL https://github.com/mParticle/mparticle-apple-sdk in the search box on the top right, choose mparticle-apple-sdk from the list of pacakges, and change "Dependency Rule" to "Up to Next Major Version". Then click the "Add Package" button on the bottom right.

Then choose either the "Package Product" called mParticle-Apple-SDK, or if you'd like to use a version of the SDK that doesn't include any location tracking nor links the CoreLocation framework choose mParticle-Apple-SDK-NoLocation.

IMPORTANT: If you choose the mParticle-Apple-SDK-NoLocation package product, you will need to import the SDK using import mParticle_Apple_SDK_NoLocation instead of import mParticle_Apple_SDK as shown in the rest of the documentation and this README.

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	Swift Package Manager
Adjust	✓	✓	✓
Appboy	✓	✓	✓
Adobe	✓	✓
AppsFlyer	✓	✓	✓
Appsee	✓
Apptentive	✓	✓
Apptimize	✓
Apteligent	✓
Blueshift	✓
Branch Metrics	✓	✓
Button	✓	✓
CleverTap	✓	✓
comScore	✓
Flurry	✓
Google Analytics for Firebase	✓
Instabot	✓
Iterable	✓	✓
Kahuna	✓
Kochava	✓		✓
Leanplum	✓	✓
Localytics	✓	✓
Optimizely	✓	✓
OneTrust	✓	✓
Pilgrim	✓	✓
Primer	✓	✓
Radar	✓	✓
Responsys
Reveal Mobile	✓
Singular	✓
Skyhook	✓
Taplytics	✓
Tune	✓	✓
Urban Airship	✓
UserLeap	✓	✓
Wootric	✓

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.

Swift

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
}

Objective-C

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.

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

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.

SDK Documentation

Support

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

License

Apache 2.0

mParticle/mparticle-apple-sdk