Migrating from SDK v4 to v5

Key Improvements and Changes in Android SDK v5

Android SDK v5 introduces major architectural changes compared with v4. The most important differences are:

• Modern Android architecture: SDK v5 uses WorkManager for background delivery and persists requests in a database instead of app files.

• Improved tracking flexibility: v5 supports form tracking, WebView bridging, object-oriented tracking, runtime changes for Track ID and Track Domain, and additional privacy controls.

• Runtime configuration APIs: several settings can be changed after initialization, for example batch support, app-version sending, user matching, and everID handling.

• Privacy features: v5 supports anonymous tracking, temporary session IDs for anonymous sessions, opt-out handling, and user matching with Mapp Engage.

Important

SDK v5 uses WorkManager for periodic delivery. The minimum periodic interval is 15 minutes. Actual execution timing depends on Android system conditions and should not be treated as an exact send schedule.

If you use SDK batch support, it groups requests inside the SDK before delivery. This is separate from Android's WorkManager scheduling.

Current Technical Baseline

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

• Android 6.0 / API 23+

• JDK 17 for current releases

• AndroidX enabled

For the full current setup, see Technical Requirements and Add the SDK Dependency.

Steps for Migration

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

1. Implement SDK v5
   Install and initialize Android SDK v5 as described in the documentation. You can use either query-based tracking or object-oriented tracking.

2. Enable migration
   Turn on the migration option in the global configuration so that existing everID data is preserved.

   Kotlin

   Java

   class SampleApplication : Application() {
   
       override fun onCreate() {
           super.onCreate()
   
           val configuration = WebtrekkConfiguration.Builder(
               listOf("YOUR_TRACK_ID"),
               "YOUR_TRACK_DOMAIN"
           )
               .enableMigration()
               .build()
   
           Webtrekk.getInstance().init(this, configuration)
       }
   }

   public class SampleApplication extends Application {
   
       @Override
       public void onCreate() {
           super.onCreate();
   
           WebtrekkConfiguration configuration = new WebtrekkConfiguration.Builder(
               Arrays.asList("YOUR_TRACK_ID"),
               "YOUR_TRACK_DOMAIN"
           )
               .enableMigration()
               .build();
   
           Webtrekk.getInstance().init(this, configuration);
       }
   }

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

Key Migration Notes

• SDK v5 no longer uses Tag Integration-based app configuration. Configure the SDK directly in the app.

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