Migrate to the Android-Kotlin SDK

SDK Comparison

Feature	Maintenance SDK	Latest SDK
Package	com.amplitude:android-sdk	com.amplitude:analytics-android
SSL Pinning	Supported	TBD
Configuration	Supports specific setter methods	Configuration is implemented by the configuration object. Configurations need to be passed into Amplitude Object during initialization.
Logger Provider	Amplitude Logger. Not customizable.	`ConsoleLoggerProvider()` by default. Fully customizable.
Storage Provider	SQLite Database.	`InMemoryStorageProvider()` by default. File storage. Fully customizable.
Customization	Middleware	Plugins
Server Endpoint	HTTP V1 API	HTTP V2 API
Batch API	Not supported.	Supported, with configuration.
Default Event Tracking	Support sessions tracking only, disabled by default.	Support sessions, app lifecycles, screen views, and deep links trackings.

Amplitude's latest Android SDK (com.amplitude:analytics-android) features a plugin architecture, built-in type definitions, is written in Kotlin. The latest Android SDK isn't backwards compatible with the maintenance Android SDK com.amplitude:android-sdk.

To migrate to com.amplitude:analytics-android, update your dependencies and instrumentation.

Terminology

com.amplitude:android-sdk: Maintenance Android SDK
com.amplitude:analytics-android: Latest Android SDK

Dependency

Update build.gradle to remove the maintenance Android SDK and add the latest Android SDK. Then sync project with Gradle files.

1dependencies {
-  implementation 'com.amplitude:android-sdk:2.+' 
+  implementation 'com.squareup.okhttp3:okhttp:4.2.2' 
+  implementation 'com.amplitude:analytics-android:1.+'
5}

Instrumentation

The latest Android SDK offers an new API to instrument events. To migrate to it, you need to update a few calls. The following sections detail which calls have changed.

Initialization

Initialize the SDK with a valid Amplitude API Key and Android application context.

 -import com.amplitude.api.Amplitude 
 -import com.amplitude.api.AmplitudeClient
 +import com.amplitude.android.Amplitude 
 4 
 -val client = Amplitude.getInstance() 
 -  .initialize(getApplicationContext(), "YOUR_API_KEY")
 +val client = Amplitude( 
 +    Configuration(
 +        apiKey = "YOUR_API_KEY",
 +        context = getApplicationContext()
 +    )
 +)

 -import com.amplitude.api.Amplitude; 
 -import com.amplitude.api.AmplitudeClient;
 +import com.amplitude.android.Amplitude; 
 4 
 -AmplitudeClient client = Amplitude.getInstance() 
 -  .initialize(getApplicationContext(), "YOUR_API_KEY");
 +Amplitude client =  new Amplitude(new Configuration( 
 +    apiKey = "YOUR_API_KEY",
 +    context = getApplicationContext()
 +));

Configuration

The latest Android SDK configuration comes in a different shape. Some configurations are no longer supported.

com.amplitude:android-sdk	com.amplitude:analytics-android
`eventUploadPeriodMillis`	`flushIntervalMillis`
`eventUploadThreshold`	`flushQueueSize`
`eventUploadMaxBatchSize`	Not supported
`eventMaxCount`	Not supported
`identifyBatchIntervalMillis`	`identifyBatchIntervalMillis`
`flushEventsOnClose`	`flushEventsOnClose`
`optOut`	`optOut`
`trackingSessionEvents`	`trackingSessionEvents`
`sessionTimeoutMillis`	Not supported. The maintenance SDK disables foreground tracking by default and uses `sessionTimeoutMillis` when foreground tracking is disabled. However, the latest SDK enables foreground tracking and it's not configurable.
`minTimeBetweenSessionsMillis`	`minTimeBetweenSessionsMillis`
`serverUrl`	`serverUrl` defaults to `https://api2.amplitude.com/2/httpapi` while the maintenance SDK defaults to `https://api2.amplitude.com/`
`useDynamicConfig`	Not supported

Send events

The logEvent() API maps to track(). The eventProperties is JSONObject type in the maintenance SDK while it's Map<String, Any?> type in the latest SDK.

 -import org.json.JSONException 
 -import org.json.JSONObject
 3 
 -val eventProperties = JSONObject() 
 -try {
 -  eventProperties.put("buttonColor", "primary")
 -} catch (e: JSONException) {
 -  System.err.println("Invalid JSON")
 -  e.printStackTrace()
 -}
 -client.logEvent("Button Clicked", eventProperties)
12 
 +client.track( 
 +    "Button Clicked",
 +    mutableMapOf<String, Any?>("buttonColor" to "primary")
 +)

 -import org.json.JSONException; 
 -import org.json.JSONObject;
 3 
 -JSONObject eventProperties = new JSONObject(); 
 -try {
 -  eventProperties.put("buttonColor", "primary");
 -} catch (JSONException e) {
 -  System.err.println("Invalid JSON");
 -  e.printStackTrace();
 -}
 -client.logEvent("Button Clicked", eventProperties);
12 
 +client.track("Button Clicked", new HashMap() );

Flush events

Unset events are stored in a buffer and flushed (sent) on app close by default. Events are flushed based on which criteria is met first: flushIntervalMillis or flushQueueSize.

You can disable flushing by setting flushEventsOnClose to false.

You can also force the SDK to upload unsent events. The uploadEvents() API maps to flush().

-client.uploadEvents() 
+client.flush()

Set user properties

The identify() API remains the same

1val identify = Identify()
2identify.set("location", "LAX")
3client.identify(identify)

1Identify identify = new Identify();
2identify.set("location", "LAX");
3client.identify(identify);

Set group properties

1val groupType = "plan"
2val groupName = "enterprise"
3 
4val identify = Identify().set("key", "value")
5client.groupIdentify(groupType, groupName, identify)

1String groupType = "plan";
2Object groupName = "enterprise";
3 
4Identify identify = new Identify().set("key", "value");
5client.groupIdentify(groupType, groupName, identify);

Track revenue

The logRevenueV2() API maps to revenue().

1val revenue = Revenue()
2revenue.productId = "com.company.productId"
3revenue.price = 3
4revenue.quantity = 2
-client.logRevenueV2(revenue) 
+client.revenue(revenue)

1Revenue revenue = new Revenue()
2revenue.setProductId("com.company.productId");
3revenue.setPrice(3);
4revenue.setQuantity(2);
-client.logRevenueV2(revenue); 
+client.revenue(revenue);

Revenue verification

The revenue verification logic is on Amplitude's backend. Revenue verification remains functional after migrating to the latest Android SDK.

Advanced topics

Warning

The maintenance SDK uses an old SDK endpoint (api2.amplitude.com) which enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength to a smaller value if you allowed identifiers with fewer than 5 characters.

Most of the behaviors of the latest SDK remain the same with the maintenance SDK. Refer to the advanced topics sections of the maintenance SDK and the latest SDK to learn more about a specific advanced topic.

Data migration

Existing maintenance SDK data (events, user/device ID) are moved to the latest SDK by default. It can be disabled by setting migrateLegacyData to false in the Configuration. Learn more in Github.

1amplitude = Amplitude(
2    Configuration(
3        ...
4        migrateLegacyData = false,
5    )
6)

1Configuration configuration = new Configuration("AMPLITUDE_API_KEY", getApplicationContext());
2configuration.setMigrateLegacyData(false);
3 
4Amplitude amplitude = new Amplitude(configuration);