Mixpanel SDKs: Android

Getting Started

Please refer to our Quickstart Guide.

The Full API Reference, Library Source Code, and an Example Application is documented in our GitHub repo.

Installing the Library

We publish builds of our library to the Maven central repository as an .aar file. This file contains all of the classes, resources, and configurations that you’ll need to use the library.

To install the library inside Android Studio, declare it as dependency in your build.gradle file by adding the following line to the dependencies section in app/build.gradle:

Java

implementation "com.mixpanel.android:mixpanel-android:7.+"

Once you’ve updated your build.gradle file, force Android Studio to sync with your new configuration by clicking the “Sync Project with Gradle Files” icon at the top of the window.

This should download the .aar dependency at which point you’ll have access to the Mixpanel library API calls. If it cannot find the dependency, you should make sure you’ve specified mavenCentral() as a repository in your build.gradle.

In order for the library to work you’ll need to ensure that you’re requesting the following permissions in your AndroidManifest.xml:

Java

<!--
This permission is required to allow the application to send
events and properties to Mixpanel.
-->
<uses-permission
  android:name="android.permission.INTERNET" />

<!--
  This permission is optional but recommended so we can be smart
  about when to send data.
 -->
<uses-permission
  android:name="android.permission.ACCESS_NETWORK_STATE" />

<!--
  This permission is optional but recommended so events will
  contain information about bluetooth state
-->
<uses-permission
  android:name="android.permission.BLUETOOTH" />

After the installation, import the library and initialize Mixpanel in your code by calling MixpanelAPI.getInstance() with your application context, your project token, and false value for automatic events.

Java

import com.mixpanel.android.mpmetrics.MixpanelAPI;


public class MainActivity extends ActionBarActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        MixpanelAPI mixpanel = MixpanelAPI.getInstance(this, "YOUR_PROJECT_TOKEN", false);
    }
}

Library Configuration

For projects with EU or India data residency, you must configure the SDK to use the correct regional endpoint. Events sent to the wrong region will not be ingested. Learn more about Privacy-Friendly Tracking.

The library can be initialized with different configurations. See a complete list of the configuration options and methods under MPConfig.

You can set the library configuration by adding meta-data entries under the <application> of your app’s AndroidManifest.xml.

Example Usage

Java

<!-- disable auto flushing on app backgrounding -->
<meta-data android:name="com.mixpanel.android.MPConfig.FlushOnBackground"
           android:value="false" />
<!-- enable debug logs -->           
<meta-data android:name="com.mixpanel.android.MPConfig.EnableDebugLogging"
           android:value="true" />

The MPConfig provide a few methods that you can call to set and retrieve your configuration after the library has already been initialized.

Example Usage

Java

// initialize Mixpanel with automatic events disabled
trackAutomaticEvents = false;
MixpanelAPI mixpanel = 
    MixpanelAPI.getInstance(this, "YOUR_PROJECT_TOKEN", trackAutomaticEvents);

Sending Events

Use .track() to send an event by providing the event name and any event properties. This will trigger a request to the /track API endpoint to ingest the event into your project.

The /track endpoint will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.

Example Usage

Java

// initialize Mixpanel
MixpanelAPI mixpanel = 
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

//Create event properties object
JSONObject props = new JSONObject();
props.put('Gender', 'Female');
props.put('Plan', 'Premium');

//track "some_event"
// with "Gender" and "Plan" event properties
mixpanel.track('some_event', 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.

Example Usage

Java

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

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

// 20 seconds later...

// stop the timer if the imageUpload() method returns true
if(imageUpload()){
    // track "Image Upload" event with "Duration" event prop set to 20
    mixpanel.track("Image Upload");
}

Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn’t send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call .flush() manually if you want to force a flush at a particular moment.

Example Usage

Java

// flush batched events for ingestion immediately
mixpanel.flush();

Flush Batch Size

By default, Mixpanel will flush events immediately if a batch reaches 50 events. Use the .setFlushBatchSize() method to adjust the batch size limit for flushing.

Example Usage

Java

// flush if event batch size reaches 100
mixpanel.setFlushBatchSize(100);

Importing Historical Events

The Android SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling .track() triggers a request to our /track API endpoint, which will validate for events with a timestamp that is within the last 5 days of the request. Events older than 5 days will not be ingested.

For bulk import of historical events older than 5 days, we will need to use the /import API endpoint which is optimized for scripting and supports ingesting historical data. We recommend the Python SDK (see the .import_data() function) and mixpanel-utils module (see the import_events() function) which both leverages the /import API for event ingestion.

Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

To register super properties, call .registerSuperProperties().

Use .registerSuperPropertiesOnce() to register super properties without overwriting existing values.

Java

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// register "name" as a super property
JSONObject props = new JSONObject();
props.put('name', 'Sam');
mixpanel.registerSuperProperties(props);

//register "city" as an additional super property
// ignore "name" since it already exists
JSONObject moreProps = new JSONObject();
moreProps.put('name', 'Samantha');
moreProps.put('city', 'San Francisco');
mixpanel.registerSuperPropertiesOnce(moreProps);


//track "some_event"
// event will include "name" prop set to "Sam"
// and "city" prop set to "San Francisco"
mixpanel.track('some_event');

If you have properties you’d like all events to include, you can also set the super properties when initializing the Mixpanel object.

Example Usage

Java

// create object of super properties
JSONObject yourSuperProps = new JSONObject();
yourSuperProps.put('name', 'Samantha');
yourSuperProps.put('city', 'San Francisco');

//create Mixpanel instance with super properties above
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', yourSuperProps, false);

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.

See more methods related to super properties in the complete library reference here.

Managing User Identity

You can handle the identity of a user using the .identify() and .reset() methods. Learn more about identity management and identifying users.

Identify

We recommend against calling .identify() for anonymous visitors to your site.

Call .identify() when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

Java

// create Mixpanel instance
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// user logs in and tracks a sign in event
mixpanel.track('sign in');

// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
mixpanel.identify('12345');

Call Reset at Logout

Call .reset() to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle multiple users on a single device.

Example Usage

Java

// your user logs out and tracks a log out event
mixpanel.track('log out');

// clear local storage and generate new distinct_id
mixpanel.reset();

Custom Device ID Generation

The Android SDK provides a DeviceIdProvider interface for implementing custom device ID generation logic. This allows you to control where device IDs are stored and whether they persist across .reset() calls.

Using a custom device ID provider is an architectural decision that should be made at project inception. Changing this after deployment can cause user identity management issues.

Configure the device ID provider using MixpanelOptions.Builder() when initializing the SDK. If the provider returns null, an empty string, or throws an exception, the SDK will fall back to generating a UUID-based device ID.

Example Usage

Java

// create a device ID provider
DeviceIdProvider provider = () -> {
    return getYourCustomDeviceId();
};

// configure Mixpanel with custom device ID provider
MixpanelOptions options = new MixpanelOptions.Builder()
    .deviceIdProvider(provider)
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(
    context,
    "YOUR_PROJECT_TOKEN",
    false,
    options
);

Persistent vs Ephemeral IDs

Returning the same value each time the provider is called creates a persistent device ID that survives .reset() calls. Returning different values generates a new device ID on each reset.

Java

// persistent ID - survives reset() calls
DeviceIdProvider persistentProvider = () -> {
    return getStoredDeviceId(); // returns same value every time
};

// ephemeral ID - changes on reset() calls
DeviceIdProvider ephemeralProvider = () -> {
    return generateNewDeviceId(); // returns new value each time
};

Storing User Profiles

Once your users are identified, create user profiles by setting profile properties to describe them. Example profile properties include “name”, “email”, “company”, and any other demographic details about the user.

The Android SDK provides a few methods for setting profile properties under the MixpanelAPI.People interface accessible via .getPeople(). These methods will trigger requests to the /engage API endpoint.

Setting Profile Properties

You must call .identify() before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.

Set profile properties on a user profile by calling the .getPeople().set() method.

If a profile property already exists, it will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

Example Usage

Java

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

// You must call identify to associate the profile update with the user
// the first param is for the user ID
// the second param is a flag for allowing profile updates
mixpanel.identify('12345', true);

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

// Update "plan" from "Premium" to "Enterprise"
mixpanel.getPeople().set('plan', 'Enterprise');

Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods here

A few commonly used people methods are highlighted below:

.setOnce()

The .getPeople().setOnce() method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set profile properties without the risk of overwriting existing data.

Example Usage

Java

// set profile properties for user "1234"
JSONObject props = new JSONObject();
props.put('name', 'Sam');

mixpanel.identify('1234', true);
mixpanel.getPeople().set(props);

// will be ignored since "name" already exists
mixpanel.getPeople().setOnce('name', 'Samantha');

// set "location" group prop since it does not exist
mixpanel.getPeople().setOnce('location', 'us');

.append()

The .getPeople().append() method append values to a list profile property.

Use this method to add additional values to an existing list property instead of redefining the entire list.

Example Usage

Java

// set profile properties for user "1234"
JSONObject props = new JSONObject();
String roles[] = {'sales','engineer'};
props.put('name', 'Sam');
props.put('roles', roles);

mixpanel.identify('1234', true);
mixpanel.getPeople().set(props);

// add "legal" to "roles"  
// new role values are ['sales','engineer','legal']
mixpanel.getPeople().append('roles', 'legal');

// .append() allows duplicates
// new "roles" values are ['sales','engineer','legal', 'legal']
mixpanel.getPeople().append('roles', 'legal');

.union()

The .getPeople().union() method append new values to a list property, excluding duplicates.

Use this method to create a list profile property that only contains unique values without duplicates.

Example Usage

Java

// set profile properties for user "1234"
JSONObject props = new JSONObject();
String roles[] = {'sales','engineer'};
props.put('name', 'Sam');
props.put('roles', roles);

mixpanel.identify('1234', true);
mixpanel.getPeople().set(props);

// append "engineer" to "roles"
// will be ignored since "engineer" already exists in "roles"
mixpanel.getPeople().union('roles', 'engineer');

// append "legal" to "roles"
// new role values are ['sales','engineer','legal']
mixpanel.getPeople().union('roles', 'legal');

.increment()

The .getPeople().increment() method increments a numeric property by a whole number.

Use this method to add to or subtract from your numeric property based on its current value.

Example Usage

Java

// set profile properties for user "1234"
JSONObject props = new JSONObject();
props.put('name', 'Sam');
props.put('age', 25);

mixpanel.identify('1234', true);
mixpanel.getPeople().set(props);

// increment "age" by 2
mixpanel.getPeople().increment('age',2);

// use negative number to decrement
// decrement "age" by 5
mixpanel.getPeople().increment('age',-5);

Group Analytics

Read more about Group Analytics before proceeding. You will need to have the group key defined in your project settings first.

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the group_key and group_id.

• group_key is the event property that connects event data to a group. (e.g. company)
• group_id is the identifier for a specific group. (e.g. mixpanel,company_a,company_b, etc.)

The Android SDK provides a few method for adding individual users to a group and setting group profile properties.

Adding Users to a Group

All events must have the group key as an event property in order to be attributed to a group. Without the group key, an event cannot be attributed to a group.

Call the .setGroup() method to register the current user to a group, which would add the group_key as an event property set to the group_id value to all events moving forward.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');
 
// track "some_event"
// event property "company" = ["mixpanel"] is added automatically
mixpanel.track('some_event');

//alternatively you can manually define the group key
JSONObject groupKey = new JSONObject();
groupKey.put('company','mixpanel');

mixpanel.track('some_event', groupKey)

Multiple Groups

An event can be attributed to multiple groups by passing in the group_key value as a list of multiple group_id values.

Call .addGroup() to add additional group_ids to an existing list.

Example Usage

Java

// assign the current user to the "mixpanel" company group
// events will contain 'company' prop set to ["mixpanel"]
mixpanel.setGroup('company', 'mixpanel');

// add "mp-us" as an additional company group
// new "company" value is ["mixpanel","mp-us"]
mixpanel.addGroup('company', 'mp-us');

// track "some_event"
// event property "company" = ["mixpanel","mp-us"] is added automatically
mixpanel.track('some_event');

Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the group_key and group_id as a user profile property using the .getPeople().set() call.

Example Usage

Java

MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false);

mixpanel.identify('12345', true);

// Sets group key "company" as a user prop 
// with group id "mixpanel" as the value
mixpanel.getPeople().set('company', 'mixpanel');

Setting Group Profile Properties

Create a group profile by setting group properties, similar to a user profile. For example, you may want to describe a company group with properties such as “ARR”, “employee_count”, and “subscription”.

To set group profile properties, specify the group that needs to be updated by calling .getGroup(), then set the group properties by chaining the .set() method, which will trigger a request to the /groups API endpoint.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// specify the target group using the group_key and group_id
// set "industry" as a group profile prop to "analytics"
mixpanel.getGroup('company','mixpanel').set('industry','analytics');

Other Group Profile Methods

See all of the methods under the Group class here.

A few commonly used group methods are highlighted below:

.setOnce()

The .getGroup().setOnce() method set group profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set group profile properties without the risk of overwriting existing data.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// set group profile properties
JSONObject groupProps = new JSONObject();
groupProps.put('name', 'Mixpanel');

mixpanel.getGroup('company','mixpanel').set(groupProps);

// ignored since "name" is already exists
mixpanel.getGroup('company','mixpanel').setOnce('name','mp');

// set "location" group prop since it does not exist
mixpanel.getGroup('company','mixpanel').setOnce('location','us');

.unset()

The .getGroup().unset() method removes a group property from a group profile.

Use this method to delete unwanted group profile properties from a specific group profile.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// set group profile properties
JSONObject groupProps = new JSONObject();
groupProps.put('name', 'Mixpanel');
groupProps.put('employee_count', '100');

mixpanel.getGroup('company','mixpanel').set(groupProps);

// delete "employee_count" from the group profile
mixpanel.getGroup('company','mixpanel').unset('employee_count');

// only "name" remains as a group prop

.union()

The .getGroup().union() method append new values to a list property, excluding duplicates.

Use this method to create a list group profile property that only contains unique values without duplicates.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// set group profile properties
JSONObject groupProps = new JSONObject();
String features[] = {'reports','alerts','cohorts'};
groupProps.put('name', 'Mixpanel');
groupProps.put('features', features);

mixpanel.getGroup('company','mixpanel').set(groupProps);


// add "data pipeline" to "features" prop
// ignore "alert" since it is a duplicate value
mixpanel.getGroup('company','mixpanel').union('features', [
    'data pipeline',
    'alerts'
    ]);

.remove()

The .getGroup().remove() method removes a value from a list-valued group profile property.

Use this method to remove specific values from a list without affecting all of the other values in the list.

Example Usage

Java

// assign the current user to the "mixpanel" company group
mixpanel.setGroup('company', 'mixpanel');

// set group profile properties
JSONObject groupProps = new JSONObject();
String features[] = {'reports','alerts','cohorts'};
groupProps.put('name', 'Mixpanel');
groupProps.put('features', features);

mixpanel.getGroup('company','mixpanel').set(groupProps);

//remove "alerts" from "features"
// "features" now contain ["reports","cohorts"]
mixpanel.getGroup('company','mixpanel').remove('features', 'alerts');

Session Replay

Install the Session Replay SDK for Android to record replay data. Learn more about Session Replay and implementing Session Replay on Android.

Debugging and Logging

Enable SDK logs

To enable debug mode, add the following permission within your AndroidManifest.xml inside the <application> tag:

Java

...
<application>
    <!-- enable debug logging-->
    <meta-data
      android:name="com.mixpanel.android.MPConfig.EnableDebugLogging"
      android:value="true" />
    ...
</application>
...

Learn more about debugging.

Network Failover

Configure a backup host for automatic failover when the primary API endpoint is unreachable. The default primary endpoint is api.mixpanel.com (or your configured custom endpoint for EU/India data residency or proxy server). This can be used as a troubleshooting fallback when network calls to the Mixpanel endpoint are blocked or unreachable.

Setup

Java

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN");
mixpanel.setBackupHost("api-backup.mixpanel.com");

AndroidManifest.xml Configuration

<application>
    <meta-data
      android:name="com.mixpanel.android.MPConfig.BackupHost"
      android:value="api-backup.mixpanel.com" />
</application>

The SDK automatically retries failed requests to the backup host, preserving the same URL path, authentication, and headers as the primary.

How It Works

Failover triggers:

• Network failures (connection timeout, DNS errors)
• Non 4xx HTTP status codes

No failover for:

• Client errors (HTTP 4xx) - indicates invalid request
• Successful responses (HTTP 200 OK)
• Parse errors

This works with proxy server setups as well - if the proxy fails, the backup will be tried.

Requirements

Your backup host must:

• Support the same API endpoints (/track/, /engage/, /groups/)
• Accept the same authentication mechanism as the primary host
• Use the same URL scheme and port as configured for the primary host

Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Android SDK provide methods to help you protect user data.

Learn more about Privacy.

Opt Out of Tracking

The Android SDK is initialized with tracking enabled by default. Use the .optOutTracking() method to opt the user out of data tracking and local storage for the current Mixpanel instance.

Example Usage

Java

//send "some_event"
mixpanel.track('some_event');

// opt user out of tracking
// SDK is prevented from sending any data
mixpanel.optOutTracking();

// this track call will not work
mixpanel.track('some_other_event');

Opt Out by Default

You can initialize the library with users opted out of tracking by default using the optOutTrackingDefault configuration. Once the user is ready to be tracked, call .optInTracking() to start tracking.

Example Usage

Java

// users opted out of tracking by default
optOutTrackingDefault = true;
trackAutomaticEvents = false;
MixpanelAPI mixpanel =
    MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', optOutTrackingDefault, trackAutomaticEvents);


// this track call will not work
mixpanel.track('some_event');

// opt user back into tracking
mixpanel.optInTracking();
 
// this track call will work
mixpanel.track('some_other_event');

EU Data Residency

Route data to Mixpanel’s EU servers by setting the serverURL to https://api-eu.mixpanel.com during initialization using MixpanelOptions.

Setting serverURL during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start.

Java

MixpanelOptions options = new MixpanelOptions.Builder()
    .serverURL("https://api-eu.mixpanel.com")
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", trackAutomaticEvents, options);

You can also configure endpoints via <meta-data> tags in your AndroidManifest.xml under the <application> tag:

Java

...
<application>
    <!--set request URLs to Mixpanel EU domain-->
    <meta-data android:name="com.mixpanel.android.MPConfig.EventsEndpoint"
           android:value="https://api-eu.mixpanel.com/track?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.PeopleEndpoint"
           android:value="https://api-eu.mixpanel.com/engage?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.GroupsEndpoint"
           android:value="https://api-eu.mixpanel.com/groups" />
    <meta-data android:name="com.mixpanel.android.MPConfig.FlagsEndpoint"
           android:value="https://api-eu.mixpanel.com/flags" />
    ...
</application>
...

India Data Residency

Route data to Mixpanel’s India servers by setting the serverURL to https://api-in.mixpanel.com during initialization using MixpanelOptions.

Setting serverURL during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start.

Java

MixpanelOptions options = new MixpanelOptions.Builder()
    .serverURL("https://api-in.mixpanel.com")
    .build();

MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", trackAutomaticEvents, options);

You can also configure endpoints via <meta-data> tags in your AndroidManifest.xml under the <application> tag:

Java

...
<application>
    <!--set request URLs to Mixpanel India domain-->
    <meta-data android:name="com.mixpanel.android.MPConfig.EventsEndpoint"
           android:value="https://api-in.mixpanel.com/track?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.PeopleEndpoint"
           android:value="https://api-in.mixpanel.com/engage?ip=1" />
    <meta-data android:name="com.mixpanel.android.MPConfig.GroupsEndpoint"
           android:value="https://api-in.mixpanel.com/groups" />
    <meta-data android:name="com.mixpanel.android.MPConfig.FlagsEndpoint"
           android:value="https://api-in.mixpanel.com/flags" />
    ...
</application>
...

Disable Geolocation

The Android SDK parse the request IP address to generate geolocation properties for events and profiles. To disable geolocation, add the following meta-data entry under the <application> tag of your app’s AndroidManifest.xml.

Java

<application>
...
  <!-- disable geolocation parsing -->
  <meta-data android:name="com.mixpanel.android.MPConfig.UseIpAddressForGeolocation" 
            android:value="false" />
...
</application>

Learn more about geolocation.

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 satisfy the following dependencies:

• Bolts Framework >= v1.1.2
• Android Support Library v4+.

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 Links

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.

Java

...
bolts.AppLinkNavigation.navigateInBackground(this, "http://anotherapp.com/app/link");
...

Tracking Via Proxy

This guide demonstrates how to route events from Mixpanel’s Android SDKs via a proxy in your own domain. This is useful to reduce the likelihood of ad-blockers impacting your tracking.

There are two steps: setting up a proxy server and pointing the SDK at your server.

Step 1: Set up a proxy server The simplest way is to use our sample nginx config. This config redirects any calls made to your proxy server to Mixpanel.

Step 2: Point Android SDK at your server

Add the following line, replacing YOUR_PROXY_DOMAIN with your proxy server’s domain.

Example Usage

// route data to your proxy server
mixpanel.setServerURL("https://<YOUR_PROXY_DOMAIN>");

Backup Host

When you set a backup host, the SDK will first attempt to send data to the primary Mixpanel endpoint. If this request fails, the SDK will then automatically retry the request using the specified backup host. The SDK will use the same URL path, protocol (HTTP/HTTPS), and query parameters as the original request, only replacing the primary host portion of the URL with the backup host.

Example Usage via SDK

// route data to your backup host
mixpanel.setBackupHost("my.backuphost.com");

Example Usage via AndroidManifest.xml

You can also set your backup host in your AndroidManifest.xml:

Java

<meta-data android:name="com.mixpanel.android.MPConfig.BackupHost" 
           android:value="my.backuphost.com" />

Legacy Automatically Tracked Events

Mixpanel’s SDKs have a legacy feature to automatically collect common mobile events. We don’t recommend enabling this, as these events rely on client-side state and can be unreliable.

Unlike the Swift SDK — where trackAutomaticEvents is an optional parameter that defaults to false — the Android SDK requires trackAutomaticEvents as an explicit, required parameter on every MixpanelAPI.getInstance() overload. There is no passive default at the call site; you must pass true or false when you initialize.

// Automatic events disabled (recommended)
MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", false);

// Automatic events enabled
MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN", true);

Note: As of Android SDK v7.0.0, trackAutomaticEvents became a required parameter. This change removed the previous server-side API call that fetched the Autotrack setting, so the behavior is now controlled entirely in your initialization code rather than from project settings.

See the table below for the automatic events tracked by the Android SDK when trackAutomaticEvents is enabled:

Raw Name	Display Name	Description
$ae_first_open	First App Open	Tracks the first time the user has opened the app. This event is retriggered if the user reinstalls the app or clears local storage.
$ae_updated	App Updated	Executes when a user updates the app from the previous version. A Version Updated ($ae_updated_version) property is tracked to store the new app version.
$ae_session	App Session	Executes when a user spends more than 10 seconds in the app, evaluated when the app moves to the background. A Session Length ($ae_session_length) property is tracked to reflect the number of seconds user spent in the session. In addition, there are two user properties tracked: Total App Sessions ($ae_total_app_sessions) and Total App Session Length ($ae_total_app_session_length).
$ae_crashed	App Crashed	Executes when the app crashes due to an uncaught exception. A Crash Reason ($ae_crashed_reason) property is tracked to store details about the crash.

Differences from the Swift SDK

The set of automatic events is not identical across platforms:

• $ae_crashed is tracked on Android only. The Swift SDK does not track app crashes automatically.
• $ae_iap (In-App Purchase) is tracked on iOS only. The Android SDK does not track in-app purchases automatically. If you need IAP tracking on Android, implement it manually with track() calls.

Configuring the Session Threshold

By default, the App Session ($ae_session) event fires only when a session lasts at least 10 seconds. You can change this minimum through AndroidManifest.xml metadata (value in milliseconds):

<meta-data
    android:name="com.mixpanel.android.MPConfig.MinimumSessionDuration"
    android:value="10000" />  <!-- 10 seconds -->

Release History

See All Releases.