This is the official Mixpanel tracking library for Java.

July 24, 2026 - v1.10.0

Latest Version

See the releases page for the latest version.

<dependency>
    <groupId>com.mixpanel</groupId>
    <artifactId>mixpanel-java</artifactId>
    <version>1.10.0</version>
</dependency>

You can alternatively download the library jar directly from Maven Central here.

How To Use

The library is designed to produce events and people updates in one process or thread, and consume the events and people updates in another thread or process. Specially formatted JSON objects are built by MessageBuilder objects, and those messages can be consumed by the MixpanelAPI via ClientDelivery objects, possibly after serialization or IPC.

MessageBuilder messages = new MessageBuilder("my token");
JSONObject event = messages.event("joe@gribbl.com", "Logged In", null);

// Later, or elsewhere...
ClientDelivery delivery = new ClientDelivery();
delivery.addMessage(event);

MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.deliver(delivery);

Gzip Compression

The library supports gzip compression for both tracking events (/track) and importing historical events (/import). To enable gzip compression, use the builder:

MixpanelAPI mixpanel = new MixpanelAPI.Builder()
    .useGzipCompression(true)
    .build();

Gzip compression can reduce bandwidth usage and improve performance, especially when sending large batches of events.

Importing Historical Events

The library supports importing historical events (events older than 5 days that are not accepted using /track) via the /import endpoint. Project token will be used for basic auth.

Service Account Authentication (Recommended)

Service account authentication is the recommended method for server-side integrations.

Service accounts provide enhanced security by using unique username/secret pairs instead of relying solely on the project token for authentication:

import com.mixpanel.mixpanelapi.*;

// Create service account credentials
ServiceAccountCredential credentials = new ServiceAccountCredential(
    12345L,              // project ID
    "service-username",  // service account username
    "service-secret"     // service account secret
);

// Configure MixpanelAPI with credentials
MixpanelAPI mixpanel = new MixpanelAPI.Builder()
    .credentials(credentials)
    .build();

// Use normally - credentials are used for /import endpoint and feature flags
MessageBuilder messages = new MessageBuilder("my token");
JSONObject event = messages.event("user@example.com", "Signup", null);

ClientDelivery delivery = new ClientDelivery();
delivery.addImportMessage(event);  // This will use service account auth

mixpanel.deliver(delivery);

Service Accounts with Feature Flags

Service account credentials are passed to MixpanelAPI and automatically used for feature flags:

import com.mixpanel.mixpanelapi.*;
import com.mixpanel.mixpanelapi.featureflags.config.LocalFlagsConfig;

// Create service account credentials
ServiceAccountCredential credentials = new ServiceAccountCredential(
    12345L, "service-username", "service-secret"
);

// Configure feature flags
LocalFlagsConfig flagsConfig = LocalFlagsConfig.builder()
    .projectToken("my-token")
    .pollingIntervalSeconds(60)
    .build();

// Pass credentials to MixpanelAPI - they'll be used for both /import and feature flags
MixpanelAPI mixpanel = new MixpanelAPI.Builder()
    .credentials(credentials)  // Credentials used for /import AND feature flags
    .flagsConfig(flagsConfig)
    .build();

// Feature flag requests will use service account authentication
mixpanel.getLocalFlags().startPollingForDefinitions();
boolean isEnabled = mixpanel.getLocalFlags().isEnabled("new-feature", context);

Important Notes:

• Recommended for all new integrations - Service accounts provide enhanced security
• Service account credentials are used for:
  • /import endpoint - Historical event imports
  • Feature flags - /flags and /flags/definitions endpoints
• Regular event tracking (/track), people updates (/engage), and group updates (/groups) continue to use the project token included in the message payload
• When service account credentials are configured:
  • Authenticated endpoints (/import and feature flags) use HTTP Basic Authentication with username:secret instead of using the project token as the Basic Auth username
  • The project_id is added as a query parameter. Feature flag endpoints (/flags, /flags/definitions) still include the token query parameter alongside project_id; the /import endpoint does not use a token query parameter
  • The project token is not used for authentication (but should still be included in tracking events)

High-Performance JSON Serialization (Optional)

For applications that import large batches of events (e.g., using the /import endpoint), the library supports optional high-performance JSON serialization using Jackson. The Jackson extension provides up to 5x performance improvement for large batches.

To enable high-performance serialization, add the Jackson extension to your project:

<dependency>
    <groupId>com.mixpanel</groupId>
    <artifactId>mixpanel-java-extension-jackson</artifactId>
    <version>1.10.0</version>
</dependency>

Then configure the MixpanelAPI to use it:

import com.mixpanel.mixpanelapi.internal.JacksonSerializer;

MixpanelAPI mixpanel = new MixpanelAPI.Builder()
    .jsonSerializer(new JacksonSerializer())
    .build();

Key benefits:

• Significant performance gains: 2-5x faster serialization for batches of 50+ messages
• Optimal for /import: Most beneficial when importing large batches (up to 2000 events)

The performance improvement is most noticeable when:

• Importing historical data via the /import endpoint
• Sending batches of 50+ events
• Processing high-volume event streams

Feature Flags

The Mixpanel Java SDK supports feature flags with both local and remote evaluation modes.

Local Evaluation (Recommended)

Fast, low-latency flag checks with background polling for flag definitions:

import com.mixpanel.mixpanelapi.*;
import com.mixpanel.mixpanelapi.featureflags.config.*;
import java.util.*;

// Initialize with your project token
LocalFlagsConfig config = LocalFlagsConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .pollingIntervalSeconds(60)
    .build();

MixpanelAPI mixpanel = new MixpanelAPI.Builder()
    .flagsConfig(config)
    .build();

// Start polling for flag definitions
mixpanel.getLocalFlags().startPollingForDefinitions();

// Wait for flags to be ready (optional but recommended)
while (!mixpanel.getLocalFlags().areFlagsReady()) {
    Thread.sleep(100);
}

// Evaluate flags
Map<String, Object> context = new HashMap<>();
context.put("distinct_id", "user-123");

// Check if a feature is enabled
boolean isEnabled = mixpanel.getLocalFlags().isEnabled("new-feature", context);

// Get a variant value with fallback
String theme = mixpanel.getLocalFlags().getVariantValue("ui-theme", "light", context);

// Cleanup
mixpanel.close();

Remote Evaluation

Real-time flag evaluation with server-side API calls:

import com.mixpanel.mixpanelapi.*;
import com.mixpanel.mixpanelapi.featureflags.config.*;
import java.util.*;

RemoteFlagsConfig config = RemoteFlagsConfig.builder()
    .projectToken("YOUR_PROJECT_TOKEN")
    .build();

try (MixpanelAPI mixpanel = new MixpanelAPI.Builder().flagsConfig(config).build()) {
    Map<String, Object> context = new HashMap<>();
    context.put("distinct_id", "user-456");

    boolean isEnabled = mixpanel.getRemoteFlags().isEnabled("premium-features", context);
}

For complete feature flags documentation, configuration options, advanced usage, and best practices, see:

https://docs.mixpanel.com/docs/tracking-methods/sdks/java/java-flags

Learn More

This library in particular has more in-depth documentation at

https://mixpanel.com/docs/integration-libraries/java

Mixpanel maintains documentation at

http://www.mixpanel.com/docs

The library also contains a simple demo application, that demonstrates using this library in an asynchronous environment.

There are also community supported libraries in addition to this library, that provide a threading model, support for dealing directly with Java Servlet requests, support for persistent properties, etc. Two interesting ones are at:

https://github.com/eranation/mixpanel-java
https://github.com/scalascope/mixpanel-java

Other Mixpanel Libraries

Mixpanel also maintains a full-featured library for tracking events from Android apps at https://github.com/mixpanel/mixpanel-android

And a full-featured client side library for web applications, in Javascript, that can be loaded directly from Mixpanel servers. To learn more about our Javascript library, see: https://mixpanel.com/docs/integration-libraries/javascript

This library is intended for use in back end applications or API services that can't take advantage of the Android libraries or the Javascript library.

License

See LICENSE File for details. The Base64Coder class used by this software
has been licensed from non-Mixpanel sources and modified for use in the library.
Please see Base64Coder.java for details.