Skip to content


Maven Central

This is the documentation for the Amplitude Analytics Java SDK, not the Android SDK.

JRE SDK Resources

GitHub · Releases

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

SDK installation


Use Gradle or another build system to resolve the Java SDK dependency. The following example is for Gradle:

dependencies {
    implementation 'org.json:json:20201115'
    implementation 'com.amplitude:java-sdk:1.10.0'

Download (alternative)

Download the latest JAR file and add it to the project's build path. See instructions for your IDE.

EU data residency

Sending data to Amplitude's EU servers, you need to configure the server URL during the initialization.

Amplitude amplitude = Amplitude.getInstance();
amplitude.init("API KEY");

Usage and examples


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

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


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

Amplitude client = Amplitude.getInstance();

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

Amplitude client = Amplitude.getInstance("YOUR_INSTANCE_NAME");

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 batch in background. You can customize batch behavior with setEventUpdloadThreshfold and setEventUploadPeriodMillis.

Amplitude client = Amplitude.getInstance();
// events queued in memory will flush when number of events exceed upload threshold
// default value is 10

// events queue will flush every certain milliseconds based on setting
// default value is 10,000 milliseconds

You can also flush events on demand.


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.

// Enable batch mode

// Disable batch mode

Config custom HTTP proxy

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

// Set proxy for http requests
client.setProxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("", port)));

// Unset proxy

Config custom logger

New in version 1.10.0. Set a customized logger for amplitude client.

// Set logger 
client.setLogger(new AmplitudeLog() {
  public void log(String tag, String message, LogMode messageMode) {
    if (messageMode.level >= logMode.level) {
      // implement using custom logging framework and format

Config events flushing 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.

client.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 threadspool. 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.


Send events

Important notes about sending events

This SDK uses the HTTP V2 API and follows the same constraints for events. Make sure that all events logged in the SDK have the event_type field and at least one of device_id or user_id, and follows the HTTP API's constraints on each of those fields.

To prevent instrumentation issues, device IDs and user IDs must be strings with a length of 5 characters or more. If an event contains a device ID or user ID that's too short, the ID value is removed from the event. If the event doesn't have a user_id or device_id value, the upload may be rejected with a 400 status. Override the default minimum length of 5 character by passing the min_id_length option with the request.

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


For testing Java SDK out, please make sure your main thread continues until the background daemon thread that has the Amplitude HTTP request is finished. Otherwise, the main thread terminated earlier than the daemon thread will lead logEvent to fail silently.

Amplitude client = Amplitude.getInstance();
client.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."

Event event = new Event("Button Clicked", "test_user_id");

JSONObject eventProps = new JSONObject();
try {
  eventProps.put("Hover Time", 10).put("prop_2", "value_2");
} catch (JSONException e) {
  System.err.println("Invalid JSON");

event.eventProperties = eventProps;


Set user properties

Privacy and tracking

Don't track any user data that may be against your privacy terms.

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

Event event = new Event("Button Clicked", "test_user_id");

JSONObject userProps = new JSONObject();
double[] arr = {1,2,4,8};
try {
  userProps.put("team", "red").put("running_times", arr);
} catch (JSONException e) {
  System.err.println("Invalid JSON");

event.userProperties = userProps;

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.

Event event = new Event("Button Clicked", "test_user_id");
event.deviceId = "device_id";
event.deviceBrand = "device_brand";
event.deviceManufacturer = "device_manufacturer";
event.deviceModel = "device_model";

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 event = new Event("Button Clicked", "test_user_id");
event.sessionId = 1;

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.

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks callbacks =
  new AmplitudeCallbacks() {
    public void onLogEventServerResponse(Event event, int status, String message) {
    // Event: Event processed.
    // status: response code, like 200, 400, etc.
    // message: success or error message.

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.

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks eventCallbacks =
  new AmplitudeCallbacks() {
    public void onLogEventServerResponse(Event event, int status, String message) {
    // Event: Event processed.
    // status: response code, like 200, 400, etc.
    // message: success or error message.
client.logEvent(event, eventCallbacks)


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:

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


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

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

Still have questions? Ask them in the Community.