Migrating from SDK v4 to v5

Key improvements in iOS SDK v5

iOS SDK v5 introduces several improvements over v4:

• Higher data quality:

  • Requests are stored in a database instead of within an app file.

  • Requests can be sent in batches to ensure correct page navigation paths.

  • WebViews can be tracked entirely inside the app context.

  • Campaign tracking is improved and refactored.

• Detailed logs and a reset() function to simplify debugging.

• Improved performance and battery usage.

• Apple Privacy Manifest support and XCFramework distribution (since 5.1.0).

Current technical baseline

Before migrating, make sure your iOS project matches the current SDK requirements:

• iOS 12 or later (also covers iPadOS)

• Xcode 14 or later (recommended)

• Swift 5.x or Objective-C

For the full setup, see Requirements & Compatibility and Add the SDK Dependency.

Differences in v5 to be aware of

• Visit / session behavior: In v4, the fns parameter (force new session) was timer-based and restarted sessions every 30 seconds by default. v5 enforces stricter session rules: sessions restart only on app restart (after the app has been killed) or after 30 minutes of inactivity (enforced during post-processing).

• Default request interval: 15 minutes (matches Android SDK v5). Configurable between approximately 5 seconds (minimum) and 60 minutes (maximum). Reducing the interval increases battery usage; prefer enabling batch support and using server-side client timestamps instead.

• No more Tag Integration: v5 does not support configuration via Tag Integration. Configure the SDK directly in the app.

Steps for migration

Preserving the existing customer everID is crucial when moving from iOS SDK v4 to v5. Without migration, updated app users may appear as new visitors in Mapp Intelligence.

1. Implement iOS SDK v5 as described in Add the SDK Dependency and Initialize the SDK.

2. Enable migration by setting shouldMigrate = true in your AppDelegate (or your @main App's init()):

   Swift

   Objective-C

   MappIntelligence.shared()?.initWithConfiguration(
       [123451234512345],
       onTrackdomain: "https://your-trackdomain.com"
   )
   MappIntelligence.shared()?.shouldMigrate = true

   [[MappIntelligence shared]
       initWithConfiguration:@[@123451234512345]
               onTrackdomain:@"https://your-trackdomain.com"];
   [[MappIntelligence shared] setShouldMigrate:YES];

3. Remove the v4 SDK and any v4 configuration / tracking setup from your app. Running both SDK generations in parallel can lead to duplicate tracking.

4. Keep the same Bundle Identifier. Changing the Bundle Identifier during migration breaks the everID continuity.

5. Publish the app.

Important: Keep the application's Bundle Identifier unchanged throughout the entire migration to avoid data loss.

Key migration notes

• Anonymous tracking prevents everID-based continuity and is therefore not compatible with v4-to-v5 everID migration.

• If you rely on release-specific fixes or behavior changes, review the Releases & Changelog page before shipping the migrated app.