Skip to content

Migration Guide

Jump to bottom
Peter Jenkins edited this page Feb 14, 2018 · 4 revisions

Migration Guide

Migrating to Version 7

Version 7 of the Apple SDK contains multiple breaking API changes as well as IDSync, mParticle's cross-device identity framework. Please reference our doc site for a migration guide and updated identity API documentation:

Migrating From Version 4 or 5 to Version 6

Here we address the steps to migrate from an earlier version of the SDK to the latest one.

Podfile

If you currently have version 4.x or 5.x of the SDK instrumented in your app, you will need to update your Podfile.

Remove the old mParticle pod statement

pod 'mParticle', '~> 4'
or
pod 'mParticle-iOS-SDK', '~> 5'
or
pod 'mParticle-Apple-SDK', '~> 5'

and replace it with:

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

For further options configuring your Podfile such as including kits please see the Get the SDK section of our README or if you are building a multi-platform (iOS and tvOS) project see Multi-platform configuration.

Kits

Kits are now implemented as extensions to the mParticle SDK. Ergo, the wrapper to each kit is no longer deployed together with the core SDK, instead they are their own pod in CocoaPods.

If you are using kits with the mParticle SDK in your Podfile as in the sample below:

pod 'mParticle-Apple-SDK', '~> 5', :subspecs => ['Appboy']
or
pod 'mParticle-Apple-SDK/Appboy', '~> 5'

You will need to update the pod statement to:

target '<Your Target>' do
    pod 'mParticle-Appboy', '~> 6'
end

Kit Status and Retrieval Methods

The signature of the methods to verify the status of a kit and to retrieve a kit instance have changed to take a NSNumber representing the kit code. Previously those methods a raw value from the MPKitInstance enum.

- (nullable id const)kitInstance:(nonnull NSNumber *)kitCode;
- (BOOL)isKitActive:(nonnull NSNumber *)kitCode;

For example, in previous versions you would use:

BOOL kitActive = [[MParticle sharedInstance] isKitActive:MPKitInstanceBranchMetrics];

Now you would use:

BOOL kitActive = [[MParticle sharedInstance] isKitActive:@(MPKitInstanceBranchMetrics)];

This change was necessary due to the new architecture where kits are implemented as extensions to the core SDK.

Import Statement

The import statement changes with version 6 of the SDK since it has been implemented as framework/module. The new syntax is:

Swift
import mParticle_Apple_SDK
Objective-C
@import mParticle_Apple_SDK;

If your app still needs to support iOS 7, please use:

#import <mParticle_Apple_SDK/mParticle.h>

If you're coming from version 4 or version 5, replace `#import ` or `#import ` with the option above that is most appropriate for you.

Moreover, in case you had the need to directly call methods from a 3rd party provider kit through the mParticle SDK, you no longer need to indirectly import their headers. You can just import them directly as indicated in the provider respective documentation. For example, if you were using:

#import <mParticle/Appboy/AppboyKit.h>

You will now use:

#import <AppboyKit.h>

Or whichever other way is recommended by the 3rd party provider.

Log Level

If you are using the .logLevel property to control what gets logged to the Xcode console and are coding in Objective-C, you will need to make a small change. We have renamed the MPLogLevel enum to MPILogLevel. The renamed values are: MPILogLevelNone, MPILogLevelError, MPILogLevelWarning, MPILogLevelDebug, and MPILogLevelVerbose.

For example, if you are setting the log level to debug as:

[MParticle sharedInstance].logLevel = MPLogLevelDebug;

You'd need to change it to:

[MParticle sharedInstance].logLevel = MPILogLevelDebug;
Clone this wiki locally