Java Server API Integration

Android and JavaScript libraries

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

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 at http://search.maven.org/#search|ga|1|mixpanel-java

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);

Storing user profiles

In addition to events, you can send People Analytics 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 People Analytics 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 notifications, 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");
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".

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);

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);