> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/mixpanel/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> Track events from Java servers with the Mixpanel server-side SDK

## Installation

Add to your `pom.xml`:

```xml theme={null}
<dependency>
  <groupId>com.mixpanel</groupId>
  <artifactId>mixpanel-java</artifactId>
  <version>1.5.2</version>
</dependency>
```

<Info>
  You can also download the JAR directly from [Maven Central](http://search.maven.org/#search%7Cga%7C1%7Cmixpanel-java).
</Info>

## Initialize

```java theme={null}
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.ClientDelivery;
import com.mixpanel.mixpanelapi.MixpanelAPI;
import org.json.JSONObject;

MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
```

## Track Events

<Warning>
  You must provide a `distinct_id` for all events.
</Warning>

```java theme={null}
MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
MixpanelAPI mixpanel = new MixpanelAPI();

// Create event with properties
JSONObject props = new JSONObject();
props.put("Product", "Premium Subscription");
props.put("Amount", 49.99);

JSONObject event = messageBuilder.event("12345", "Purchase", props);

// Bundle and send
ClientDelivery delivery = new ClientDelivery();
delivery.addMessage(event);
mixpanel.deliver(delivery);
```

### Multiple Events

```java theme={null}
ClientDelivery delivery = new ClientDelivery();

JSONObject event1 = messageBuilder.event("12345", "Page View", null);
JSONObject event2 = messageBuilder.event("12345", "Button Click", 
  new JSONObject().put("button", "Sign Up"));

delivery.addMessage(event1);
delivery.addMessage(event2);

mixpanel.deliver(delivery);
```

## User Profiles

```java theme={null}
MessageBuilder messageBuilder = new MessageBuilder("YOUR_PROJECT_TOKEN");
MixpanelAPI mixpanel = new MixpanelAPI();

JSONObject props = new JSONObject();
props.put("Plan", "Premium");
props.put("$email", "user@example.com");
props.put("$ip", "0"); // Disable geolocation

JSONObject message = messageBuilder.set("12345", props);
mixpanel.sendMessage(message);
```

<Tabs>
  <Tab title="setOnce()">
    ```java theme={null}
    JSONObject props = new JSONObject();
    props.put("First Purchase", "2024-01-01");
    props.put("$ip", "0");

    JSONObject message = messageBuilder.setOnce("12345", props);
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="increment()">
    ```java theme={null}
    JSONObject increments = new JSONObject();
    increments.put("login_count", 1);
    increments.put("age", 1);

    JSONObject message = messageBuilder.increment("12345", increments);
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="append()">
    ```java theme={null}
    JSONObject props = new JSONObject();
    props.put("roles", "admin");

    JSONObject message = messageBuilder.append("12345", props);
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="union()">
    ```java theme={null}
    JSONObject props = new JSONObject();
    props.put("skills", "Java");

    JSONObject message = messageBuilder.union("12345", props);
    mixpanel.sendMessage(message);
    ```
  </Tab>
</Tabs>

## Group Analytics

### Send Events

```java theme={null}
JSONObject props = new JSONObject();
props.put("company", "Acme Inc");
props.put("feature", "Reports");

JSONObject event = messageBuilder.event("12345", "Feature Used", props);
mixpanel.sendMessage(event);
```

### Set Group Properties

```java theme={null}
JSONObject groupProps = new JSONObject();
groupProps.put("name", "Acme Inc");
groupProps.put("industry", "Technology");
groupProps.put("employees", 500);

JSONObject message = messageBuilder.groupSet("company", "Acme Inc", groupProps);
mixpanel.sendMessage(message);
```

<Tabs>
  <Tab title="groupSetOnce()">
    ```java theme={null}
    JSONObject props = new JSONObject();
    props.put("founded", "2010-01-01");

    JSONObject message = messageBuilder.groupSetOnce(
      "company", "Acme Inc", props
    );
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="groupUnset()">
    ```java theme={null}
    ArrayList<String> unsetProps = new ArrayList<>(
      Arrays.asList("temp_property")
    );

    JSONObject message = messageBuilder.groupUnset(
      "company", "Acme Inc", unsetProps
    );
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="groupUnion()">
    ```java theme={null}
    ArrayList<String> features = new ArrayList<>(
      Arrays.asList("Reports", "Analytics")
    );

    JSONObject props = new JSONObject();
    props.put("features", features);

    JSONObject message = messageBuilder.groupUnion(
      "company", "Acme Inc", props
    );
    mixpanel.sendMessage(message);
    ```
  </Tab>

  <Tab title="groupRemove()">
    ```java theme={null}
    JSONObject props = new JSONObject();
    props.put("features", "Beta Feature");

    JSONObject message = messageBuilder.groupRemove(
      "company", "Acme Inc", props
    );
    mixpanel.sendMessage(message);
    ```
  </Tab>
</Tabs>

## Privacy Controls

### EU Data Residency

```java theme={null}
MixpanelAPI mixpanel = new MixpanelAPI(
  "https://api-eu.mixpanel.com/track",
  "https://api-eu.mixpanel.com/engage",
  "https://api-eu.mixpanel.com/groups"
);
```

### India Data Residency

```java theme={null}
MixpanelAPI mixpanel = new MixpanelAPI(
  "https://api-in.mixpanel.com/track",
  "https://api-in.mixpanel.com/engage",
  "https://api-in.mixpanel.com/groups"
);
```

### Disable Geolocation

```java theme={null}
// For events
JSONObject props = new JSONObject();
props.put("ip", "0");
JSONObject event = messageBuilder.event("12345", "event", props);

// For profiles
JSONObject userProps = new JSONObject();
userProps.put("$ip", "0");
JSONObject message = messageBuilder.set("12345", userProps);
```

## Platform Considerations

<Warning>
  All server-side calls originate from your server's IP. Set `ip` to `0` to disable geolocation.
</Warning>

* You manage `distinct_id` yourself
* No automatic identity management
* Message-based architecture (build, bundle, send)
* Use `/import` endpoint for historical data
* Designed for high-throughput server environments

## Resources

* [Full API Reference](http://mixpanel.github.io/mixpanel-java/)
* [GitHub Repository](https://github.com/mixpanel/mixpanel-java)
* [Example Application](https://github.com/mixpanel/mixpanel-java/blob/master/src/demo/java/com/mixpanel/mixpanelapi/demo/MixpanelAPIDemo.java)