The [Ampli Wrapper](/docs/sdks/ampli) is a generated, strongly typed API for tracking Analytics events based on your Tracking Plan in Amplitude Data. The tracking library exposes a function for every event in your team's tracking plan. The function's arguments correspond to the event's properties. Ampli provides autocompletion for events and properties defined in Data and enforces your event schemas in code to prevent bad instrumentation. ## Quick start 1. [(Prerequisite) Create a Tracking Plan in Amplitude Data](/docs/data/create-tracking-plan) Plan your events and properties in [Amplitude Data](https://data.amplitude.com/). 1. [Install the Amplitude SDK](#install-the-amplitude-sdk) ```kotlin implementation 'com.amplitude:analytics-android:1.+' ``` 1. [Install the Ampli CLI](#install-the-ampli-cli) ```bash npm install -g @amplitude/ampli ``` 1. [Pull the Ampli Wrapper into your project](#pull) ```bash ampli pull [--path ./app/src/main/java/com/amplitude/ampli] ``` 1. [Initialize the Ampli Wrapper](#load) ```kotlin import com.amplitude.ampli.* ampli.load(appContext, LoadOptions( client = LoadClientOptions(apiKey = AMPLITUDE_API_KEY) )) ``` 1. [Identify users and set user properties](#identify) ```kotlin ampli.identify(userId, Identify( userProp = "A trait associated with this user" )) ``` 1. [Track events with strongly typed methods and classes](#track) ```kotlin ampli.songPlayed(songId = "song-1") ampli.track(SongFavorited(songId = "song-2")) ``` 1. [Flush events before application exit](#flush) ```kotlin ampli.flush(); ``` 1. [Verify implementation status with CLI](#status) ```bash ampli status [--update] ``` ## Install the Amplitude SDK If you haven't already, install the core Amplitude SDK dependencies. ```kotlin implementation 'com.amplitude:analytics-android:1.+' ``` {% callout type="note" heading="" %} If you're not already requesting the [INTERNET permission](https://developer.android.com/reference/android/Manifest.permission#INTERNET), add `` to your AndroidManifest.xml. {% /callout %} ## Install the Ampli CLI You can install the Ampli CLI from Homebrew or npm. {% code-group %} ```bash brew brew tap amplitude/ampli brew install ampli ``` ```bash npm npm install -g @amplitude/ampli ``` {% /code-group %} ### Pull the Ampli Wrapper into your project Run the Ampli CLI `pull` command to log in to Amplitude Data and download the strongly typed Ampli Wrapper for your tracking plan. Run Ampli CLI commands from the project root directory. ```bash ampli pull ``` ## API Ampli generates a thin facade over the Amplitude SDK that provides convenience methods. The Ampli Wrapper also grants access to every method of the underlying Amplitude SDK through `ampli.client`. For more details, refer to [Wrapping the Amplitude SDK](/docs/sdks/ampli#wrapping-the-amplitude-sdk). ### Load Initialize Ampli in your code. The `load()` method accepts configuration option arguments: {% code-group %} ```kotlin Kotlin import com.amplitude.ampli.* ampli.load(appContext, LoadOptions( client = LoadClientOptions(apiKey = AMPLITUDE_API_KEY) )) ``` ```java Java import com.amplitude.ampli.*; Ampli.getInstance().load(this, new LoadOptions() .setClient(new LoadClientOptions().setApiKey(AMPLITUDE_API_KEY)) ); ``` {% /code-group %} | Arg | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `appContext` | An object with a set of properties to add to every event the Ampli Wrapper sends. This option applies when at least one source template links to your team's tracking plan. | | `LoadOptions` | Required. Specifies configuration options for the Ampli Wrapper. | | `disabled` | Optional. Specifies whether the Ampli Wrapper does any work. When true, all calls to the Ampli Wrapper are no-ops. Useful in local or development environments. | | `client.instance` | Required if `client.apiKey` isn't set. Specifies an Amplitude instance. By default, Ampli creates an instance for you. | | `client.apiKey` | Required if `client.instance` isn't set. Specifies an API Key. This option overrides the default, which is the API Key configured in your tracking plan. | | `client.configuration` | Optional. Specifies the Amplitude configuration. This option overrides the default configuration. | ### Identify Call `identify()` to identify a user in your app and associate all future events with their identity, or to set their properties. Just as Ampli creates types for events and their properties, it creates types for user properties. The `identify()` function accepts an optional `userId`, optional user properties, and optional `options`. For example your tracking plan contains a user property called `userProp`. The property's type is a string. {% tabs tabs="Kotlin, Java" %} {% tab name="Kotlin" %} ```kotlin ampli.identify(userId, Identify( userProp = "A trait associated with this user" )) ``` {% /tab %} {% tab name="Java" %} ``` Ampli.getInstance().identify(userId, Identify.builder() .userProp("A trait associated with this user") .build() ); ``` {% /tab %} {% /tabs %} The `options` argument lets you pass [Amplitude fields](/docs/apis/analytics/http-v2#event-array-keys) for this call, such as `deviceId`. {% code-group %} ```kotlin Kotlin val eventOptions = EventOptions(); eventOptions.deviceId = "device-id"; ampli.identify( userId, Identify( userProp = "A trait associated with this user", ), eventOptions ) ``` ```java Java EventOptions eventOptions = new EventOptions(); eventOptions.setDeviceId("deviceId"); Ampli.getInstance().identify( userId, Identify.builder().userProp("A trait associated with this user").build(), eventOptions ); ``` {% /code-group %} ### Group identify Call `groupIdentify()` to identify a group in your app and set or update group properties. Just as Ampli creates types for events and their properties, Ampli creates types for group properties. The `groupIdentify()` function accepts a string `group_type`, a string `group_name`, a Group event instance, and an optional `EventOptions`. For example, your tracking plan contains a group `test group:android-java-ampli` with a property called `requiredBoolean` of type boolean. {% code-group %} ```kotlin Kotlin ampli.groupIdentify("test group", "android-kotlin-ampli", Group(requiredBoolean = true)) ``` ```java Java Ampli.getInstance().groupIdentify("test group", "android-java-ampli", Group.builder() .requiredBoolean(true) .build() ); ``` {% /code-group %} ### Group Call `setGroup()` to associate a user with their group (for example, their department or company). The `setGroup()` function accepts a required `groupType`, and `groupName` and an optional EventOptions. {% code-group %} ```kotlin Kotlin ampli.client?.setGroup("groupType", "groupName") ``` ```java Java Ampli.getInstance().getClient().setGroup("groupType", "groupName"); ``` {% /code-group %} 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 performs the specific event, the count includes the group. For example, you want to group users by organization 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 you set 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` is `sport` with `groupName` values like `tennis` and `baseball`. Setting a group also sets `groupType:groupName` as a user property and overwrites any existing `groupName` value for that user's `groupType`. `groupType` is a string. `groupName` can be a string or an array of strings to show that a user belongs to multiple groups. For example, if Joe is in `orgId` `10` and `20`, then `groupName` is `[10, 20]`. Your code might look like this: {% code-group %} ```kotlin Kotlin ampli.client?.setGroup("orgId", arrayOf("10", "20")) ``` ```java Java Ampli.getInstance().getClient().setGroup("orgID", new String[]{"10", "20"}); ``` {% /code-group %} ### Track To track an event, call the event's corresponding function. Every event in your tracking plan has its own function in the Ampli Wrapper. The call uses this structure: {% code-group %} ```kotlin Kotlin ampli.eventName(...eventNameProperties) ``` ```java Java Ampli.getInstance().eventName(EventName event, EventOptions options) ``` {% /code-group %} The `options` argument lets you pass [Amplitude fields](/docs/apis/analytics/http-v2#event-array-keys), like `deviceID`. For example, in the following code snippets, your tracking plan contains an event called `songPlayed`. The event has two required properties: `songId` and `songFavorited`. The property type for `songId` is string, and `songFavorited` is a boolean. {% code-group %} ```kotlin Kotlin ampli.songPlayed( songId = "songId", // String, songFavorited = true, // Boolean ) ``` ```java Java Ampli.getInstance().songPlayed(SongPlayed.builder() .songId("songId") // String .songFavorited(true) // Boolean .build() ); ``` {% /code-group %} Ampli also generates a class for each event. {% code-group %} ```kotlin Kotlin val myEventObject = SongPlayed( songId = "songId", // String, songFavorited = true, // Boolean ); ``` ```java Java SongPlayed event = SongPlayed.builder() .songId("songId") // String .songFavorited(true) // Boolean .build() ``` {% /code-group %} Send event objects using the generic track method. {% code-group %} ```kotlin Kotlin val options = EventOptions() options.userId = "user_id" ampli.track(SongPlayed( songId = "songId", // String songFavorited = true, // Boolean ), options); ``` ```java Java EventOptions options = new EventOptions(); options.setUserId("user-id"); Ampli.getInstance().track(SongPlayed.builder() .songId("songId") // String .songFavorited(true) // Boolean .build(), options); ``` {% /code-group %} ### Flush The Ampli Wrapper queues events and sends them on an interval based on the configuration. Call `flush()` to send any pending events immediately. The `flush()` method returns a promise you can use to ensure Ampli sends all pending events before continuing. Call `flush()` before the application exits to avoid losing queued events. Ampli flushes events in the buffer automatically when the queue reaches `flushQueueSize` or the timer reaches `flushInterval`. ```kotlin ampli.flush() ``` ### Plugin Plugins let you extend Amplitude behavior. For example, you can modify event properties (enrichment type) or send to third-party APIs (destination type). First, define your plugin. The following code shows a Destination Plugin example. {% code-group %} ```kotlin Kotlin class SegmentDestinationPlugin(appContext: Context, segmentApiKey: String) : DestinationPlugin() { var analytics: Analytics? = null; val context: Context = appContext; init { analytics = Analytics.Builder(appContext, segmentApiKey).build() } override fun track(event: BaseEvent): BaseEvent { val eventProperties = Properties(); event.eventProperties?.forEach { entry -> entry.value?.let { eventProperties.put(entry.key, it) } } analytics?.track(event.eventType, eventProperties); return event } } ``` ```java Java public class SegmentDestinationPlugin extends DestinationPlugin { android.content.Context context; Analytics analytics; String SEGMENT_API_KEY; public SegmentDestinationPlugin(android.content.Context appContext, String segmentAPIKey) { this.context = appContext; this.SEGMENT_WRITE_KEY = segmentWriteKey; } @Override public void setup(Amplitude amplitude) { super.setup(amplitude); analytics = new Analytics.Builder(this.context, SEGMENT_API_KEY) .build(); Analytics.setSingletonInstance(analytics); } @Override public BaseEvent track(BaseEvent event) { Properties properties = new Properties(); for (Map.Entry entry : event.getEventProperties().entrySet()) { properties.putValue(entry.getKey(),entry.getValue()); } analytics.track(event.eventType, properties); return event; } } ``` {% /code-group %} Add your plugin after you initialize Ampli. {% code-group %} ```kotlin Kotlin ampli.client?.add( YourDestinationPlugin(this, DESTINATION_API_KEY) ) ``` ```java Java Ampli.getInstance().getClient().add( new YourDestinationPlugin(this, DESTINATION_API_KEY) ); ``` {% /code-group %} ## Ampli CLI ### Pull The `pull` command downloads the Ampli Wrapper code to your project. Run the `pull` command from the project root. ```bash ampli pull ``` Log in to your workspace when prompted and select a source. ```bash ➜ ampli pull Ampli project is not initialized. No existing `ampli.json` configuration found. ? Create a new Ampli project here? Yes ? Organization: Amplitude ? Workspace: My Workspace ? Source: My Source ``` Learn more about [`ampli pull`](/docs/sdks/ampli/ampli-cli#pull). ### Status Verify that events exist in your code with the status command: ```bash ampli status [--update] ``` The output displays status and indicates which events are missing. ```bash ➜ ampli status ✘ Verifying event tracking implementation in source code ✔ Song Played (1 location) ✘ Song Stopped Called when a user stops playing a song. Events Tracked: 1 missed, 2 total ``` Learn more about [`ampli status`](/docs/sdks/ampli/ampli-cli#status).