Android Kotlin SDK
The Kotlin Android SDK lets you send events to Amplitude. This library is open-source, check it out on GitHub.
Android SDK Resources
Ampli Wrapper versus the Amplitude SDK
The Ampli Wrapper is an autogenerated library based on your pre-defined tracking plan. This is a lightweight wrapper over the Amplitude SDK that provides type safety, automatic code completion, linting, and schema validation. The generated code replicates the spec in the Tracking Plan and enforces its rules and requirements. This guide is about the Amplitude SDK. To learn more about Ampli Wrapper, see Ampli Wrapper Overview and examples. Click here for more documentation on Ampli for Android.
Migration guide
This is the documentation for the latest Amplitude SDK. If you are using the maintenance SDK, refer to the migration documentation: Android SDK Migration Guide.
SDK bundle size
You can get the SDK bundle size by checking Maven repository. Select the version you are using and you can find the size in the "Files" row after selecting "Amplitude Android Kotlin SDK".
Minimum version
For the minimum supported SDK version of this package, see build.gradle
on GitHub.
Getting started¶
Use this quickstart guide to get started with Amplitude Android Kotlin SDK.
Usage¶
Configuration¶
Configuration Options
Name |
Description | Default Value |
---|---|---|
flushIntervalMillis |
Int . The amount of time SDK will attempt to upload the unsent events to the server or reach flushQueueSize threshold. The value is in milliseconds. |
30000 |
flushQueueSize |
Int . SDK will attempt to upload once unsent event count exceeds the event upload threshold or reach flushIntervalMillis interval. |
30 |
flushMaxRetries |
Int . Maximum retry times. |
5 |
minIdLength |
Int . The minimum length for user id or device id. |
5 |
partnerId |
Int . The partner id for partner integration. |
null |
identifyBatchIntervalMillis |
Long . The amount of time SDK will attempt to batch intercepted identify events. The value is in milliseconds |
30000 |
flushEventsOnClose |
Boolean . Flushing of unsent events on app close. |
true |
callback |
EventCallBack . Callback function after event sent. |
null |
optOut |
Boolean . Opt the user out of tracking. |
false |
trackingSessionEvents |
Boolean . Deprecated. Automatic tracking of "Start Session" and "End Session" events that count toward event volume. |
false |
defaultTracking |
DefaultTrackingOptions . Options to control the default events tracking. |
Check Tracking default events |
minTimeBetweenSessionsMillis |
Long . The amount of time for session timeout. The value is in milliseconds. |
300000 |
serverUrl |
String . The server url events upload to. |
https://api2.amplitude.com/2/httpapi |
serverZone |
ServerZone.US or ServerZone.EU . The server zone to send to, will adjust server url based on this config. |
ServerZone.US |
useBatch |
Boolean Whether to use batch api. |
false |
useAdvertisingIdForDeviceId |
Boolean . Whether to use advertising id as device id. Please check here for required module and permission. |
false |
useAppSetIdForDeviceId |
Boolean . Whether to use app set id as device id. Please check here for required module and permission. |
false |
trackingOptions |
TrackingOptions . Options to control the values tracked in SDK. |
enable |
enableCoppaControl |
Boolean . Whether to enable COPPA control for tracking options. |
false |
instanceName |
String . The name of the instance. Instances with the same name will share storage and identity. For isolated storage and identity use a unique instanceName for each instance. |
$default_instance |
migrateLegacyData |
Boolean . Available in 1.9.0 +. Whether to migrate maintenance Android SDK data (events, user/device ID). Learn more here. |
true |
Configure batching behavior¶
To support high-performance environments, the SDK sends events in batches. Every event logged by the track
method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with flushQueueSize
and flushIntervalMillis
. By default, the serverUrl will be https://api2.amplitude.com/2/httpapi
. For customers who want to send large batches of data at a time, set useBatch
to true
to set setServerUrl
to batch event upload API https://api2.amplitude.com/batch
. Both the regular mode and the batch mode use the same events upload threshold and flush time intervals.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
flushIntervalMillis = 50000,
flushQueueSize = 20,
)
)
import com.amplitude.android.Amplitude;
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setFlushIntervalMillis(1000);
configuration.setFlushQueueSize(10);
Amplitude amplitude = new Amplitude(configuration);
You can dynamically set the configuration after initialization.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
)
)
amplitude.configuration.optOut = true
import com.amplitude.android.Amplitude;
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
Amplitude amplitude = new Amplitude(configuration);
amplitude.getConfiguration().setOptOut(true);
EU data residency¶
You can configure the server zone when initializing the client for sending data to Amplitude's EU servers. The SDK sends data based on the server zone if it's set.
Note
For EU data residency, the project must be set up inside Amplitude EU. You must initialize the SDK with the API key from Amplitude EU.
import com.amplitude.android.Amplitude
val amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
serverZone = ServerZone.EU
)
)
import com.amplitude.android.Amplitude;
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setServerZone(ServerZone.EU);
Amplitude amplitude = new Amplitude(configuration);
track¶
Events represent how users interact with your application. For example, "Song Played" may be an action you want to note.
amplitude.track("Song Played")
You can also optionally include event properties.
amplitude.track(
"Song Played",
mutableMapOf<String, Any?>("title" to "Happy Birthday")
)
For more complex events you can create and track a BaseEvent
object.
var event = BaseEvent()
event.eventType = "Song Played"
event.eventProperties = mutableMapOf<String, Any?>("title" to "Happy Birthday")
event.groups = mutableMapOf<String, Any?>("test-group-type" to "test-group-value")
event.insertId = 1234
amplitude.track(event)
identify¶
Identify is for setting the user properties of a particular user without sending any event. The SDK supports the operations set
, setOnce
, unset
, add
, append
, prepend
, preInsert
, postInsert
, and remove
on individual user properties. Declare the operations via a provided Identify interface. You can chain together multiple operations in a single Identify object. The Identify object is then passed to the Amplitude client to send to the server.
Starting from release v1.7.0, identify events with only set operations will be batched and sent with fewer events. This change won't affect running the set operations. There is a config identifyBatchIntervalMillis
managing the interval to flush the batched identify intercepts.
Note
If the Identify call is sent after the event, the results of operations will be visible immediately in the dashboard user's profile area, but it will not appear in chart result until another event is sent after the Identify call. So the identify call only affects events going forward. More details here.
You can handle the identity of a user using the identify methods. Proper use of these methods can connect events to the correct user as they move across devices, browsers, and other platforms. Send an identify call containing those user property operations to Amplitude server to tie a user's events with specific user properties.
val identify = Identify()
identify.set("color", "green")
amplitude.identify(identify)
Tracking default events¶
Starting from release v1.10.1, the SDK is able to track more default events now. It can be configured to track the following events automatically:
- Sessions 1
- App lifecycles
- Screen views
- Deep links
Tracking default events options
Name |
Type | Default Value | Description |
---|---|---|---|
config.defaultTracking.sessions |
Optional. boolean |
true |
Enables session tracking. This configuration replaces trackingSessionEvents . If value is true , Amplitude tracks session start and session end events.See Tracking sessions for more information. |
config.defaultTracking.appLifecycles |
Optional. boolean |
false |
Enables application lifecycle events tracking. If value is true , Amplitude tracks application installed, application updated, application opened, and application backgrounded events.Event properties tracked includes: [Amplitude] Version ,[Amplitude] Build ,[Amplitude] Previous Version , [Amplitude] Previous Build , [Amplitude] From Background See Tracking application lifecycles for more information. |
config.defaultTracking.screenViews |
Optional. boolean |
false |
Enables screen views tracking. If value is true , Amplitude tracks screen viewed events.Event properties tracked includes: [Amplitude] Screen Name See Tracking screen views for more information. |
config.defaultTracking.deepLinks |
Optional. boolean |
false |
Enables deep link tracking. If value is true , Amplitude tracks deep link opened events.Event properties tracked includes: [Amplitude] Link URL , [Amplitude] Link Referrer See Tracking deep links for more information. |
You can enable Amplitude to start tracking all events mentioned above, use the code sample below. Otherwise, you can omit the configuration to keep only session tracking enabled.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions.ALL
)
)
Note
Amplitude may add more events in a future version, and this configuration enables tracking for those events as well.
Similarly, you can disable Amplitude to track all events mentioned above with the code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions.NONE
)
)
You can also customize the tracking with DefaultTrackingOptions
, see code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
appLifecycles = true,
sessions = false,
deepLinks = true,
screenViews = false
)
)
)
Tracking sessions¶
You can enable Amplitude to start tracking session events by setting configuration.defaultTracking.sessions
to true
. Refer to the code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
sessions = true
)
)
)
For more information about session tracking, refer to User sessions.
Note
configuration.trackingSessionEvents
is deprecated and replaced with configuration.defaultTracking.sessions
.
Tracking application lifecycles¶
You can enable Amplitude to start tracking application lifecycle events by setting configuration.defaultTracking.appLifecycles
to true
. Refer to the code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
appLifecycles = true
)
)
)
After enabling this setting, Amplitude will track the following events:
[Amplitude] Application Installed
, this event fires when a user opens the application for the first time right after installation.[Amplitude] Application Updated
, this event fires when a user opens the application after updating the application.[Amplitude] Application Opened
, this event fires when a user launches or foregrounds the application after the first open.[Amplitude] Application Backgrounded
, this event fires when a user backgrounds the application.
Tracking screen views¶
You can enable Amplitude to start tracking screen view events by setting configuration.defaultTracking.screenViews
to true
. Refer to the code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
screenViews = true
)
)
)
After enabling this setting, Amplitude will track the [Amplitude] Screen Viewed
event with the screen name property. This property value is read from the activity label, application label, and activity name successively.
Tracking deep links¶
You can enable Amplitude to start tracking deep link events by setting configuration.defaultTracking.deepLinks
to true
. Refer to the code sample below.
Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
deepLinks = true
)
)
)
After enabling this setting, Amplitude will track the [Amplitude] Deep Link Opened
event with the URL and referrer information.
User groups¶
Feature availability
This feature is available in accounts with a Growth or Enterprise plan with the Accounts add-on.
Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, then the count includes the group.
For example, you want to group your users based on what organization they're in by using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.
When setting groups, define a groupType
and groupName
. In the previous example, 'orgId' is the groupType
and '10' and '15' are the values for groupName
. Another example of a groupType
could be 'sport' with groupName
values like 'tennis' and 'baseball'.
Setting a group also sets the groupType:groupName
as a user property, and overwrites any existing groupName
value set for that user's groupType, and the corresponding user property value. groupType
is a string, and groupName
can be either a string or an array of strings to indicate that a user is in multiple groups.
Example
If Joe is in 'orgId' '15', then the groupName
would be '15'.
// set group with a single group name
amplitude.setGroup("orgId", "15");
If Joe is in 'sport' 'tennis' and 'soccer', then the groupName
would be '["tennis", "soccer"]'.
// set group with multiple group names
amplitude.setGroup("sport", arrayOf("tennis", "soccer"))
You can also set event-level groups by passing an Event
Object with groups
to track
. With event-level groups, the group designation applies only to the specific event being logged, and doesn't persist on the user unless you explicitly set it with setGroup
.
val event = BaseEvent()
event.eventType = "event type"
event.eventProperties = mutableMapOf("event property" to "event property value")
event.groups = mutableMapOf("orgId" to "15")
amplitude.track(event)
Group identify¶
Feature availability
This feature is available in accounts with a Growth or Enterprise plan with the Accounts add-on.
Use the Group Identify API to set or update the properties of particular groups. Keep these considerations in mind:
- Updates affect only future events, and don't update historical events.
- You can track up to 5 unique group types and 10 total groups.
The groupIdentify
method accepts a group type string parameter and group name object parameter, and an Identify object that's applied to the group.
val groupType = "plan"
val groupName = "enterprise"
val identify = Identify().set("key", "value")
amplitude.groupIdentify(groupType, groupName, identify)
Track revenue¶
Amplitude can track revenue generated by a user. Revenue is tracked through distinct revenue objects, which have special fields that are used in Amplitude's Event Segmentation and Revenue LTV charts. This allows Amplitude to automatically display data relevant to revenue in the platform. Revenue objects support the following special properties, as well as user-defined properties through the eventProperties
field.
val revenue = Revenue()
revenue.productId = "com.company.productId"
revenue.price = 3.99
revenue.quantity = 3
amplitude.revenue(revenue)
Name |
Description |
---|---|
productId |
Optional. String. An identifier for the product. Amplitude recommends something like the Google Play Store product ID. Defaults to null . |
quantity |
Required. Integer. The quantity of products purchased. Note: revenue = quantity * price. Defaults to 1 |
price |
Required. Double. The price of the products purchased, and this can be negative. Note: revenue = quantity * price. Defaults to null . |
revenueType |
Optional, but required for revenue verification. String. The revenue type (for example, tax, refund, income). Defaults to null . |
receipt |
Optional. String. The receipt identifier of the revenue. For example, "123456". Defaults to null . |
receiptSignature |
Optional, but required for revenue verification. String. Defaults to null . |
Custom user ID¶
If your app has its login system that you want to track users with, you can call setUserId
at any time.
amplitude.setUserId("user@amplitude.com")
Custom device ID¶
You can assign a new device ID using deviceId
. When setting a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.
import java.util.UUID
amplitude.setDeviceId(UUID.randomUUID().toString())
Reset when user logs out¶
reset
is a shortcut to anonymize users after they log out, by:
- setting
userId
tonull
- setting
deviceId
to a new value based on current configuration
With an empty userId
and a completely new deviceId
, the current user would appear as a brand new user in dashboard.
amplitude.reset()
Amplitude SDK plugin¶
Plugins allow you to extend Amplitude SDK's behavior by, for example, modifying event properties (enrichment type) or sending to third-party APIs (destination type). A plugin is an object with methods setup()
and execute()
.
Plugin.setup¶
This method contains logic for preparing the plugin for use and has amplitude
instance as a parameter. The expected return value is null
. A typical use for this method, is to instantiate plugin dependencies. This method is called when the plugin is registered to the client via amplitude.add()
.
Plugin.execute¶
This method contains the logic for processing events and has event
instance as parameter. If used as enrichment type plugin, the expected return value is the modified/enriched event. If used as a destination type plugin, the expected return value is a map with keys: event
(BaseEvent), code
(number), and message
(string). This method is called for each event, including Identify, GroupIdentify and Revenue events, that's instrumented using the client interface.
Plugin examples¶
Enrichment type plugin¶
Here's an example of a plugin that modifies each event that's instrumented by adding extra event property.
import androidx.annotation.NonNull;
import androidx.annotation.Nullable;
import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.Plugin;
import java.util.HashMap;
public class EnrichmentPlugin implements Plugin {
public Amplitude amplitude;
@NonNull
@Override
public Amplitude getAmplitude() {
return this.amplitude;
}
@Override
public void setAmplitude(@NonNull Amplitude amplitude) {
this.amplitude = amplitude;
}
@NonNull
@Override
public Type getType() {
return Type.Enrichment;
}
@Nullable
@Override
public BaseEvent execute(@NonNull BaseEvent baseEvent) {
if (baseEvent.getEventProperties() == null) {
baseEvent.setEventProperties(new HashMap<String, Object>());
}
baseEvent.getEventProperties().put("custom android event property", "test");
return baseEvent;
}
@Override
public void setup(@NonNull Amplitude amplitude) {
this.amplitude = amplitude;
}
}
amplitude.add(new EnrichmentPlugin());
Destination type plugin¶
In destination plugin, you are able to overwrite the track(), identify(), groupIdentify(), revenue(), flush() functions.
import com.amplitude.core.Amplitude;
import com.amplitude.core.events.BaseEvent;
import com.amplitude.core.platform.DestinationPlugin;
import com.segment.analytics.Analytics;
import com.segment.analytics.Properties;
public class SegmentDestinationPlugin extends DestinationPlugin {
android.content.Context context;
Analytics analytics;
String writeKey;
public SegmentDestinationPlugin(android.content.Context appContext, String writeKey) {
this.context = appContext;
this.writeKey = writeKey;
}
@Override
public void setup(Amplitude amplitude) {
super.setup(amplitude);
analytics = new Analytics.Builder(this.context, this.writeKey)
.build();
Analytics.setSingletonInstance(analytics);
}
@Override
public BaseEvent track(BaseEvent event) {
Properties properties = new Properties();
for (Map.Entry<String,Object> entry : event.getEventProperties().entrySet()) {
properties.putValue(entry.getKey(),entry.getValue());
}
analytics.track(event.eventType, properties);
return event;
}
}
amplitude.add(
new SegmentDestinationPlugin(this, SEGMENT_WRITE_KEY)
)
Troubleshooting and Debugging¶
How to debug¶
Please ensure that the configuration and payload are accurate and check for any unusual messages during the debugging process. If everything appears to be right, check the value of flushQueueSize
or flushIntervalMillis
. Events are queued and sent in batches by default, which means they are not immediately dispatched to the server. Ensure that you have waited for the events to be sent to the server before checking for them in the charts.
Log¶
- Set the log level to debug to collect useful information during debugging. More details.
- Customize
loggerProvider
class from theLoggerProvider
and implement your own logic, such as logging error message in server in a production environment. More details.
Plugins¶
You can take advantage of a Destination Plugin to print out the configuration value and event payload before sending them to the server. You can set the logLevel to debug, copy the following TroubleShootingPlugin
into your project, add the plugin into amplitude instance.
Event Callback¶
The event callback will be executed after the event has been sent, for both successful and failed events. You can use this method to monitor the event status and message. Check how to set callback under configuration > callback.
Common Issues¶
Please refer to this document for additional common issues in general.
Advanced topics¶
User sessions¶
Amplitude starts a session when the app is brought into the foreground or when an event is tracked in the background. A session ends when the app remains in the background for more than the time set by setMinTimeBetweenSessionsMillis()
without any event being tracked. Note that a session will continue for the entire time the app is in the foreground no matter whether session tracking is enabled by configuration.trackingSessionEvents
or configuration.defaultTracking.sessions
or not.
When the app enters the foreground, Amplitude tracks a session start, and starts a countdown based on setMinTimeBetweenSessionsMillis()
. Amplitude extends the session and restarts the countdown any time it tracks a new event. If the countdown expires, Amplitude waits until the next event to track a session end event.
Amplitude doesn't set user properties on session events by default. To add these properties, use identify()
and setUserId()
. Amplitude aggregates the user property state and associates the user with events based on device_id
or user_id
.
Due to the way in which Amplitude manages sessions, there are scenarios where the SDK works expected but it may appear as if events are missing or session tracking is inaccurate:
- If a user doesn't return to the app, Amplitude does not track a session end event to correspond with a session start event.
- If you track an event in the background, it's possible that Amplitude perceives the session length to be longer than the user spends on the app in the foreground.
- If you modify user properties between the last event and the session end event, the session end event reflects the updated user properties, which may differ from other properties associated with events in the same session. To address this, use an enrichment plugin to set
event['$skip_user_properties_sync']
totrue
on the session end event, which prevents Amplitude from synchronizing properties for that specific event. See $skip_user_properties_sync in the Converter Configuration Reference article to learn more.
Amplitude groups events together by session. Events that are logged within the same session have the same session_id
. Sessions are handled automatically so you don't have to manually call startSession()
or endSession()
.
You can adjust the time window for which sessions are extended. The default session expiration time is 30 minutes.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
minTimeBetweenSessionsMillis = 10000
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setMinTimeBetweenSessionsMillis(1000);
Amplitude amplitude = new Amplitude(configuration);
By default, Amplitude automatically sends the '[Amplitude] Start Session' and '[Amplitude] End Session' events. Even though these events aren't sent, sessions are still tracked by using session_id
.
You can also disable those session events.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
defaultTracking = DefaultTrackingOptions(
sessions = false
)
)
)
defaultTrackingOptions = new DefaultTrackingOptions();
defaultTrackingOptions.setSessions(false);
amplitude = AmplitudeKt.Amplitude(AMPLITUDE_API_KEY, getApplicationContext(), configuration -> {
configuration.setDefaultTracking(defaultTrackingOptions);
return Unit.INSTANCE;
});
You can use the helper method getSessionId
to get the value of the current sessionId
.
val sessionId = amplitude.sessionId;
long sessionId = amplitude.getSessionId();
You can define your own session expiration time. The default session expiration time is 30 minutes.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
minTimeBetweenSessionsMillis = 10000
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setMinTimeBetweenSessionsMillis(10000);
Amplitude amplitude = new Amplitude(configuration);
Set custom user ID¶
If your app has its login system that you want to track users with, you can call setUserId
at any time.
amplitude.setUserId("USER_ID");
amplitude.setUserId("USER_ID");
Don't assign users a user ID that could change, because each unique user ID is a unique user in Amplitude. Learn more about how Amplitude tracks unique users in the Help Center.
Log level¶
You can control the level of logs that print to the developer console.
- 'INFO': Shows informative messages about events.
- 'WARN': Shows error messages and warnings. This level logs issues that might be a problem and cause some oddities in the data. For example, this level would display a warning for properties with null values.
- 'ERROR': Shows error messages only.
- 'DISABLE': Suppresses all log messages.
- 'DEBUG': Shows error messages, warnings, and informative messages that may be useful for debugging.
Set the log level by calling setLogLevel
with the level you want.
amplitude.logger.logMode = Logger.LogMode.DEBUG
amplitude.getLogger().setLogMode(Logger.LogMode.DEBUG);
Logged out and anonymous users¶
Amplitude merges user data, so any events associated with a known userId
or deviceId
are linked the existing user.
If a user logs out, Amplitude can merge that user's logged-out events to the user's record. You can change this behavior and log those events to an anonymous user instead.
To log events to an anonymous user:
- Set the
userId
to null. - Generate a new
deviceId
.
Events coming from the current user or device appear as a new user in Amplitude. Note: If you do this, you can't see that the two users were using the same device.
amplitude.reset()
amplitude.reset();
Disable tracking¶
By default the Android SDK tracks several user properties such as carrier
, city
, country
, ip_address
, language
, and platform
.
Use the provided TrackingOptions
interface to customize and toggle individual fields.
To use the TrackingOptions
interface, import the class.
import com.amplitude.android.TrackingOptions
import com.amplitude.android.TrackingOptions
Before initializing the SDK with your apiKey, create a TrackingOptions
instance with your configuration and set it on the SDK instance.
val trackingOptions = TrackingOptions()
trackingOptions.disableCity().disableIpAddress().disableLatLng()
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
trackingOptions = trackingOptions
)
)
TrackingOptions trackingOptions = new TrackingOptions();
trackingOptions.disableCity().disableIpAddress().disableLatLng();
// init instance
amplitude = AmplitudeKt.Amplitude(AMPLITUDE_API_KEY, getApplicationContext(), configuration -> {
configuration.setTrackingOptions(trackingOptions);
return Unit.INSTANCE;
});
Tracking for each field can be individually controlled, and has a corresponding method (for example, disableCountry
, disableLanguage
).
Method |
Description |
---|---|
disableAdid() |
Disable tracking of Google ADID |
disableCarrier() |
Disable tracking of device's carrier |
disableCity() |
Disable tracking of user's city |
disableCountry() |
Disable tracking of user's country |
disableDeviceBrand() |
Disable tracking of device brand |
disableDeviceModel() |
Disable tracking of device model |
disableDma() |
Disable tracking of user's designated market area (DMA). |
disableIpAddress() |
Disable tracking of user's IP address |
disableLanguage() |
Disable tracking of device's language |
disableLatLng() |
Disable tracking of user's current latitude and longitude coordinates |
disableOsName() |
Disable tracking of device's OS Name |
disableOsVersion() |
Disable tracking of device's OS Version |
disablePlatform() |
Disable tracking of device's platform |
disableRegion() |
Disable tracking of user's region. |
disableVersionName() |
Disable tracking of your app's version name |
Note
Using TrackingOptions
only prevents default properties from being tracked on newly created projects, where data has not yet been sent. If you have a project with existing data that you want to stop collecting the default properties for, get help in the Amplitude Community. Disabling tracking doesn't delete any existing data in your project.
Carrier¶
Amplitude determines the user's mobile carrier using Android's TelephonyManager networkOperatorName
, which returns the current registered operator of the tower
.
COPPA control¶
COPPA (Children's Online Privacy Protection Act) restrictions on IDFA, IDFV, city, IP address and location tracking can all be enabled or disabled at one time. Apps that ask for information from children under 13 years of age must comply with COPPA.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
enableCoppaControl = true //Disables ADID, city, IP, and location tracking
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
//Disables ADID, city, IP, and location tracking
configuration.setEnableCoppaControl(true);
Amplitude amplitude = new Amplitude(configuration);
Advertiser ID¶
The Android Advertising ID is a unique identifier provided by the Google Play store. As it's unique to every person and not just their devices, it's useful for mobile attribution. This is similar to the IDFA on iOS. Mobile attribution is the attribution of an installation of a mobile app to its original source (such as ad campaign, app store search). Users can choose to disable the Advertising ID, and apps targeted to children can't track at all.
Follow these steps to use Android Ad ID.
Google Ad ID and Tracking Warning
As of April 1, 2022, Google allows users to opt out of Ad ID tracking. Ad ID may return null or error. You can use am alternative ID called App Set ID, which is unique to every app install on a device. Learn more.
-
Add
play-services-ads-identifier
as a dependency.dependencies { implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1' }
-
AD_MANAGER_APP
Permission If you use Google Mobile Ads SDK version 17.0.0 or higher, you need to addAD_MANAGER_APP
toAndroidManifest.xml
.<manifest> <application> <meta-data android:name="com.google.android.gms.ads.AD_MANAGER_APP" android:value="true"/> </application> </manifest>
-
Add ProGuard exception
Amplitude Android SDK uses Java Reflection to use classes in Google Play Services. For Amplitude SDKs to work in your Android application, add these exceptions to
proguard.pro
for the classes fromplay-services-ads
.-keep class com.google.android.gms.ads.** { *; }
-
AD_ID
PermissionWhen apps update their target to Android 13 or above will need to declare a Google Play services normal permission in the manifest file as follows if you are trying to use the ADID as a deviceId:
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>
Learn More at here.
Set advertising ID as device ID¶
After you set up the logic to fetch the advertising ID, you can enable useAdvertisingIdForDeviceId
to use advertising id as the device ID.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
useAdvertisingIdForDeviceId = true
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setUseAdvertisingIdForDeviceId(true);
Amplitude amplitude = new Amplitude(configuration);
App set ID¶
App set ID is a unique identifier for each app install on a device. App set ID is reset by the user manually when they uninstall the app, or after 13 months of not opening the app. Google designed this as a privacy-friendly alternative to Ad ID for users who want to opt out of stronger analytics.
To use App Set ID, follow these steps.
-
Add
play-services-appset
as a dependency. For versions earlier than 2.35.3, use'com.google.android.gms:play-services-appset:16.0.0-alpha1'
dependencies { implementation 'com.google.android.gms:play-services-appset:16.0.2' }
-
Enable to use app set ID as Device ID.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
useAppSetIdForDeviceId = true
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setUseAppSetIdForDeviceId(true);
Amplitude amplitude = new Amplitude(configuration);
Device ID lifecycle¶
The SDK initializes the device ID in the following order, with the device ID being set to the first valid value encountered:
- Device ID of the instance
- ADID if
useAdvertisingIdForDeviceId
is enabled and required module is installed. Learn more - App Set ID with an “S” appended if
useAppSetIdForDeviceId
is enabled and required module is installed. Learn more - A randomly generated UUID with an "R" appended
One user with multiple devices¶
A single user may have multiple devices, each having a different device ID. To ensure coherence, set the user ID consistently across all these devices. Even though the device IDs differ, Amplitude can still merge them into a single Amplitude ID, thus identifying them as a unique user.
Transfer to a new device¶
It's possible for multiple devices to have the same device ID when a user switches to a new device. When transitioning to a new device, users often transfer their applications along with other relevant data. The specific transferred content may vary depending on the application. In general, it includes databases and file directories associated with the app. However, the exact items included depend on the app's design and the choices made by the developers. If databases or file directories have been backed up from one device to another, the device ID stored within them may still be present. Consequently, if the SDK attempts to retrieve it during initialization, different devices might end up using the same device ID.
Get device ID¶
You can use the helper method getDeviceId()
to get the value of the current deviceId
.
val deviceId = amplitude.getDeviceId();
String deviceId = amplitude.getDeviceId();
To set the device, refer to custom device ID.
Location tracking¶
Amplitude converts the IP of a user event into a location (GeoIP lookup) by default. This information may be overridden by an app's own tracking solution or user data.
By default, Amplitude can use Android location service (if available) to add the specific coordinates (longitude and latitude) for the location from which an event is logged. Control this behavior by enable / disable location listening during the initialization.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
locationListening = true
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setLocationListening(true);
Amplitude amplitude = new Amplitude(configuration);
ProGuard obfuscation
If you use ProGuard obfuscation, add the following exception to the file:
-keep class com.google.android.gms.common.** { *; }
Opt users out of tracking¶
Users may wish to opt out of tracking entirely, which means Amplitude doesn't track any of their events or browsing history. OptOut
provides a way to fulfill a user's requests for privacy.
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
optOut = true
)
)
Configuration configuration = new Configuration(AMPLITUDE_API_KEY, getApplicationContext());
configuration.setOptOut(true);
Amplitude amplitude = new Amplitude(configuration);
Push notification events¶
Don't send push notification events client-side via the Android SDK. Because a user must open the app to initialize the Amplitude SDK in order for the SDK to send the event, events aren't sent to the Amplitude servers until the next time the user opens the app. This can cause data delays.
You can use mobile marketing automation partners or the HTTP API V2 to send push notification events to Amplitude.
Set log callback¶
Implements a customized loggerProvider
class from the LoggerProvider, and pass it in the configuration during the initialization to help with collecting any error messages from the SDK in a production environment.
import com.amplitude.common.Logger
import com.amplitude.core.LoggerProvider
class sampleLogger : Logger {
override var logMode: Logger.LogMode
get() = Logger.LogMode.DEBUG
set(value) {}
override fun debug(message: String) {
TODO("Handle debug message here")
}
override fun error(message: String) {
TODO("Handle error message here")
}
override fun info(message: String) {
TODO("Handle info message here")
}
override fun warn(message: String) {
TODO("Handle warn message here")
}
}
class sampleLoggerProvider : LoggerProvider {
override fun getLogger(amplitude: com.amplitude.core.Amplitude): Logger {
return sampleLogger()
}
}
amplitude = Amplitude(
Configuration(
apiKey = AMPLITUDE_API_KEY,
context = applicationContext,
loggerProvider = sampleLoggerProvider()
)
)
import com.amplitude.common.Logger;
import com.amplitude.core.LoggerProvider;
class sampleLogger implements Logger {
@NonNull
@Override
public LogMode getLogMode() {
return LogMode.DEBUG;
}
@Override
public void setLogMode(@NonNull LogMode logMode) {
// TODO("Handle debug message here")
}
@Override
public void debug(@NonNull String message) {
// TODO("Handle debug message here")
}
@Override
public void error(@NonNull String message) {
// TODO("Handle error message here")
}
@Override
public void info(@NonNull String message) {
// TODO("Handle info message here")
}
@Override
public void warn(@NonNull String message) {
// TODO("Handle warn message here")
}
}
class sampleLoggerProvider implements LoggerProvider {
@NonNull
@Override
public Logger getLogger(@NonNull com.amplitude.core.Amplitude amplitude) {
return new sampleLogger();
}
}
Multiple Instances¶
It is possible to create multiple instances of Amplitude. Instances with the same instanceName
will share storage and identity. For isolated storage and identity use a unique instanceName
for each instance. For more details see Configuration.
val amplitude1 = Amplitude(Configuration(
instanceName = "one",
apiKey = "api-key-1",
context = applicationContext,
))
val amplitude2 = Amplitude(Configuration(
instanceName = "two",
apiKey = "api-key-2",
context = applicationContext,
))
-
Session tracking is the same as supported in previous versions, which was previously enabled/disabled via the
trackingSessionEvents
configuration. ↩