Java

Server API Integration

The Mixpanel pure Java library is designed for generality, and is mostly useful in deep back-end and embedded applications.

Android and JavaScript libraries

Mixpanel also provides a full-featured Android library for developers deploying Android applications, and a powerful and easy to use client-side JavaScript library for web applications. Both of these libraries offer platform-specific features and conveniences that can make Mixpanel implementations much simpler, and can scale naturally to an unlimited number of clients.

Installing the Library

You can get the library by including the following in your project's pom.xml:

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

If you're not using Maven to build your project, you can browse and download the library jar directly from Maven central

Sending Events

Track events in the mixpanel-java library by creating messages using an instance of MessageBuilder using your project token, bundling messages together using an instance of ClientDelivery, and then pushing the bundle to Mixpanel using an instance of MixpanelAPI.

The JSONObjects produced by MessageBuilder are completely self-contained, and can be sent over a network or enqueued for later processing.

import com.mixpanel.mixpanelapi.ClientDelivery;
import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

// You can find your project token in the
// project settings dialog
// of the Mixpanel web application
MessageBuilder messageBuilder =
    new MessageBuilder(PROJECT_TOKEN);

// Create an event
JSONObject sentEvent =
    messageBuilder.event(distinctId, "Sent Message", null);

// You can send properties along with events
JSONObject props = new JSONObject();
props.put("Gender", "Female");
props.put("Plan", "Premium");

JSONObject planEvent =
    messageBuilder.event(distinctId, "Plan Selected", props);

// Gather together a bunch of messages into a single
// ClientDelivery. This can happen in a separate thread
// or process from the call to MessageBuilder.event()
ClientDelivery delivery = new ClientDelivery();
delivery.addMessage(sentEvent);
delivery.addMessage(planEvent);

// Use an instance of MixpanelAPI to send the messages
// to Mixpanel's servers.
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.deliver(delivery);

EU Data Residency

Route data to Mixpanel's EU servers by passing in positional arguments into the MixpanelAPI constructor
public MixpanelAPI(String eventsEndpoint,
String peopleEndpoint,
String groupsEndpoint)


MixpanelAPI mixpanel = new MixpanelAPI( "https://api-eu.mixpanel.com/track",
                                        "https://api-eu.mixpanel.com/engage",
                                        "https://api-eu.mixpanel.com/groups");

Managing User Identity

Mixpanel groups events sent with different distinct_ids, presenting them in reports as different user event streams. You can connect events with different distinct_ids using alias, identify, or merge, ultimately attributing them to one user.

📘

ID Merge

If a project has ID merge enabled, the $identify event can connect pre- and post-authentication events. If ID merge is not enabled, identify events will not link identities however alias can be used to connect pre and post registration events.

Storing User Profiles

In addition to events, you can send user profile updates to Mixpanel. Mixpanel can maintain a profile of each of your users, storing information you know about them. An update is a message that changes the properties of a user profile.

You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Setting Profile Properties

You can prepare a profile update message with MessageBuilder.set

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

MessageBuilder messageBuilder =
    new MessageBuilder(PROJECT_TOKEN);

// Sets user 13793's "Plan" attribute to "Premium"
// This creates a profile for 13793 if one does not
// already exist.
JSONObject props = new JSONObject();
props.put("Plan", "Premium");
props.put("$ip", "72.229.28.185");
props.put("$ignore_time", "true");
JSONObject update = messageBuilder.set("13793", props);

// Send the update to mixpanel
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.sendMessage(update);

This will set a "Plan" property, with a value "Premium", on user 13793's profile. If there isn't a profile with distinct_id 13793 in Mixpanel already, a new profile will be created. If user 13793 already has a property named "Plan" in their profile, the old value will be overwritten with "Premium". The ip property is set to the user’s ip address “72.229.28.185”. The ignore_time property is set to a value of “true”. Learn more about the ip and ignore_time properties in this article.

📘

NOTE

Pick your property names wisely. Once you've sent them to Mixpanel, there is no way to change them. Feel free to use capitalization and spaces in between words.
There are a few limitations:

  • Your property names should not begin with $ or mp_. These properties are reserved for special properties sent by Mixpanel.
  • Your property names cannot begin or end with a space as they will automatically be trimmed.
  • Your property names and values cannot be longer than 255 characters. In practice they should be much shorter than that. Property names get cut off by our user interface at about 20 characters.

Click here to see a list of Mixpanel's reserved user profile properties.

Incrementing Numeric Properties

You can use MessageBuilder.increment to create a message that will change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, emails sent, or points earned.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

MessageBuilder messageBuilder =
    new MessageBuilder(PROJECT_TOKEN);

// Pass a Map to increment multiple properties
Map<String, Long> properties = new HashMap<String, Long>();
properties.put("dollars spent", 17);

// Subtract by passing a negative value
properties.put("credits remaining", -34);
JSONObject update =
    messageBuilder.increment("13793", properties);

// Send the update to mixpanel
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.sendMessage(update);

Appending to List Properties

MessageBuilder.append creates an update that adds an item to a list-valued property. The value you send with the append is added to the end of the list. If the property doesn't exist, it will be created with a one element list as its value.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

MessageBuilder messageBuilder =
    new MessageBuilder(PROJECT_TOKEN);

// Adds "Asheville" to a list-value property
// "Cities Visited" on user "13793"
JSONObject properties = new JSONObject();
properties.put("Cities Visited", "Asheville");
JSONObject update =
    messageBuilder.append("13793", properties);

// Send the update to mixpanel
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.sendMessage(update);

Group Analytics

Mixpanel Group Analytics allows behavioral data analysis by selected groups, as opposed to individual users.

Grouping by identifiers other than the distinct_id allows analysis at a company or group level when using Mixpanel analytics. Read this article to learn more about Group Analytics.

A group is identified by the group_key and group_id.

  • group_key is the property that connects event data for Group Analytics.
  • group_id is the identifier for a specific group.

If the property “Company” is chosen for Group Analytics, “Company” is the group_key, and “Mixpanel”, “Company A”, and “13254” are all potential group_id values.

A user can belong to multiple groups. All updates to a group operate on the group_key and group_id.

📘

Add Group Keys

To start tracking groups data, add group keys in project settings. If you don't see group keys in your Project Settings, reach out to the Mixpanel Sales Team to purchase Group Analytics.

Creating a Group Key

Administer group keys through your Project Settings. Group keys are event properties. All events need to have a defined group key on them in order to be attributed to a group. Group keys are project specific, and the group key should be set up before group data is sent. Note that Mixpanel does not backfill historical data before the group key was implemented.

To administer group keys, navigate to your Project Settings. Click +Add Group Key under the GROUP KEYS section.

Enter an event property to attribute the group key to. You can also enter a display name for the group key. Click Save.

Sending Group Identifiers With Events

To send group identifiers with events, send the group_key as a property key and the group_id as the property value. The data type of the group_key property is a list, therefore you can add multiple values for a single user. It is also possible to pass only one value.

Mixpanel can group events by the group_id, similar to how events are grouped with the distinct_id. A group_id, however, is a group level identifier and not a user level identifier like the distinct_id.

Note that sending in a group_key and group_id as event properties does not add users to the group profile or assign group membership to the user's profile. Only events with your chosen group_key property set will be available for behavioral analysis at the group level. See the sections following the code example to learn how to add users to a group profile or add a group to the user's profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanelApi = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// You can send properties along with events
JSONObject props = new JSONObject();
props.put("Name", "Pat Davis");
props.put("Plan", "Premium");
props.put("Company", "Mixpanel")
 
JSONObject planEvent =
    messageBuilder.event(distinctId, "Plan Selected", props);
mixpanel.sendMessage(planEvent);

Adding Group Identifiers to Individual Users

To connect group information to a user profile, include the group_key and group_id by sending the property as part of the set() call.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel= new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
//Create JSON object ‘props’
// Include “Company” property with “Mixpanel” as value
 
JSONObject props = new JSONObject();
props.put("$name", "Pat Davis");
props.put("Plan", "Premium");
props.put("Company", "Mixpanel");
 
// Adds “Company” : “Mixpanel” to user profile with distinct_id=13793
JSONObject update = messageBuilder.set("13793", props);
mixpanel.sendMessage(update);

Creating Group Profiles

It is possible to create a Group profile that is similar to a user profile. You must call a property-setting method like set() (described below) to create a group profile. It is important to include the group_key, group_id, and at least one property so that the profile is not empty.

Setting Group Properties

You can add details to Group Profiles by adding properties to them. You can set the property $name to populate the name field at the top of the group profile.

These operations are similar to the corresponding operations for user profile property updates.

set

groupSet() updates or adds properties to a group profile. The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Create a group profile with group_key = "company", group_id = "Acme Inc."
// and assign the properties "$name" and "Industry"
JSONObject groupProperties = new JSONObject();
groupProperties.put("$name", "Acme Incorporated");
groupProperties.put("Industry", "Manufacturing");
JSONObject message = messageBuilder.groupSet(
    "company",
    "Acme Inc.",
    groupProperties
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

set once

groupSetOnce() adds properties to a group only if the property is not already set. The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Create a group profile with group_key = "company", group_id = "Acme Inc."
// and assign the property "First Purchase" with value "Steel" to the profile
// only if it is not already set
JSONObject groupProperties = new JSONObject();
groupProperties.put("First Purchase", "Steel");
JSONObject message = messageBuilder.groupSetOnce(
    "company",
    "Acme Inc.",
    groupProperties
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

unset

groupUnset() unsets properties on the group profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");

// Removes the properties named in propertyNames from the group profile identified by groupKey and groupId.
JSONObject message = messageBuilder.groupUnset(
    "company",
    "Acme Inc.",
    List.of("First Purchase")
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

union

groupUnion() adds the specified values to a list property and ensures that those values only appear once. The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Merges list-valued properties into a group profile.
// The list values given are merged with the existing list on the group profile,
// ignoring duplicate list values. 
JSONArray array=new JSONArray();
array.put("Anvils");
array.put("Explosives");
Map<String, JSONArray> props = Map.of("Products", array);
JSONObject message = messageBuilder.groupUnion(
    "company",
    "Acme Inc.",
    props
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

remove

groupRemove() removes a specific value in a list property on a group profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Removes "Anvils" from the "Products" list property
JSONObject props = new JSONObject();
props.put("Products", "Anvils");
JSONObject message = messageBuilder.groupRemove("company", "Acme Inc.", props);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

delete

groupDelete() permanently deletes a group profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
JSONObject message = messageBuilder.groupDelete("company", "Acme Inc.");
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

Lookup tables

You can use lookup tables to enrich existing event and profile properties. While you've had the ability to upload CSV to update the lookup tables, we now support programmatic access to do the same. Updating lookup tables follows the same process as updating group profile properties.

It is possible to create a lookup profile that is similar to a user profile. You must call a property-setting method like groupSet() to create a lookup profile (row). It is important to include the group_key, group_id, and at least one property so that the profile is not empty.

To learn more about the concepts behind lookup tables, and to see how each of the IDs map to the lookup table entities, please read this.

How to find the group_key?

Updating a lookup table

set

groupSet() updates or adds properties to a lookup profile (row). The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Create a lookup profile with group_key "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7" 
// (found in lookup table details page) and group_id "Gagnam style" (join key value in 1st column of table).
JSONObject groupProperties = new JSONObject();
groupProperties.put("Genre", "Pop");
JSONObject message = messageBuilder.groupSet(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style",
    groupProperties
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

set once

groupSetOnce() adds properties to a lookup profile only if the property is not already set. The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Create a lookup profile with group_key "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7" 
// (found in lookup table details page) and group_id "Gagnam style" (join key value in 1st column of table)
// and assign the property "Genre" with value "Pop" to the profile
// only if it is not already set
JSONObject groupProperties = new JSONObject();
groupProperties.put("Genre", "Pop");
JSONObject message = messageBuilder.groupSetOnce(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style",
    groupProperties
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

unset

groupUnset() unsets properties on the lookup profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");

// Removes the property "Genre" from the lookup profile identified by groupKey and groupId.
JSONObject message = messageBuilder.groupUnset(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style",
    List.of("Genre")
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

union

groupUnion() adds the specified values to a list property and ensures that those values only appear once. The profile is created if it does not exist.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Merges list-valued properties into a lookup profile.
// The list values given are merged with the existing list on the lookup profile,
// ignoring duplicate list values. 
JSONArray array=new JSONArray();
array.put("spectacular");
array.put("crazy");
Map<String, JSONArray> props = Map.of("hashtags", array);
JSONObject message = messageBuilder.groupUnion(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style",
    props
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

remove

groupRemove() removes a specific value in a list property on a lookup profile.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
// Removes "amazing" from the "hashtags" list property
JSONObject props = new JSONObject();
props.put("hashtags", "amazing");
JSONObject message = messageBuilder.groupRemove(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style",
    props
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

delete

groupDelete() permanently deletes a lookup profile (row).

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;
 
MixpanelAPI mixpanel = new MixpanelAPI();
MessageBuilder messageBuilder = new MessageBuilder("[your project token]");
 
JSONObject message = messageBuilder.groupDelete(
    "d1b6d2e0-1330-4ad6-b520-d948ede3b1a7",
    "Gangnam style"
);
try {
    mixpanel.sendMessage(message);
} catch(IOException e) {
    // exception handling logic
}

Tracking Revenue

Mixpanel makes it easy to analyze the revenue you make from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with MessageBuilder.trackCharge. Sending a message created with trackCharge will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

import com.mixpanel.mixpanelapi.MessageBuilder;
import com.mixpanel.mixpanelapi.MixpanelAPI;

MessageBuilder messageBuilder =
    new MessageBuilder(PROJECT_TOKEN);

// Track a charge of $29.99 for the user identified by 13793
JSONObject update =
    messageBuilder.trackCharge("13793", 29.99, null);

// Send the update to mixpanel
MixpanelAPI mixpanel = new MixpanelAPI();
mixpanel.sendMessage(update);

// Track a refund of $50 for the user identified by 13793
JSONObject update =
    messageBuilder.trackCharge("13793", -50, null);
mixpanel.sendMessage(update);

// Track a charge of 25 dollars on January 2, 2012
JSONObject properties = new JSONObject()
properties.put("$time", "2012-01-02T00:00:00");
JSONObject update =
    messageBuilder.trackCharge("13793", -50, properties);
mixpanel.sendMessage(update);

The Java library appends a time stamp to events by default. You have to manually use the $time property to append a time stamp to user profile properties.

Updated 3 months ago


Java


Server API Integration

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.