Kotlin Android (Beta)

Amplitude Kotlin Android SDK

Maven CentralMaven Central

With Kotlin Android SDK, you can send events to our Analytics service or any other analytics or marketing tool.

This library is open-source, feel free to check it out on GitHub.

Getting Started

1. Add dependencies

  • We recommend using Android Studio as an IDE and Gradle to manage dependencies.
  • In build.gradle file, please add the following dependencies.
dependencies {
  implementation 'com.amplitude:analytics-android:0.1.0-beta.5'
}
  • Sync project with gradle files.

2. Add permissions

To report events to Amplitude, add the INTERNET permission to your AndroidManifest.xml file.
<uses-permission android:name="android.permission.INTERNET" />

For Android 6.0 (Marshmallow) and above, explicitly add the READ_PHONE_STATE permission to fetch phone related information.
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

The SDK internally uses a number of Java 8 language APIs through desugaring. Make sure your project either enables desugaring) or requires a minimum API level of 26.

Usage

Initializing SDK

Initialization is necessary before any instrumentation is done. The API key for your Amplitude project is required. Optionally, a config object can be passed in this call. The SDK can be used anywhere after it is initialized anywhere in an application.

val amplitude = Amplitude(
  Configuration(
    apiKey = AMPLITUDE_API_KEY,
    context = applicationContext
  )
)

Tracking an Event

Events represent how users interact with your application. For example, “Button Clicked” may be an action you want to note.

// Track a basic event
amplitude.track("Button Clicked")

// Track events with optional properties
amplitude.track(
  "Button Clicked",
  mapOf("buttonColor" to "primary")
)

User Properties

User properties help you understand your users at the time they performed some action within your app such as their device details, their preferences, or language.

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. The operations are declared via a provided Identify interface. Multiple operations can be chained together in a single Identify object. The Identify object is then passed to the Amplitude client to send to the server.

🚧

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

Setting a User Property

The Identify object provides controls over setting user properties. An Identify object must first be instantiated, then Identify methods can be called on it, and finally the client will make a call with the Identify object.

val identify = Identify()
amplitude.identify(identify)

Identify.set

This method sets the value of a user property. For example, you can set a role property of a user.

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

Identify.setOnce

This method sets the value of a user property only once. Subsequent calls using setOnce will be ignored. For example, you can set an initial login method for a user and since only the initial value is tracked, setOnce ignores subsequent calls.

val identify = Identify()
identify.setOnce("initial-location", "SFO")
amplitude.identify(identify)

Identify.add

This method increments a user property by some numerical value. If the user property does not have a value set yet, it will be initialized to 0 before being incremented. For example, you can track a user's travel count.

val identify = Identify()
identify.add("travel-count", 1)
amplitude.identify(identify)

Arrays in User Properties

Arrays can be used as user properties. You can directly set arrays or use prepend, append, preInsert and postInsert to generate an array.

Identify.prepend

This method prepends a value or values to a user property array. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are prepended.

val identify = Identify()
identify.prepend("visited-locations", "LAX")
amplitude.identify(identify)

Identify.append

This method appends a value or values to a user property array. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are prepended.

val identify = Identify()
identify.append("visited-locations", "SFO")
amplitude.identify(identify)

Identify.preInsert

This method pre-inserts a value or values to a user property, if it does not exist in the user property yet. Pre-insert means inserting the value(s) at the beginning of a given list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are pre-inserted. If the user property has an existing value, it will be no operation.

val identify = Identify()
identify.preInsert("unique-locations", "LAX")
amplitude.identify(identify)

Identify.postInsert

This method post-inserts a value or values to a user property, if it does not exist in the user property yet. Post-insert means inserting the value(s) at the end of a given list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are post-inserted. If the user property has an existing value, it will be no operation.

val identify = Identify()
identify.postInsert("unique-locations", "SFO")
amplitude.identify(identify)

User Groups

📘

This feature is only available for Growth customers who have purchased the Accounts add-on.

Amplitude supports assigning users to groups and performing queries such as Count by Distinct on those groups. An example would be if you want to group your users based on what organization they are in by using an 'orgId'. You can designate Joe to be in 'orgId' '10' while Sue is in 'orgId' '15'. When performing a query in our Event Segmentation chart, you can then select "..performed by" 'orgId' to query the number of different organizations that have performed a specific event. As long as at least one member of that group has performed the specific event, that group will be included in the count.

When setting groups, you will need to define a groupType and groupName(s). In the above example, 'orgId' is the groupType and the values '10' and '15' are groupName(s). Another example of a groupType could be 'sport' with groupName(s) like 'tennis' and 'baseball'. You can use setGroup() to designate which groups a user belongs to. Note: This will also set the 'groupType:groupName' as a user property. This will overwrite any existing groupName value set for that user's groupType, as well as the corresponding user property value. groupType is a string and groupName can be either a string or an array of strings to indicate a user being in multiple groups (for example, if Joe is in 'orgId' '10' and '16', then the groupName would be '[10, 16]'). Here is what your code might look like.

// set group with single group name
amplitude.setGroup("orgId", "15");

// set group with multiple group names
amplitude.setGroup("orgId", arrayOf("15", "21"))

Group Identify

(Enterprise only) This feature is only available to Growth and Enterprise customers who have purchased the Accounts add-on.

Use the Group Identify API to set or update properties of particular groups. However, these updates will only affect events going forward.

The groupIdentify method accepts a group type string parameter and group name object parameter, as well as an Identify object that will be applied to the group.

val groupType = "orgId"
val groupName = "15"

val identify = Identify().set("locale", "en-us")
amplitude.groupIdentify(groupType, groupName, identify)

Revenue Tracking

The preferred method of tracking revenue for a user is to use revenue() in conjunction with the provided Revenue interface. Revenue instances will store each revenue transaction and allow you to define several special revenue properties (such as 'revenueType', 'productIdentifier', etc.) that are used in Amplitude's Event Segmentation and Revenue LTV charts. These Revenue instance objects are then passed into revenue to send as revenue events to Amplitude. This allows us to automatically display data relevant to revenue in the platform. You can use this to track both in-app and non-in-app purchases.

To track revenue from a user, call revenue each time a user generates revenue. For example, 3 units of a product was purchased at $3.99.

val revenue = Revenue()
revenue.productId = "com.company.productId"
revenue.price = 3.99
revenue.quantity = 3
amplitude.revenue(revenue)

Revenue Interface

NameTypeDescriptionDefault
productId (optional)stringAn identifier for the product. We recommend something like the Google Play Store product ID.null
quantity (required)intThe quantity of products purchased. Note: revenue = quantity * price1
price (required)DoubleThe price of the products purchased, and this can be negative. Note: revenue = quantity * pricenull
revenueType (optional, required for revenue verification)StringThe type of revenue (e.g. tax, refund, income).null
receipt (optional)StringThe type of revenue (e.g. tax, refund, income).null
receiptSignature (optional, required for revenue verification)StringThe type of revenue (e.g. tax, refund, income).null
eventProperties (optional)JSONObjectAn object of event properties to include in the revenue event.null

Did this page help you?