JRE Java SDK

This is the documentation for the Amplitude Analytics Java SDK.

Install the SDK

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

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.

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

Initialize the SDK

You must initialize the SDK before you instrument any events. The SDK requires the API key for your Amplitude project.

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

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

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

Configure the SDK

Options

Configure batching behavior

To support high-performance environments, the SDK sends events in batches. The SDK queues every event the logEvent method logs in memory, then flushes events in batches in the background. Customize batch behavior with setEventUploadThreshold and setEventUploadPeriodMillis. By default, the SDK runs in regular mode with serverUrl set to https://api2.amplitude.com/2/httpapi. To send large batches of data at a time, switch to batch mode by setting useBatchMode to true, which sets setServerUrl to the batch event upload API at https://api2.amplitude.com/batch. Both regular mode and batch mode use the same flush queue size and flush intervals.

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

// Events queue will flush every certain milliseconds based on setting
// Default value is 10,000 milliseconds
client.setEventUploadPeriodMillis(5000);

// Using batch mode with batch API endpoint, `https://api2.amplitude.com/batch`
client.useBatchMode(true);

You can also flush events on demand.

client.flushEvents();

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

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

Because batch mode permits a higher rate of data, Amplitude may delay data sent in batch mode based on load. Refer to this project on GitHub for a usage example.

// Enable batch mode
client.useBatchMode(true);

// Disable batch mode
client.useBatchMode(false);

Configure a custom HTTP proxy

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

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

// Unset proxy
client.setProxy(Proxy.NO_PROXY);

Configure a custom logger

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

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

Configure minIdLength and header

The Amplitude Java SDK supports customizing the minimum ID length and header in versions later than 1.7.0.

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

Configure event flushing and thread timeout

New in version 1.10.0. Set the events flushing thread timeout in milliseconds. If set to a positive long integer, event 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 thread pool. Events in the buffer trigger callbacks. Amplitude creates and returns a new instance if you call Amplitude.getInstance(INSTANCE_NAME) with the same instance name.

client.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. Refer to the HTTP V2 API for available event object keys.

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

Events with properties

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

JSONObject eventProps = new JSONObject()
    .put("Hover Time", 10)
    .put("prop_2", "value_2");

Event event = new Event("Button Clicked", userId);
event.eventProperties = eventProps;

client.logEvent(event);

Events with groups

Amplitude supports assigning users to groups and running 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 based on the organization they belong to 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 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 and the corresponding user property value. groupType is a string, and groupName can be a string or an array of strings to indicate that a user belongs to multiple groups.

JSONObject groups = new JSONObject();
groups.put("orgId", 10);

Event setGroupEvent = new Event("$identify", userId);
setGroupEvent.groups = groups;
setGroupEvent.userProperties = groups;
client.logEvent(setGroupEvent);

JSONObject groups = new JSONObject();
groups.put("sport", new String[] {"tennis", "soccer"});

Event setGroupsEvent = new Event("$identify", userId);
setGroupsEvent.groups = groupProps;
setGroupsEvent.userProperties = groups;

client.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 you log, and doesn't persist on the user.

JSONObject groups = new JSONObject();
groups.put("orgId", 10);

Event event = new Event('event type', userId);
event.groups = groups;

client.logEvent(event);

After you set groups, you can set or update the properties of particular groups. These updates only affect events going forward.

JSONObject groups = new JSONObject()
    .put("org", "engineering")
    .put("department", "sdk");
JSONObject groupProps = new JSONObject()
    .put("technology", "java")
    .put("location", "sf");

Event event = new Event("$groupidentify", userId);
event.groups = groups;
event.groupProperties = groupProps;

client.logEvent(event);

Set user properties

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) {
  e.printStackTrace();
  System.err.println("Invalid JSON");
}

event.userProperties = userProps;
client.logEvent(event);

Set device information

Unlike the Android SDK or iOS SDK, the Java SDK doesn't collect device information. Set device information like device ID, device brand, device manufacturer, and device model 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";
client.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.

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

Amplitude callbacks

Support for AmplitudeCallBacks starts with version 1.4.0. You can trigger a callback after the SDK sends an event to the server or after the event fails after retries.

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks callbacks =
  new AmplitudeCallbacks() {
  @Override
    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.setCallbacks(callbacks);

Starting in version 1.5.0, you can add callbacks at the event level. The SDK triggers them after it sends the event to the server or after the event fails after retries. One event can trigger both client-level callbacks and event-level callbacks.

Amplitude client = Amplitude.getInstance();
AmplitudeCallbacks eventCallbacks =
  new AmplitudeCallbacks() {
  @Override
    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

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

Each middleware is an interface with a run method:

void run(MiddlewarePayload payload, MiddlewareNext next);

The payload contains the event the SDK sends and an optional extra field that lets you 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, event processing stops after the current middleware completes.

Add middleware to Amplitude through client.addEventMiddleware. You can add as many middleware as you want. Each middleware runs in the order you added it.

Refer to 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.