Upgrade to Version 9

Version 9 of the Apple SDK contains breaking changes from version 8.x, including removal of the AppDelegateProxy (you must now forward push, URL, and user-activity events to the SDK), removal of deprecated UIApplicationDelegate URL/activity methods in favor of the UIScene lifecycle, removal of location support and the NoLocation variant, removal of support for iOS app extension targets, removal of Carthage distribution (use Swift Package Manager or CocoaPods instead), direct routing to regional endpoints by default, and API changes for MPRokt and listener callbacks. The SDK’s minimum deployment is iOS 15 and tvOS 15. This guide covers migration from versions < 9.0.0. For migration from SDK 7.x to 8.x, see the mParticle Apple SDK migration guide v8 on GitHub.

Imports (Swift, Objective-C, and Rokt)

Swift: Use import mParticle_Apple_SDK for all public SDK APIs, including Rokt types (such as RoktEvent) that the kit re-exports. You do not need a separate import RoktContracts in Swift for typical mParticle + Rokt usage.

Objective-C: Prefer #import <mParticle_Apple_SDK.h>, or @import mParticle_Apple_SDK; when modules are enabled. If a source file references Rokt SDK types directly (for example in blocks that take RoktEvent *), add @import RoktContracts; (or the equivalent for your build) in that file only.

Swift Package Manager: Depend on the single product mParticle-Apple-SDK; the old mParticle-Apple-SDK-NoLocation product name is no longer used (see Removed Location Support).

Removed AppDelegateProxy

The AppDelegateProxy feature has been removed from the SDK. The SDK no longer automatically intercepts UIApplicationDelegate messages for push notifications, URL opening, or user activity. You must explicitly forward these events to the SDK from your app delegate or scene delegate.

What Has Changed

• The proxyAppDelegate property has been removed from MParticleOptions
• The proxiedAppDelegate property has been removed from MParticle
• The MPAppDelegateProxy and MPSurrogateAppDelegate classes have been removed

Migration Steps

If you were using proxyAppDelegate = YES (the default), you must now forward app delegate events to the SDK. See Push Notifications and Configuration – Forwarding app lifecycle events for the required code.

• Remove any references to proxyAppDelegate from your MParticleOptions configuration
• Remove any references to proxiedAppDelegate property checks

Removed Legacy Database Migration Support

Support for migrating from SDK versions prior to 8.27.0 (internal database version < 30) has been removed. Only migration from the immediately preceding database version (v30 → v31) is supported.

What This Means

• Apps upgrading from 8.26.x or earlier to SDK 9.x will start with a fresh local database
• Any pending (unsent) events from the old SDK version will be lost during the upgrade
• User identity and session data will be re-established after the upgrade

This only affects apps that are upgrading directly from mParticle SDK versions before 8.27.0 (released August 2024) and that have pending events not yet uploaded to mParticle.

Removed MPListenerController

The MPListenerController class has been removed. The SDK no longer invokes any listener callbacks.

App extension targets

The mParticle Apple SDK 9.x does not support iOS app extension targets. If you need the SDK in an extension, you can continue using 8.x. If you require continued app extension support beyond that path, contact your mParticle representative.

Removed Carthage support

Carthage is no longer supported for the mParticle Apple SDK as of 9.0.0. Integrate the SDK with Swift Package Manager or CocoaPods, or build manually from source. If you relied on Carthage with SDK 8.x, migrate your dependency to SPM or CocoaPods before upgrading.

Direct Routing Enabled by Default

API requests now route directly to regional endpoints based on your API key prefix.

Before (8.x):

• nativesdks.mparticle.com
• tracking-nativesdks.mparticle.com
• identity.mparticle.com
• tracking-identity.mparticle.com
• config2.mparticle.com

After (9.x):

• nativesdks.[pod].mparticle.com
• tracking-nativesdks.[pod].mparticle.com
• identity.[pod].mparticle.com
• tracking-identity.[pod].mparticle.com
• config2.mparticle.com (unchanged; used for SDK configuration)

Examples by API key format:

If your app has strict App Transport Security (ATS) settings, you may need to add NSIncludesSubdomains set to YES for the mparticle.com domain in your Info.plist to allow connections to regional subdomains.

Removed Deprecated UIApplicationDelegate Methods

Apple has deprecated several UIApplicationDelegate protocol methods in favor of the UIScene lifecycle. The mParticle SDK has removed its wrapper methods for these deprecated delegate methods. Use the UIScene-based APIs in your SceneDelegate instead. The SDK’s minimum deployment is iOS 15 and tvOS 15, so the UIScene lifecycle is always available.

What Has Changed

The following methods have been removed from the MParticle class:

• openURL:sourceApplication:annotation:
• openURL:options:
• continueUserActivity:restorationHandler:

Migration Steps

Use the UIScene lifecycle in your SceneDelegate and call the new SDK methods.

URL handling — use handleURLContext: in your SceneDelegate:

// In SceneDelegate
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    for (UIOpenURLContext *urlContext in URLContexts) {
        [[MParticle sharedInstance] handleURLContext:urlContext];
    }
}

// In SceneDelegate
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    for urlContext in URLContexts {
        MParticle.sharedInstance().handleURLContext(urlContext)
    }
}

User activity (universal links, Handoff) — use handleUserActivity: in your SceneDelegate:

// In SceneDelegate
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
    [[MParticle sharedInstance] handleUserActivity:userActivity];
}

// In SceneDelegate
func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    MParticle.sharedInstance().handleUserActivity(userActivity)
}

• If you still use the UIApplicationDelegate lifecycle without scenes, consider migrating to the UIScene lifecycle as Apple continues to deprecate the older approach

Removed Location Support

In version 9.0.0, location support has been removed from the SDK. The SDK now provides a single target without location functionality.

What Has Changed

• Location-related functionality has been removed
• The SDK provides a single target (no separate Location or NoLocation variant)
• The target name is the standard name (e.g. mParticle-Apple-SDK); the -NoLocation product name has been removed

Migration Steps

If you were using a target with Location support:
Switch your project to the standard target (no Location suffix) and remove any location-related dependencies, imports, or build scripts.

If you were using the NoLocation variant (e.g. mParticle-Apple-SDK-NoLocation):

1. Replace the NoLocation import/product with the standard name: mParticle-Apple-SDK
2. Update Package.swift or Podfile to use the standard target/product name

Swift Package Manager example:

// Before (NoLocation variant)
.target(
    name: "MyTarget",
    dependencies: [
        .product(name: "mParticle-Apple-SDK-NoLocation", package: "mParticle-Apple-SDK")
    ]
)

// After (standard target)
.target(
    name: "MyTarget",
    dependencies: [
        .product(name: "mParticle-Apple-SDK", package: "mParticle-Apple-SDK")
    ]
)