Getting Started

Overview

The mParticle SDK is composed of the “core” library and a series of “kit” libraries that depend on the core. With each integration with a partner we strive to implement as many features as possible in the server-to-server layer, however sometimes a deeper integration, working side-by-side with a 3rd party SDK, is necessary to capture a partner’s full feature set. We use the term Kit to describe such integrations.

The core SDK takes care of initializing kits, depending on what you’ve configured in your app dashboard, so you just have to decide which kits you might want to use prior to submission to the App Store. You can easily include all of the kits, none of the kits, or selected individual kits.

Get the SDK

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

CocoaPods

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', '~> 7'
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:

# 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', '~> 7'
    pod 'mParticle-BranchMetrics', '~> 7'
    pod 'mParticle-Localytics', '~> 7'
end

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, Taplytics 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

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:

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

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

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

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

Currently Supported Kits

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.

Upgrade to Version 7 of the SDK

Version 7 of the Apple SDK contains breaking changes from version 6.x, including new methods to support mParticle’s IDSync features and the deprecation of older methods for managing users.

MParticleOptions object

It is now required to configure the SDK by supplying an MParticleOptions argument to startWithOptions. Previously it was possible to initialize the SDK using startWithKey. See Initialize the SDK for more.

Identity and User Attributes

Previously, current user identities and attributes were set at the level of the device and included with any outgoing batches. This approach has been deprecated in favor of more explicit user management via the Identity API. You may include an Identity request when you intialize the SDK. If you do not specify a request, identify will be called with the most recently stored user identities. You should also update the current User Identity at appropriate points in your app lifecycle, such as Login and Logout.

UserAliasHandler

When transitioning from one user to another, usually as a previously anonymous user creates an account and becomes a known user, some Identity Strategies will alias the old anonymous profile to the new known one. The UserAliasHandler gives you the option to copy over attributes currently held in local storage to the new user profile.

The MParticleUser object

The setUserIdentity and setUserAttribute methods are deprecated as at version 5. Instead, the current user, as determined by the Identity API is exposed via the MParticleUser object. The MParticleUser provides methods to check the MPID of the current user, modify the user’s Identity Record and get/set attributes.

First Initialize after Upgrade

The first time the upgraded SDK is initialized for an existing user, the SDK will automatically migrate identities and attributes currently in local storage. If you do not provide an identity request in your MParticleOptions object, the initial identity request will be created automatically based on any migrated identities.

Deeplinking / Attribution

Version 7 includes a new Attribution API. If you use any of our deeplinking partners, including Appsflyer, Button, Branch and Tune, you may need to update your code. See our Kits documentation for more.

Shopping Cart

The shopping cart is now maintained against the current user. See the eCommerce docs for details.

Upgrade Checklist

• Create MParticleOptions object and pass it to startWithOptions in your initialization code.
• If you are implementing an eCommerce strategy, implement a UserAliasHandler.
• Replace any instance of setUserIdentity with the appropriate Identity method.
• Any instance of setUserAttribute must now be called on your MParticleUserObject.
• Any methods accessing the cart must be called on the current user object.

Common Errors / Fixes

If you update your build.gradle to version 5 without making further changes, your code will not compile. See below for a list of common errors and fixes.

Error

No visible @interface for 'MParticle' declares the selector 'startWithKey:secret:'

Fix:

// Old code:
// [[MParticle sharedInstance] startWithKey:@"foo-api-key"
//                                   secret:@"foo-api-secret"];

// Replace with MParticleOptions object and new startWithOptions method
// See Initialize the SDK for more
MParticleOptions *mParticleOptions = [MParticleOptions optionsWithKey:@"foo-api-key"
                                                               secret:@"foo-api-secret"];

MPIdentityApiRequest *request = [MPIdentityApiRequest requestWithEmptyUser];
mParticleOptions.identifyRequest = request;
mParticleOptions.onIdentifyComplete = ^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
    NSLog(@"Identify complete. userId = %@ error = %@", apiResult.user.userId, error);
};

[[MParticle sharedInstance] startWithOptions:mParticleOptions];

Error

No visible @interface for 'MParticle' declares the selector 'setUserIdentity:identityType:'

Fix:

// Old code:
// [[MParticle sharedInstance] setUserIdentity:@"foo@example.com"
//                                identityType:MPUserIdentityEmail];

// Replace with an appropriate Identity request.
// See Identity for more.
MPIdentityApiRequest *identityRequest = [MPIdentityApiRequest requestWithEmptyUser];
identityRequest.email = @"foo@example.com";

[[[MParticle sharedInstance] identity] login:identityRequest
                                  completion:^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
    if (error)           
        //retry the request or otherwise handle the error, see below
    } else {
        //Continue with login, and you can also access the new/updated user:
        MParticleUser *user = apiResult.user;
    }
}];

Error

No visible @interface for 'MParticle' declares the selector 'setUserAttribute:value:'

Fix:

// Old code:
// [[MParticle sharedInstance] setUserAttribute: @"foo"
//                                        value: @"bar"];

// Replace by calling setUserAttribute on the current user.
// See Identity for more.
MParticleUser *currentUser = [[[MParticle sharedInstance] identity] currentUser];
[currentUser setUserAttribute:@"foo" 
                        value:@"bar"];

Error

No visible @interface for 'MParticle' declares the selector 'logout'

Fix:

// Old code:
// [[MParticle sharedInstance] logout];

// Replace with Logout Identity Request
// See Identity for more
MPIdentityApiRequest *identityRequest = [MPIdentityApiRequest requestWithEmptyUser];

[[[MParticle sharedInstance] identity] logout:identityRequest
                                   completion:^(MPIdentityApiResult * _Nullable apiResult, NSError * _Nullable error) {
    if (error)           
        //retry the request or otherwise handle the error, see below
    } else {
        //Continue with logout, and you can also access the new/updated user:
        MParticleUser *user = apiResult.user;
    }
}];