Android (Java) to Android (Kotlin) SDK Migration Guide

This guide walks you through migrating persisted SDK state data from the Android (Java) SDKAndroid (Java) refers to the legacy RudderStack Android SDK. Note that it will be deprecated soon.

For new implementations, use the Android (Kotlin) SDK instead. to the Android (Kotlin) SDK to maintain continuity of user identity, session tracking, and app info across SDK versions.

Pre-migration considerations

You can migrate the following data from the legacy Android (Java) SDK to the Android (Kotlin) SDK:

• anonymousId
• userId
• traits
• sessionId
• lastActivityTime
• App version
• App build
• Manual session tracking status

Also, note that:

• Events are not migrated in this process
• The Android (Kotlin) SDK does not persist external IDs, so you do not need to migrate them
• Opt status, opt in time, and opt out time are not supported in the Android (Kotlin) SDK
• The Android (Kotlin) SDK does not persist the advertising ID — use a custom AndroidAdvertisingId Plugin instead
• The Android (Kotlin) SDK manages server config independently, so you do not need to migrate the server config last update value

Migration process overview

Note that:

• You must run the migration before initializing the Android (Kotlin) SDK. The SDK reads persisted values on initialization, so migrated data must already be in place.
• Configure the migration code so that it runs only once.

1. Understand how storage works in the legacy Android (Java) SDK.
2. Run pre-flight checks to verify that the migration is possible.
3. Migrate the data from the legacy SDK to the Android (Kotlin) SDK (see the mapping table below).
4. Write the migrated data to the Android (Kotlin) SDK’s SharedPreferences file.
5. Optional but recommended: Clean up the legacy storage.
6. Initialize the Android (Kotlin) SDK.

Step 1: Understand legacy SDK storage

The legacy Android (Java) SDK and the Android (Kotlin) SDK store data in different SharedPreferences files:

Data availability

These values are available only if the legacy SDK-based app was not removed before installing the app version integrated with the Android (Kotlin) SDK.

Step 2: Run pre-flight checks

The runPreflightChecks() method validates the following before the migration:

val migration = Migration(context = this, writeKey = writeKey)

val canProceed = migration.runPreflightChecks()
if (!canProceed) {
    Log.w("Migration", "Pre-flight checks failed - skipping migration")
    return
}

If any check fails, the method returns false and you should skip the migration.

Step 3: Migrate the data

Follow these steps to migrate the existing values:

1. Extract values from the legacy SharedPreferences storage.
2. Transform values as needed — see the Storage key mapping table below.
3. Write values to the Android (Kotlin) SDK’s SharedPreferences file.

// Extract data from legacy storage
val legacyData = migration.extract()
Log.d("Migration", "Extracted: $legacyData")

// Transform to new format
val transformedData = migration.transform(legacyData)
Log.d("Transformation", "Transformed: $transformedData")

// Write to new storage
val writeSuccess = migration.write(transformedData)
if (!writeSuccess) {
    Log.e("Migration", "Failed to write migrated data")
    return
}

Storage key mapping

After retrieving the values from the legacy storage, store each value using its corresponding Android (Kotlin) SDK key:

Step 4: Clean up legacy storage

Cleanup is optional but recommended after a successful migration.

After a successful write, clean up the legacy storage:

migration.cleanup()

Step 5: Initialize the Android (Kotlin) SDK

After completing the migration, you can safely initialize the Android (Kotlin) SDK. The SDK reads the migrated values from SharedPreferences on initialization.

Complete example

The following example shows the complete migration flow in Application.onCreate(), before SDK initialization:

// In Application.onCreate(), BEFORE SDK initialization
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        val writeKey = "YOUR_NEW_SDK_WRITE_KEY"

        Migration(context = this, writeKey = writeKey).run {
            if (!runPreflightChecks()) return@run

            extract()
                .let(::transform)
                .let(::write)
                .also { success -> if (success) cleanup() }
        }

        // NOW safe to initialize the SDK
        initializeRudderSDK()
    }
}

Selective migration

You can migrate only specific values by passing a set of MigratableValue options to the extract() method:

val legacyData = migration.extract(
    values = setOf(
        MigratableValue.ANONYMOUS_ID,
        MigratableValue.USER_ID,
        MigratableValue.TRAITS
    )
)

The available MigratableValue options are:

• ANONYMOUS_ID
• USER_ID
• TRAITS
• SESSION_ID
• LAST_ACTIVITY_TIME
• APP_VERSION
• APP_BUILD
• IS_SESSION_MANUAL
• ALL (automatically includes all of the above)

Migration helper class

RudderStack provides a migration helper class — Migration — in the sample app to help you migrate persisted values from the legacy Android (Java) SDK.

Use this helper if you are upgrading from the legacy Android (Java) SDK and want to restore persisted values before initializing the Android (Kotlin) SDK.

Note that:

• Use the Android (Kotlin) SDK’s write key (not the legacy Android (Java) SDK’s write key).
• Handle device reboots gracefully — the session resets naturally.

Migrate integration SDKs

When migrating from legacy Android (Java) integration SDKs to Android (Kotlin) integration SDKs, the destination SDK (Braze, Adjust, AppsFlyer, etc.) handles its own data migration. The RudderStack migration process only migrates RudderStack SDK state data, not destination SDK data.

RudderStack recommends the following:

• Check destination SDK migration documentation: Each destination SDK may have its own migration requirements when upgrading versions. Refer to the official documentation for Braze, Adjust, AppsFlyer, Facebook, and Firebase for version-specific migration steps.
• The destination SDK manages its own data: The RudderStack migration process does not touch destination SDK data stored on the device. This data is managed entirely by the destination SDKs themselves.

If you are running both the legacy Android (Java) SDK and the Android (Kotlin) SDK simultaneously (during a gradual rollout), configure each integration in only one of the SDKs.

Having the same integration active in both SDKs can lead to unpredictable behavior.

Troubleshooting