JRE Java SDK

This is the documentation for the Amplitude Analytics Java SDK.

Install the SDK

1dependencies {
2    implementation 'org.json:json:20201115'
3    implementation 'com.amplitude:java-sdk:1.+'
4}

Import the SDK

Import Amplitude into any file that uses it. Amplitude uses the open source JSONObject library to conveniently create JSON key-value objects.

1import com.amplitude.Amplitude;
2import org.json.JSONObject;

Initialize the SDK

You must initialize the SDK before any events are instrumented. The API key for your Amplitude project is required.

1Amplitude client = Amplitude.getInstance();
2client.init(AMPLITUDE_API_KEY);

Amplitude.getInstance(String name) may optionally take a name which uniquely holds settings.

1Amplitude client = Amplitude.getInstance("YOUR_INSTANCE_NAME");
2client.init(AMPLITUDE_API_KEY);

Configure the SDK

Options

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. Every event logged by logEvent method is queued in memory. Events are flushed in batches in background. You can customize batch behavior with setEventUploadThreshold and setEventUploadPeriodMillis. By default, the SDK is in regular mode with serverUrl to https://api2.amplitude.com/2/httpapi. For customers who want to send large batches of data at a time, switch to batch mode by setting useBatchMode 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 flush queue size and flush intervals.

 1Amplitude client = Amplitude.getInstance();
 2// Events queued in memory will flush when number of events exceed upload threshold
 3// Default value is 10
 4client.setEventUploadThreshold(20);
 5 
 6// Events queue will flush every certain milliseconds based on setting
 7// Default value is 10,000 milliseconds
 8client.setEventUploadPeriodMillis(5000);
 9 
10// Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
11client.useBatchMode(true);

You can also flush events on demand.

1client.flushEvents();

For customers who want to send large batches of data at a time, for example through scheduled jobs, rather than in a continuous real-time stream, Amplitude provides the batch mode.

Both the regular mode and the batch mode use the same events upload threshold and flush time intervals. The batch mode allows larger payload size (20MB) and has a higher throttling limit.

Due to the higher rate of data that's permitted by this mode, data sent by batch mode may be delayed based on load. You can see a usage example in this project on GitHub.

1// Enable batch mode
2client.useBatchMode(true);
3 
4// Disable batch mode
5client.useBatchMode(false);

Configure a custom HTTP proxy

New in version 1.9.0. Set and unset custom proxy for HTTP requests.

1// Set proxy for http requests
2client.setProxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.domain.com", port)));
3 
4// Unset proxy
5client.setProxy(Proxy.NO_PROXY);

Configure a custom logger

New in version 1.10.0. Set a customized logger for the Amplitude client.

1// Set logger
2client.setLogger(new AmplitudeLog() {
3  @Override
4  public void log(String tag, String message, LogMode messageMode) {
5    if (messageMode.level >= logMode.level) {
6      // implement using custom logging framework and format
7    }
8  }
9});

Configure minIdLength and header

Amplitude Java SDK supports customizing the min length of ID and header on the version later than 1.7.0.

1// Set logger
2client.setOptions(new Options()
3      .addHeader("Custom Header", "value")
4      .setMinIdLength(5));

Configure event flushing and thread timeout

New in version 1.10.0. Set events flushing thread timeout in milliseconds. If set to a positive long integer, events flushing tasks time out and trigger callbacks for those events.

1client.setFlushTimeout(2000L); // 2 seconds

Shutdown client and release resource

New in version 1.10.0. Stops the Amplitude client from accepting new events and shuts down the threads pool. Events in the buffer trigger callbacks. A new instance is created and returned if you call Amplitude.getInstance(INSTANCE_NAME) with the same instance name.

1client.shutdown();

Send events

Events represent how users interact with your application. For example, "Button Clicked" may be an action you want to track. In Java, logEvent only accepts an event object. See the HTTP V2 API for available event object keys.

1Amplitude client = Amplitude.getInstance();
2client.logEvent(new Event("Button Clicked", "test_user_id"));

Events with properties

Events can also contain properties. They provide context about the event taken. For example, "hover time" may be a relevant event property to "button click."

1JSONObject eventProps = new JSONObject()
2    .put("Hover Time", 10)
3    .put("prop_2", "value_2");
4 
5Event event = new Event("Button Clicked", userId);
6event.eventProperties = eventProps;
7 
8client.logEvent(event);

Events witih groups

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.

1JSONObject groups = new JSONObject();
2groups.put("orgId", 10);
3 
4Event setGroupEvent = new Event("$identify", userId);
5setGroupEvent.groups = groups;
6setGroupEvent.userProperties = groups;
7client.logEvent(setGroupEvent);

1JSONObject groups = new JSONObject();
2groups.put("sport", new String[] {"tennis", "soccer"});
3 
4Event setGroupsEvent = new Event("$identify", userId);
5setGroupsEvent.groups = groupProps;
6setGroupsEvent.userProperties = groups;
7 
8client.logEvent(setGroupsEvent);

You can also use logEvent to set event-level groups. With event-level groups, the group designation applies only to the specific event being logged, and doesn't persist on the user.

1JSONObject groups = new JSONObject();
2groups.put("orgId", 10);
3 
4Event event = new Event('event type', userId);
5event.groups = groups;
6 
7client.logEvent(event);

After setting groups, you can then set or update the properties of particular groups. However, these updates will only affect events going forward.

 1JSONObject groups = new JSONObject()
 2    .put("org", "engineering")
 3    .put("department", "sdk");
 4JSONObject groupProps = new JSONObject()
 5    .put("technology", "java")
 6    .put("location", "sf");
 7 
 8Event event = new Event("$groupidentify", userId);
 9event.groups = groups;
10event.groupProperties = groupProps;
11 
12client.logEvent(event);

Set user properties

Use event.userProperties as a shorthand to set multiple user properties at one time.

 1Event event = new Event("Button Clicked", "test_user_id");
 2 
 3JSONObject userProps = new JSONObject();
 4double[] arr = {1,2,4,8};
 5try {
 6  userProps.put("team", "red").put("running_times", arr);
 7} catch (JSONException e) {
 8  e.printStackTrace();
 9  System.err.println("Invalid JSON");
10}
11 
12event.userProperties = userProps;
13client.logEvent(event);

Set device information

Unlike the Android SDK or iOS SDK, device information in Java SDK isn't collected via SDK. Device information like device id, device brand, device manufacturer, and device model can be set as properties in each event.

1Event event = new Event("Button Clicked", "test_user_id");
2event.deviceId = "device_id";
3event.deviceBrand = "device_brand";
4event.deviceManufacturer = "device_manufacturer";
5event.deviceModel = "device_model";
6client.logEvent(event);

Set session information

You can set sessionId in an event. This pattern also applies to other properties like city and price. You can see a full list of events properties in Event.java.

1Event event = new Event("Button Clicked", "test_user_id");
2event.sessionId = 1;
3client.logEvent(event);

Amplitude callbacks

Support for AmplitudeCallBacks is available beginning with 1.4.0. You can trigger a callback when event is sent to server or failed after retries.

 1Amplitude client = Amplitude.getInstance();
 2AmplitudeCallbacks callbacks =
 3  new AmplitudeCallbacks() {
 4  @Override
 5    public void onLogEventServerResponse(Event event, int status, String message) {
 6    // Event: Event processed.
 7    // status: response code, like 200, 400, etc.
 8    // message: success or error message.
 9  }
10};
11client.setCallbacks(callbacks);

From 1.5.0, callbacks can be added to event level and triggered when the event is sent to server or failed after retries. One event can trigger both client level callbacks and event level callbacks.

 1Amplitude client = Amplitude.getInstance();
 2AmplitudeCallbacks eventCallbacks =
 3  new AmplitudeCallbacks() {
 4  @Override
 5    public void onLogEventServerResponse(Event event, int status, String message) {
 6    // Event: Event processed.
 7    // status: response code, like 200, 400, etc.
 8    // message: success or error message.
 9  }
10};
11client.logEvent(event, eventCallbacks)

Middleware

Middleware allows you to extend Amplitude by running a sequence of custom code on every event.
This pattern is flexible and can be used to support event enrichment, transformation, filtering, routing to third-party destinations, and more.

Each middleware is a simple interface with a run method:

1void run(MiddlewarePayload payload, MiddlewareNext next);

The payload contains the event being sent as well as an optional extra that allows you to pass custom data to your own middleware implementations.

To invoke the next middleware in the queue, use the next function. You must call next.run(payload) to continue the middleware chain.
If a middleware doesn't call next, then the event processing stop executing after the current middleware completes.

Add middleware to Amplitude via client.addEventMiddleware. You can add as many middleware as you like. Each middleware runs in the order in which it was added.

You can find examples for Java and Kotlin.

Troubleshooting

When debugging, check the logs. The SDK prints error messages.

If you have problems, open an issue on the GitHub issues page.