com.mixpanel.mixpanelapi

Class MessageBuilder

java.lang.Object

com.mixpanel.mixpanelapi.MessageBuilder

public class MessageBuilder
extends Object

This class writes JSONObjects of a form appropriate to send as Mixpanel events and updates to people analytics profiles via the MixpanelAPI class. Instances of this class can be instantiated separately from instances of MixpanelAPI, and the resulting messages are suitable for enqueuing or sending over a local network.

Constructor Summary

Constructors

Constructor and Description
MessageBuilder(String token)

Method Summary

Methods

Modifier and Type	Method and Description
org.json.JSONObject	append(String distinctId, org.json.JSONObject properties) For each key and value in the properties argument, attempts to append that value to a list associated with the key in the identified People Analytics profile.
org.json.JSONObject	append(String distinctId, org.json.JSONObject properties, org.json.JSONObject modifiers) For each key and value in the properties argument, attempts to append that value to a list associated with the key in the identified People Analytics profile.
org.json.JSONObject	delete(String distinctId) Deletes the People Analytics profile associated with the given distinctId.
org.json.JSONObject	delete(String distinctId, org.json.JSONObject modifiers) Deletes the People Analytics profile associated with the given distinctId.
org.json.JSONObject	event(String distinctId, String eventName, org.json.JSONObject properties) Creates a message tracking an event, for consumption by MixpanelAPI See: http://blog.mixpanel.com/2012/09/12/best-practices-updated/ for a detailed discussion of event names, distinct ids, event properties, and how to use them to get the most out of your metrics.
org.json.JSONObject	increment(String distinctId, Map<String,Long> properties) For each key and value in the properties argument, adds that amount to the associated property in the People Analytics profile with the given distinct id.
org.json.JSONObject	increment(String distinctId, Map<String,Long> properties, org.json.JSONObject modifiers) For each key and value in the properties argument, adds that amount to the associated property in the People Analytics profile with the given distinct id.
org.json.JSONObject	peopleMessage(String distinctId, String actionType, Object properties, org.json.JSONObject modifiers) Formats a generic people message.
org.json.JSONObject	set(String distinctId, org.json.JSONObject properties) Sets a People Analytics property on the profile associated with the given distinctId.
org.json.JSONObject	set(String distinctId, org.json.JSONObject properties, org.json.JSONObject modifiers) Sets a People Analytics property on the profile associated with the given distinctId.
org.json.JSONObject	setOnce(String distinctId, org.json.JSONObject properties, org.json.JSONObject modifiers) Sets a People Analytics property on the profile associated with the given distinctId, only if that property is not already set on the associated profile.
org.json.JSONObject	trackCharge(String distinctId, double amount, org.json.JSONObject properties) Tracks revenue associated with the given distinctId.
org.json.JSONObject	trackCharge(String distinctId, double amount, org.json.JSONObject properties, org.json.JSONObject modifiers) Tracks revenue associated with the given distinctId.
org.json.JSONObject	union(String distinctId, Map<String,org.json.JSONArray> properties, org.json.JSONObject modifiers) Merges list-valued properties into a user profile.
org.json.JSONObject	unset(String distinctId, Collection<String> propertyNames, org.json.JSONObject modifiers) Removes the properties named in propertyNames from the profile identified by distinctId.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageBuilder

public MessageBuilder(String token)

Method Detail

event

public org.json.JSONObject event(String distinctId,
                        String eventName,
                        org.json.JSONObject properties)

Creates a message tracking an event, for consumption by MixpanelAPI See: http://blog.mixpanel.com/2012/09/12/best-practices-updated/ for a detailed discussion of event names, distinct ids, event properties, and how to use them to get the most out of your metrics.

Parameters:

distinctId - a string uniquely identifying the individual cause associated with this event (for example, the user id of a signing-in user, or the hostname of a server)

eventName - a human readable name for the event, for example "Purchase", or "Threw Exception"

properties - a JSONObject associating properties with the event. These are useful for reporting and segmentation of events. It is often useful not only to include properties of the event itself (for example { 'Item Purchased' : 'Hat' } or { 'ExceptionType' : 'OutOfMemory' }), but also properties associated with the identified user (for example { 'MemberSince' : '2012-01-10' } or { 'TotalMemory' : '10TB' })

set

public org.json.JSONObject set(String distinctId,
                      org.json.JSONObject properties)

Sets a People Analytics property on the profile associated with the given distinctId. When sent, this message will overwrite any existing values for the given properties. So, to set some properties on user 12345, one might call:

 JSONObject userProperties = new JSONObject();
     userProperties.put("Company", "Uneeda Medical Supply");
     userProperties.put("Easter Eggs", "Hatched");
     JSONObject message = messageBuilder.set("12345", userProperties);
     mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to change, for example, a user id of an app, or the hostname of a server. If no profile exists for the given id, a new one will be created.

properties - a collection of properties to set on the associated profile. Each key in the properties argument will be updated on on the people profile.

set

public org.json.JSONObject set(String distinctId,
                      org.json.JSONObject properties,
                      org.json.JSONObject modifiers)

Sets a People Analytics property on the profile associated with the given distinctId. When sent, this message will overwrite any existing values for the given properties. So, to set some properties on user 12345, one might call:

 JSONObject userProperties = new JSONObject();
     userProperties.put("Company", "Uneeda Medical Supply");
     userProperties.put("Easter Eggs", "Hatched");
     JSONObject message = messageBuilder.set("12345", userProperties);
     mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to change, for example, a user id of an app, or the hostname of a server. If no profile exists for the given id, a new one will be created.

properties - a collection of properties to set on the associated profile. Each key in the properties argument will be updated on on the people profile

modifiers - Modifiers associated with the update message. (for example "$time" or "$ignore_time"). this can be null- if non-null, the keys and values in the modifiers object will be associated directly with the update.

setOnce

public org.json.JSONObject setOnce(String distinctId,
                          org.json.JSONObject properties,
                          org.json.JSONObject modifiers)

Sets a People Analytics property on the profile associated with the given distinctId, only if that property is not already set on the associated profile. So, to set a new property on on user 12345 if it is not already present, one might call:

 JSONObject userProperties = new JSONObject();
     userProperties.put("Date Began", "2014-08-16");

     // "Date Began" will not be overwritten, but if it isn't already
     // present it will be set when we send this message.
     JSONObject message = messageBuilder.setOnce("12345", userProperties);
     mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to change, for example, a user id of an app, or the hostname of a server. If no profile exists for the given id, a new one will be created.

properties - a collection of properties to set on the associated profile. Each key in the properties argument will be updated on on the people profile

modifiers - Modifiers associated with the update message. (for example "$time" or "$ignore_time"). this can be null- if non-null, the keys and values in the modifiers object will be associated directly with the update.

delete

public org.json.JSONObject delete(String distinctId)

Deletes the People Analytics profile associated with the given distinctId.

 JSONObject message = messageBuilder.delete("12345");
     mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to delete

delete

public org.json.JSONObject delete(String distinctId,
                         org.json.JSONObject modifiers)

Deletes the People Analytics profile associated with the given distinctId.

 JSONObject message = messageBuilder.delete("12345");
     mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to delete

modifiers - Modifiers associated with the update message. (for example "$time" or "$ignore_time"). this can be null- if non-null, the keys and values in the modifiers object will be associated directly with the update.

increment

public org.json.JSONObject increment(String distinctId,
                            Map<String,Long> properties)

For each key and value in the properties argument, adds that amount to the associated property in the People Analytics profile with the given distinct id. So, to maintain a login count for user 12345, one might run the following code at every login:

 Map<String, Long> updates = new HashMap<String, Long>();
    updates.put('Logins', 1);
    JSONObject message = messageBuilder.set("12345", updates);
    mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to change, for example, a user id of an app, or the hostname of a server. If no profile exists for the given id, a new one will be created.

properties - a collection of properties to change on the associated profile, each associated with a numeric value.

increment

public org.json.JSONObject increment(String distinctId,
                            Map<String,Long> properties,
                            org.json.JSONObject modifiers)

For each key and value in the properties argument, adds that amount to the associated property in the People Analytics profile with the given distinct id. So, to maintain a login count for user 12345, one might run the following code at every login:

 Map<String, Long> updates = new HashMap<String, Long>();
    updates.put('Logins', 1);
    JSONObject message = messageBuilder.set("12345", updates);
    mixpanelApi.sendMessage(message);
 
 

Parameters:

distinctId - a string uniquely identifying the people analytics profile to change, for example, a user id of an app, or the hostname of a server. If no profile exists for the given id, a new one will be created.

properties - a collection of properties to change on the associated profile, each associated with a numeric value.

modifiers - Modifiers associated with the update message. (for example "$time" or "$ignore_time"). this can be null- if non-null, the keys and values in the modifiers object will be associated directly with the update.

append

public org.json.JSONObject append(String distinctId,
                         org.json.JSONObject properties)

For each key and value in the properties argument, attempts to append that value to a list associated with the key in the identified People Analytics profile.

append

public org.json.JSONObject append(String distinctId,
                         org.json.JSONObject properties,
                         org.json.JSONObject modifiers)

For each key and value in the properties argument, attempts to append that value to a list associated with the key in the identified People Analytics profile.

union

public org.json.JSONObject union(String distinctId,
                        Map<String,org.json.JSONArray> properties,
                        org.json.JSONObject modifiers)

Merges list-valued properties into a user profile. The list values in the given are merged with the existing list on the user profile, ignoring duplicate list values.

unset

public org.json.JSONObject unset(String distinctId,
                        Collection<String> propertyNames,
                        org.json.JSONObject modifiers)

Removes the properties named in propertyNames from the profile identified by distinctId.

trackCharge

public org.json.JSONObject trackCharge(String distinctId,
                              double amount,
                              org.json.JSONObject properties)

Tracks revenue associated with the given distinctId.

Parameters:

distinctId - an identifier associated with a People Analytics profile

amount - a double revenue amount. Positive amounts represent income for your business.

properties - can be null. If provided, a set of properties to associate with the individual transaction.

trackCharge

public org.json.JSONObject trackCharge(String distinctId,
                              double amount,
                              org.json.JSONObject properties,
                              org.json.JSONObject modifiers)

Tracks revenue associated with the given distinctId.

Parameters:

distinctId - an identifier associated with a People Analytics profile

amount - a double revenue amount. Positive amounts represent income for your business.

properties - can be null. If provided, a set of properties to associate with the individual transaction.

modifiers - can be null. If provided, the keys and values in the object will be merged as modifiers associated with the update message (for example, "$time" or "$ignore_time")

peopleMessage

public org.json.JSONObject peopleMessage(String distinctId,
                                String actionType,
                                Object properties,
                                org.json.JSONObject modifiers)

Formats a generic people message. Use of this method requires familiarity with the underlying Mixpanel HTTP API, and it may be simpler and clearer to use the pre-built functions for setting, incrementing, and appending to properties. Use this method directly only when interacting with experimental APIs, or APIS that the rest of this library does not yet support. The underlying API is documented at https://mixpanel.com/help/reference/http

Parameters:

distinctId - a string uniquely identifying the individual cause associated with this event (for example, the user id of a signing-in user, or the hostname of a server)

actionType - a string associated in the HTTP api with the operation (for example, $set or $add)

properties - a payload of the operation. Will be converted to JSON, and should be of types Boolean, Double, Integer, Long, String, JSONArray, JSONObject, the JSONObject.NULL object, or null. NaN and negative/positive infinity will throw an IllegalArgumentException

modifiers - if provided, the keys and values in the modifiers object will be merged as modifiers associated with the update message (for example, "$time" or "$ignore_time")

Throws:

IllegalArgumentException - if properties is not intelligible as a JSONObject property

See Also:

set(String distinctId, JSONObject properties), delete(String distinctId), MessageBuilder#increment(String distinctId, Map properties), append(String distinctId, JSONObject properties, JSONObject modifiers)