Android - Advanced

Getting Started

Please refer to our Quickstart Guide.

Opting Users Out of Tracking

Client-side tracking of individual user data can be stopped or resumed by controlling a user’s opt-out/opt-in state. Opt-out methods and library configuration settings only affect data sent from a single library instance. Data sent from other sources to Mixpanel’s APIs will still be ingested regardless of whether the user is opted out locally.

The opt-out/opt-in state of a user is controlled by an opt-out flag that is stored in the local storage of the user’s device. If the value of the flag is true, then the user is opted-out and will not be tracked. If the opt-out flag is false, then the user is tracked. The flag is not set when the SDK is initialized, so the initial state is neither opted in nor opted out. Without the flag set, the user will be tracked by default.

To opt a user out of tracking locally, use the optOutTracking method. To resume tracking for an individual user, use optInTracking. Call hasOptedOutTracking to check user’s opt-out status locally. By default, an "$opt_in" event is sent every time that a user opts in.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// Opt a user out of data collection

// Check a user's opt-out status
// Returns true of user is opted out of tracking locally
    Boolean hasOptedOutTracking = mixpanel.hasOptedOutTracking();

Opting Users Out of Tracking by Default

Mixpanel’s tracking libraries will send user data by default. Explicitly setting a default opt-out state of true will opt-out all users by default, preventing data from sending unless a user’s opt-out state is set to false.

// Initializing a default opt-out state of true 
// will prevent data from being collected by default

MixpanelAPI mixpanelOptOutDefault = 
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN, true);

Delete Existing Data

Opting users out of tracking will stop any future tracking. This does not automatically delete data that has already been collected. Mixpanel's deletion API can be used to delete existing data.

Sending Events

Once you've initialized the library, you can track an event using MixpanelAPI.track with the event name and properties.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

JSONObject props = new JSONObject();
props.put("Gender", "Female");
props.put("Plan", "Premium");

mixpanel.track("Plan Selected", props);

Timing Events

You can track the time it took for an action to occur, such as an image upload or a comment post, using timeEvent. This will mark the "start" of your action, which will be timed until you finish with a track call. The time duration is then recorded in the "Duration" property.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// start the timer for the event "Image Upload"
mixpanel.timeEvent("Image Upload");

// stop the timer if the imageUpload() method returns true
    mixpanel.track("Image Upload");

Super Properties

It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event - for example, the user's age, gender, source, or initial referrer.

To make things easier, you can register these properties as super properties. If you tell us just once that these properties are important, we will automatically include them with all events sent. Super properties are saved to device storage, and will persist across invocations of your app. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties here.

To set super properties, call MixpanelAPI.registerSuperProperties.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// Send a "User Type: Paid" property will be sent
// with all future track calls.
JSONObject props = new JSONObject();
props.put("User Type", "Paid");

The next time you track an event, the super properties you just set will be included as properties.

Super properties are saved to device storage, and will persist between executions of your app.

Setting Super Properties Once and Only Once

If you want to store a super property only once (for example, a date of first login), you can use MixpanelAPI.registerSuperPropertiesOnce. registerSuperPropertiesOnce behaves like registerSuperProperties and has the same interface, but it doesn't override super properties you've already saved.

This means it's safe to call registerSuperPropertiesOnce with the same property multiple times, and it will only set properties if the super property doesn't exist.

Super Properties Live in Local Storage

Our mobile libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove that customers super properties.

Group Analytics


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.

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

Grouping by identifiers other than the distinct_id will allow 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.

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.

Adding Users to a Group

Adding users to groups causes the group_key and group_id to send as a property key and value for all events triggered by that user on the device. You can add multiple values for a single user to the group_key list property.

Similar to a distinct_id, the group_key allows Mixpanel to group events by an identifier for analysis. A group_key, however, is a group level identifier and not a user level identifier like the distinct_id.

You can add users to groups by calling the setGroup() method.

mMixpanel.setGroup("group key", "group id");

You can call addGroup() to add any additional groups to an existing list.

mMixpanel.addGroup("group key", "group id");

You can call removeGroup() to remove any additional groups from an existing list.

mMixpanel.removeGroup("group key", "group id");

Creating Group Profiles

It is possible to create a Group profile that is similar to a user profile. You must call getGroup().set() to build a group profile. It is important to the group_key, group_id, and one property so that the profile is not empty.

mMixpanel.getGroup("group key", "group id").set("SET NAME", "SET VALUE");

Setting Group Profile Properties

You can add details to Groups by adding properties to them.

In order to update Group profile properties, you must specify the group that needs to be updated by calling getGroup().set().

mMixpanel.getGroup("group key", "group id").set("SET NAME", "SET VALUE");

mMixpanel.getGroup("group key", "group id").setMap((new HashMap<>()).put("SET MAP INT", 1));

The getGroup() method can be chained with other commands that edit properties specific to the group.

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.


mixpanel.getGroup().set() updates or adds a property to a group.

mMixpanel.getGroup("group key", "group id").set("SET NAME", "SET VALUE");

mMixpanel.getGroup("group key", "group id").setMap((new HashMap<>()).put("SET MAP INT", 1));

set once

mixpanel.getGroup().set_once() adds a property value to a group only if it has not been set before.

mMixpanel.getGroup("group key", "group id").setOnce("SET ONCE NAME", "SET ONCE VALUE");

mMixpanel.getGroup("group key", "group id").setOnceMap((new HashMap<>()).put("SET ONCE MAP STR", "SET ONCE MAP VALUE"));


mixpanel.getGroup().unset() unsets a specific property in the group.

mMixpanel.getGroup("group key", "group id").unset("UNSET NAME");


mixpanel.getGroup().remove() removes a specific value in a list property.

mMixpanel.getGroup("group key", "group id").remove("property name", "value to remove");


mixpanel.getGroup().union() adds the specified values to a list property and ensures that those values only appear once.

mMixpanel.getGroup("group key", "group id").union("UNION NAME", new JSONArray("[100]"));


mixpanel.getGroup().deleteGroup() deletes a group.

mMixpanel.getGroup("group key", "group id").deleteGroup();

Managing User Identity

You can handle the identity of a user using the identify and alias methods. Proper use of these methods can connect events to the correct user as they move across devices, browsers, and other platforms.


Identify a user with a unique ID to track user activity across devices, tie a user to their events, and create a user profile. If you never call this method, unique visitors are tracked using a UUID that generates the first time they use the app.

Call identify when you know the identity of the current user, typically after log-in or sign-up. We recommend against using identify for anonymous visitors to your site. To assign your own distinct_ids, you can use MixpanelAPI.identify and MixpanelAPI.getPeople().identify. We strongly recommend using the same distinct id for both calls.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// Ensure all future events sent from
// the device will have the distinct_id 13793

// Ensure all future user profile properties sent from
// the device will have the distinct_id 13793

In general, if you use identify, you should call it as soon as the user logs in to your application. This will track all of their authenticated application usage to the correct user ID.


ID Merge

If a project has ID Merge enabled, the identify method will connect pre- and post-authentication events when appropriate.

If a project does not have ID Merge enabled, identify will change the user's local distinct_id to the unique ID you pass. Events tracked prior to authentication will not be connected to the same user identity. If ID Merge is disabled, alias can be used to connect pre and post registration events.


The alias method creates an alias which Mixpanel will use to remap one id to another. Multiple aliases can point to the same identifier.






A unique identifier that you want to use as an identifier for this user.



The current user identifier.

The following is a valid use of alias:

// This makes the current ID (by default an auto-generated GUID)
// and '13793' interchangeable distinct ids (but not retroactively).
mixpanel.alias("13793", null);
// To create a user profile, you must call getPeople().identify

Aliases can also be chained - the following is a valid example:

mixpanel.alias("new_id", "existing_id");
// You can chain aliases
mixpanel.alias("newer_id", "new_id");

Aliases cannot point to multiple identifiers - the following example will not work:

mixpanel.alias("new_id", "existing_id");
//this is invalid as 'new_id' already points to 'existing_id'
mixpanel.alias("new_id", "newer_id");


ID Merge

If a project does not have ID Merge enabled, the best practice is to call alias once when a unique ID is first created for a user (e.g., when a user first registers for an account). Do not use alias multiple times for a single user without ID Merge enabled.

Call Reset at Logout

Reset generates a new random distinct_id and clears super properties. Call reset to clear data attributed to a user when that user logs out. This allows you to handle multiple users on a single device. For more information about maintaining user identity, see the Identity Management: Best Practices article.

Storing User Profiles

In addition to events, you can store user profiles in Mixpanel's Behavioral Analytics product. Profiles are persistent sets of properties that describe a user - things like name, email address, and signup date. 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.


Before you send profile updates, you must call getPeople().identify. The library uses a separate ID for User records, and you must set this value to send updates.

Setting Profile Properties

You can set properties on a user profile with MixpanelAPI.getPeople().set.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// identify must be called before
// user profile properties can be set

// Sets user 13793's "Plan" attribute to "Premium"
mixpanel.getPeople().set("Plan", "Premium");

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".



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 MixpanelAPI.getPeople().increment to change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, messages sent, or points earned.

// Add 500 to the current value of
// "points earned" in Mixpanel
mixpanel.getPeople().increment("points earned", 500);

// Pass a Map to increment multiple properties
Map<String, Integer> properties =
    new HashMap<String, Integer>();
properties.put("dollars spent", 17);
// Subtract by passing a negative value
properties.put("credits remaining", -34);


Appending to List Properties

getPeople.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 one element list as its value.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

//Identify the user profile that is going to be updated

//Add the color green to the list property "Favorite Colors"
//A new list property is created if it doesn't already exist
mixpanel.getPeople().append("Favorite Colors", "Green")

Other Types of Profile Updates

There are a few other types of profile updates. They can be accessed through the MixpanelPeople class, which is accessible via MixpanelAPI.getPeople().

Tracking Revenue

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

You can track a single transaction with MixpanelAPI.getPeople().trackCharge. This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, MIXPANEL_TOKEN);

// Make getPeople() identify has been
// called before making revenue updates

// Tracks $100 in revenue for user 13793
mixpanel.getPeople().trackCharge(100, null);

// Refund this user 50 dollars
mixpanel.getPeople().trackCharge(-50, null);

// Tracks $25 in revenue for user 13793
// on the 2nd of january
JSONObject properties = new JSONObject()
properties.put("$time", "2012-01-02T00:00:00");
mixpanel.getPeople().trackCharge(25, properties);

Push Notifications Guide


Messaging and Mobile A/B Testing Deprecation

Messaging and mobile A/B testing are not available for purchase and will be deprecated from the product on January 1st, 2022. Read more information on the Mixpanel blog.

Mixpanel provides a quick-start guide for setting up push for your Android app that covers setting up your Google API project, locating your project number, uploading your Google API Project key to Mixpanel, and configuring your application to register for and receive push notifications.

In-App Messages

There is a quick start guide for Android in app messages to help you get integrated.

Make sure that you have already:

  1. Included the latest version of the Mixpanel Android library in your app
  2. Made sure you are identifying your users in the app.
  3. Created an in-app message on the Messages tab of the Mixpanel website.

A/B Testing


Messaging and Mobile A/B Testing Deprecation

Messaging and mobile A/B testing are not available for purchase and will be deprecated from the product on January 1st, 2022. Read more information on the Mixpanel blog.


To use Mixpanel Android A/B testing, your app needs to be using version 4.6.0 or greater of the Mixpanel SDK. Make sure you are initializing the MixpanelAPI in your main activity using the project token that you wish to run tests in. See the quick start guide for installation steps.



Planning to run an experiment on the initial view of your app? It can take several seconds for experiments to be applied on first app open; as a result, we recommend against putting UX changes or developer Tweaks on the first view of your app. If you wish to A/B test on the initial app view you will need to take delivery latency into account. We recommend employing the addOnMixpanelUpdatesReceivedListener (to know when test data is available) and joinExperimentIfAvailable() method (to apply the variant data to the view).

Creating Your First A/B Test

Mixpanel A/B testing allows you to make changes to your app and deploy it to your users without a new release to the Google Play store. You can modify the look and feel of your app, change the copy, and even change the values of variables (using developer tweaks). Then you can see which version performs better without making any changes to your tracking code. Once you've installed the Mixpanel Android SDK, running your first A/B test is simple.

  1. Open the A/B testing tab and create a new experiment
  1. Open your app and connect to Mixpanel using the flip gesture. If production devices prevent your test device from connecting, follow these steps.

3 .Use the visual editor to make the changes you want

  1. Save and deploy your changes

Now the next time a user opens your app, they will receive the updated version. You can also use Mixpanel A/B testing to change the values of variables by taking advantage of developer tweaks.

Notes on Experiment Delivery

Mixpanel checks for any new experiments asynchronously each time your application is opened or resumed. After the response is received, experiment changes and tweaks are applied or removed where appropriate. To handle network availability, each experiment is cached on the device so they can be re-applied when the API call cannot be successfully made.

If you'd like more control over when this check for new experiments occurs, you can use the addOnMixpanelUpdatesReceivedListener listener and the joinExperimentIfAvailable method to download and apply experiments manually.

The $experiment_started event is fired when a given experiment (both changes and/or tweaks) is first started on a device. The event will contain an $experiment_id property with the given experiment id which we encourage use within funnels, and our other reports.

A/B Developer Tweaks

For more complex changes that you want to A/B test, you can send arbitrary data to your apps as part of A/B testing, through a mechanism called Tweaks. Tweaks allow you to control variables in your app directly from Mixpanel. For example, you can alter the difficulty of a game, choose different paths through the app, or change text. The possibilities are endless.

Using Tweaks in Your Application

You can declare a tweak using MixpanelAPI.booleanTweak, MixpanelAPI.stringTweak, MixpanelAPI.longTweak, MixpanelAPI.doubleTweak, and other static methods that declare a tweak name and set a default value. To add A/B testable logic to your app, you might do something like this:

package com.mixpanel.mygame;

import android.os.Bundle;


public class GameActivity extends Activity {
    private static Tweak<Double> gameSpeed = MixpanelAPI.doubleTweak("Game speed", 1.0);
  private static Tweak<Boolean> showAds = MixpanelAPI.booleanTweak("show ads",false);
  protected void onCreate(Bundle savedInstanceState) {
    runGame(gameSpeed.get()); // pass in game speed for this A/B test, defaulted         //to 1.0
  if (showAds.get()) { //do we want to show ads in this A/B test? default to            //false
  public void runGame(Double speed) {
    // ... logic to start a new game
  public void showAdBar() {
    // ... some logic that shows ads

When you create an A/B test, you will be able to change the value of any Tweak you create in your app!

Note that the class containing the Tweaks must be loaded for the Tweaks to appear in the A/B test builder.

Automatic Referrer Tracking

The Mixpanel library can automatically set super properties associated with how your users found your app in the Google Play Store. To enable this feature, just add the following dependency to your app build.gradle file:

dependencies {
    implementation ''

Once you've added this dependency, you will automatically send referrer information along with every event you send to Mixpanel.

App Links Tracking

The Mixpanel library has built in support for tracking in-bound and out-bound App Links. App Links is a specification to help standardize deep-linking between apps as well as give you additional information about how users are getting to and from your own mobile app.


In order for Mixpanel to track App Links, your app must statisfy the following dependencies:



If your application does not meet these requirements, the Mixpanel library will log debug messages about App Links tracking not being enabled. This is NOT an error and can be safely ignored.

Tracking In-bound App Links

If a user comes to your app via an App Link, Mixpanel will automatically track a "$al_nav_in" event with meta information about where they came from.

Tracking Out-bound App lLnks

If you're linking to other applications using the Bolts framework, Mixpanel will track a $al_nav_out event with additional meta information about where the user is being linked to.


Debugging and Logging

Enabling Mixpanel debugging and logging allows you to see the debug output from the Mixpanel Android library. This may be useful in determining when track calls go out or in-app messages are fetched. To enable Mixpanel debugging and logging, you will want to add the following permission within your AndroidManifest.xml inside the <application> tag:

      android:value="true" />

EU Data Residency

Route data to Mixpanel's EU servers by adding meta-data entries under the <application> tag of your app's AndroidManifest.xml.

<meta-data android:name=""
           android:value="" />
<meta-data android:name=""
           android:value="" />
<meta-data android:name=""
           android:value="" />
<meta-data android:name="" 
           android:value="" />

Release History

See All Releases.

Updated 3 months ago

Android - Advanced

Suggested Edits are limited on API Reference Pages

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