Migrating from SDK v4 to v5

Updated
  • 1 minute(s) read
Prev Next

This page describes how to migrate from iOS SDK v4 to v5 while preserving the existing customer everID. Without migration, updated app users may appear as new visitors in Mapp Intelligence.

Two hard requirements before you start:

  • Bundle Identifier must not change during the migration. Changing it breaks everID continuity and causes data loss.

  • Anonymous Tracking is not compatible. If your app uses Anonymous Tracking, the v4-to-v5 everID migration cannot preserve user continuity.

Before you start

Make sure your project meets the SDK requirements — see Requirements & Compatibility and Add the SDK Dependency.

Migration steps

  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()):

    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 or tracking setup from your app. Running both SDK generations in parallel can lead to duplicate tracking.

  4. Publish the app.

Behavior changes after migration

  • 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.

Why migrate

Compared to v4, iOS SDK v5 offers:

  • 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).