Skip to content

Android SDK Migration Guide

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.


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


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

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


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.


You must initialize the SDK with a valid Amplitude API Key and Android application context.

- import com.amplitude.api.Amplitude
- import com.amplitude.api.AmplitudeClient
+ import

- 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;

- AmplitudeClient client = Amplitude.getInstance()
-   .initialize(getApplicationContext(), "YOUR_API_KEY");
+ Amplitude client =  new Amplitude(new Configuration(
+     apiKey = "YOUR_API_KEY",
+     context = getApplicationContext()
+ ));


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 while the maintenance SDK defaults to
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

- val eventProperties = JSONObject() 
- try {
-   eventProperties.put("buttonColor", "primary")
- } catch (e: JSONException) {
-   System.err.println("Invalid JSON")
-   e.printStackTrace()
- }
- client.logEvent("Button Clicked", eventProperties)

+ client.track(
+     "Button Clicked",
+     mutableMapOf<String, Any?>("buttonColor" to "primary")
+ )
- import org.json.JSONException;
- import org.json.JSONObject;

- JSONObject eventProperties = new JSONObject();
- try {
-   eventProperties.put("buttonColor", "primary");
- } catch (JSONException e) {
-   System.err.println("Invalid JSON");
-   e.printStackTrace();
- }
- client.logEvent("Button Clicked", eventProperties);

+ client.track("Button Clicked", new HashMap() {{
+     put("buttonColor", "primary");
+ }});

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()
- client.uploadEvents();
+ client.flush();

Set user properties


The identify() API remains the same

val identify = Identify()
identify.set("location", "LAX")
Identify identify = new Identify();
identify.set("location", "LAX");

Set group properties


The groupIdentify() API remains the same.

val groupType = "plan"
val groupName = "enterprise"

val identify = Identify().set("key", "value")
client.groupIdentify(groupType, groupName, identify)
String groupType = "plan";
Object groupName = "enterprise";

Identify identify = new Identify().set("key", "value");
client.groupIdentify(groupType, groupName, identify);

Track revenue


The logRevenueV2() API maps to revenue().

val revenue = Revenue()
revenue.productId = ""
revenue.price = 3
revenue.quantity = 2
- client.logRevenueV2(revenue)
+ client.revenue(revenue)
Revenue revenue = new Revenue()
- client.logRevenueV2(revenue);
+ client.revenue(revenue);

Revenue verification

The revenue verification logic is on Amplitude's backend. So revenue verification still works after migrating to the latest Android SDK.

Advanced topics

Id length limit

The maintenance SDK uses an old SDK endpoint ( which enforces no length limit for deviceId and userId. The latest SDK uses Amplitude's HTTP V2 API ( 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.


This section provides a comparison between different version of SDKs. This overview provides key insights for developers, identifying areas that have significant changes and need careful consideration.


While there are multiple versions of our SDK available, please use the latest version of the SDKs rather than maintenance SDKs. Maintenance versions only provide support and will eventually be deprecated. The latest SDK adopts an aligned architecture, with no extra dependencies, and offers enhanced stability for optimal performance.

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

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.

amplitude = Amplitude(
        migrateLegacyData = false,
Configuration configuration = new Configuration("AMPLITUDE_API_KEY", getApplicationContext());

Amplitude amplitude = new Amplitude(configuration);

Was this page helpful?