diff --git a/docs/tracking-methods/sdks/android.mdx b/docs/tracking-methods/sdks/android.mdx index fe40ca3e..95a2c787 100644 --- a/docs/tracking-methods/sdks/android.mdx +++ b/docs/tracking-methods/sdks/android.mdx @@ -1,6 +1,6 @@ --- -sidebarTitle: "Android" title: "Mixpanel SDKs: Android" +sidebarTitle: "Android" --- ## Getting Started @@ -22,7 +22,7 @@ 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. -![image](/images/android_install_image.png) + ![image](/images/android_install_image.png) 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`. @@ -52,7 +52,7 @@ events and properties to Mixpanel. android:name="android.permission.BLUETOOTH" /> ``` -After the installation, import the library and initialize Mixpanel in your code by calling [`MixpanelAPI.getInstance()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getInstance(android.content.Context,java.lang.String,boolean)) with your application context, your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens), and `false` value for automatic events. +After the installation, import the library and initialize Mixpanel in your code by calling [`MixpanelAPI.getInstance()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getInstance\(android.content.Context,java.lang.String,boolean\)) with your application context, your [project token](/docs/orgs-and-projects/managing-projects#find-your-project-tokens), and `false` value for automatic events. ```java Java import com.mixpanel.android.mpmetrics.MixpanelAPI; @@ -72,13 +72,16 @@ public class MainActivity extends ActionBarActivity { ### 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](/docs/tracking-methods/sdks/android#privacy-friendly-tracking). + + 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](/docs/tracking-methods/sdks/android#privacy-friendly-tracking). + The library can be initialized with different configurations. See a complete list of the configuration options and methods under [`MPConfig`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MPConfig.html). You can set the library configuration by adding `meta-data` entries under the `` of your app's `AndroidManifest.xml`. **Example Usage** + ```xml Java The [/track endpoint](/reference/track-event) 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. @@ -124,12 +127,12 @@ props.put('Plan', 'Premium'); 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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#timeEvent(java.lang.String)). 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. +You can track the time it took for an action to occur, such as an image upload or a comment post, using [`.timeEvent()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#timeEvent\(java.lang.String\)). 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 Java MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, MIXPANEL_TOKEN, false); @@ -147,11 +150,13 @@ if(imageUpload()){ ``` ### 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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#flush()) manually if you want to force a flush at a particular moment. +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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#flush\(\)) manually if you want to force a flush at a particular moment. **Example Usage** + ```java Java // flush batched events for ingestion immediately mixpanel.flush(); @@ -159,15 +164,17 @@ mixpanel.flush(); **Flush Batch Size** -By default, Mixpanel will flush events immediately if a batch reaches 50 events. Use the [`.setFlushBatchSize()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setFlushBatchSize(int)) method to adjust the batch size limit for flushing. +By default, Mixpanel will flush events immediately if a batch reaches 50 events. Use the [`.setFlushBatchSize()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setFlushBatchSize\(int\)) method to adjust the batch size limit for flushing. **Example Usage** + ```java 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](/reference/track-event), 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](/reference/import-events) which is optimized for scripting and supports ingesting historical data. We recommend the [Python SDK](/docs/tracking-methods/sdks/python) (see the [`.import_data()`](https://mixpanel.github.io/mixpanel-python/#primary-interface) function) and [mixpanel-utils module](https://github.com/mixpanel/mixpanel-utils) (see the [`import_events()`](https://github.com/mixpanel/mixpanel-utils?tab=readme-ov-file#import-events) function) which both leverages the /import API for event ingestion. @@ -176,10 +183,9 @@ For bulk import of historical events older than 5 days, we will need to use the Super properties are global event properties that you define once and apply to all events. -To register super properties, call [`.registerSuperProperties()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperProperties(org.json.JSONObject)). - -Use [`.registerSuperPropertiesOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperPropertiesOnce(org.json.JSONObject)) to register super properties without overwriting existing values. +To register super properties, call [`.registerSuperProperties()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperProperties\(org.json.JSONObject\)). +Use [`.registerSuperPropertiesOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#registerSuperPropertiesOnce\(org.json.JSONObject\)) to register super properties without overwriting existing values. ```java Java MixpanelAPI mixpanel = @@ -203,9 +209,11 @@ mixpanel.registerSuperPropertiesOnce(moreProps); // 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 Java // create object of super properties @@ -223,16 +231,16 @@ Our mobile libraries store your super properties in local storage. They will per See more methods related to super properties in the complete library reference [here](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html). ## Managing User Identity -You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify(java.lang.String,boolean)) and [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#reset()) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users). +You can handle the identity of a user using the [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify\(java.lang.String,boolean\)) and [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#reset\(\)) methods. Learn more about [identity management](/docs/tracking-methods/id-management/identity-management) and [identifying users](/docs/tracking-methods/id-management/identifying-users). ### Identify - We recommend against calling `.identify()` for anonymous visitors to your site. + We recommend against calling `.identify()` for anonymous visitors to your site. -Call [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify(java.lang.String,boolean)) 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. +Call [`.identify()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#identify\(java.lang.String,boolean\)) 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 Java // create Mixpanel instance @@ -249,9 +257,10 @@ mixpanel.identify('12345'); ### Call Reset at Logout -Call [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#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](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device). +Call [`.reset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#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](/docs/tracking-methods/id-management/identifying-users-simplified#multiple-users-one-device). **Example Usage** + ```java Java // your user logs out and tracks a log out event mixpanel.track('log out'); @@ -265,12 +274,13 @@ mixpanel.reset(); The Android SDK provides a [`DeviceIdProvider`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/DeviceIdProvider.html) 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. + 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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelOptions.Builder.html) 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 Java // create a device ID provider DeviceIdProvider provider = () -> { @@ -310,7 +320,7 @@ DeviceIdProvider ephemeralProvider = () -> { Once your users are identified, create [user profiles](/docs/data-structure/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`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html) interface accessible via [`.getPeople()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getPeople()). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set). +The Android SDK provides a few methods for setting profile properties under the [`MixpanelAPI.People`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html) interface accessible via [`.getPeople()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getPeople\(\)). These methods will trigger requests to the [/engage API endpoint](/reference/profile-set). ### Setting Profile Properties @@ -318,11 +328,12 @@ The Android SDK provides a few methods for setting profile properties under the 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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#set(org.json.JSONObject)) method. +Set profile properties on a user profile by calling the [`.getPeople().set()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#set\(org.json.JSONObject\)) 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 Java MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, 'YOUR_PROJECT_TOKEN', false); @@ -338,122 +349,126 @@ 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](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html) A few commonly used people methods are highlighted below: - The [`.getPeople().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#setOnce(org.json.JSONObject)) 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. + The [`.getPeople().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#setOnce\(org.json.JSONObject\)) 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 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'); ``` - The [`.getPeople().append()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#append(java.lang.String,java.lang.Object)) method append values to a list profile property. + The [`.getPeople().append()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#append\(java.lang.String,java.lang.Object\)) 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 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'); ``` - - The [`.getPeople().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#union(java.lang.String,org.json.JSONArray)) method append new values to a list property, excluding duplicates. + The [`.getPeople().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#union\(java.lang.String,org.json.JSONArray\)) 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 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'); ``` - - The [`.getPeople().increment()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#increment(java.lang.String,double)) method increments a numeric property by a whole number. + The [`.getPeople().increment()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.People.html#increment\(java.lang.String,double\)) 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 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](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-project-settings) first. + Read more about [Group Analytics](/docs/data-structure/group-analytics) before proceeding. You will need to have the [group key defined in your project settings](/docs/data-structure/group-analytics#group-keys-in-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.) + +- `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. @@ -461,9 +476,10 @@ The Android SDK provides a few method for adding individual users to a group and [All events must have the group key as an event property in order to be attributed to a group](/docs/data-structure/group-analytics#group-keys-tracked-as-event-properties). Without the group key, an event cannot be attributed to a group. -Call the [`.setGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setGroup(java.lang.String,java.util.List)) 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. +Call the [`.setGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#setGroup\(java.lang.String,java.util.List\)) 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 Java // assign the current user to the "mixpanel" company group mixpanel.setGroup('company', 'mixpanel'); @@ -483,9 +499,10 @@ mixpanel.track('some_event', groupKey) [An event can be attributed to multiple groups](/docs/data-structure/group-analytics#attribute-events-to-multiple-groups) by passing in the `group_key` value as a list of multiple `group_id` values. -Call [`.addGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#addGroup(java.lang.String,java.lang.Object)) to add additional `group_id`s to an existing list. +Call [`.addGroup()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#addGroup\(java.lang.String,java.lang.Object\)) to add additional `group_id`s to an existing list. **Example Usage** + ```java Java // assign the current user to the "mixpanel" company group // events will contain 'company' prop set to ["mixpanel"] @@ -518,11 +535,13 @@ 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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getGroup(java.lang.String,java.lang.Object)), then set the group properties by chaining the [`.set()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#set(org.json.JSONObject)) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property). +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()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#getGroup\(java.lang.String,java.lang.Object\)), then set the group properties by chaining the [`.set()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#set\(org.json.JSONObject\)) method, which will trigger a request to the [/groups API endpoint](/reference/group-set-property). **Example Usage** + ```java Java // assign the current user to the "mixpanel" company group mixpanel.setGroup('company', 'mixpanel'); @@ -533,78 +552,80 @@ mixpanel.getGroup('company','mixpanel').set('industry','analytics'); ``` ### Other Group Profile Methods + See all of the methods under the Group class [here](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html). A few commonly used group methods are highlighted below: - The [`.getGroup().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#setOnce(org.json.JSONObject)) 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. + The [`.getGroup().setOnce()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#setOnce\(org.json.JSONObject\)) 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 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'); ``` - - The [`.getGroup().unset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#unset(java.lang.String)) method removes a group property from a group profile. + The [`.getGroup().unset()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#unset\(java.lang.String\)) 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 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 ``` - - The [`.getGroup().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#union(java.lang.String,org.json.JSONArray)) method append new values to a list property, excluding duplicates. + The [`.getGroup().union()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#union\(java.lang.String,org.json.JSONArray\)) 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 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', [ @@ -612,18 +633,18 @@ A few commonly used group methods are highlighted below: 'alerts' ]); ``` - - The [`.getGroup().remove()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#remove(java.lang.String,java.lang.Object)) method removes a value from a list-valued group profile property. + The [`.getGroup().remove()`](https://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.Group.html#remove\(java.lang.String,java.lang.Object\)) 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 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'}; @@ -631,7 +652,7 @@ A few commonly used group methods are highlighted below: 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'); @@ -646,7 +667,9 @@ Install the [Session Replay SDK for Android](/docs/tracking-methods/sdks/android ## Debugging and Logging ### Enable SDK logs + To enable debug mode, add the following permission within your `AndroidManifest.xml` inside the `` tag: + ```xml Java ... @@ -666,12 +689,14 @@ Learn more about [debugging](/docs/tracking-best-practices/debugging). 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 Java MixpanelAPI mixpanel = MixpanelAPI.getInstance(context, "YOUR_PROJECT_TOKEN"); mixpanel.setBackupHost("api-backup.mixpanel.com"); ``` **AndroidManifest.xml Configuration** + ```xml -Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start. + Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start. ```java Java @@ -785,7 +818,7 @@ You can also configure endpoints via `` tags in your `AndroidManifest 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. + Setting `serverURL` during initialization ensures all requests (events, profiles, and feature flags) use the correct endpoint from the start. ```java Java @@ -815,7 +848,6 @@ You can also configure endpoints via `` tags in your `AndroidManifest ... ``` - ### 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 `` tag of your app's `AndroidManifest.xml`. @@ -833,14 +865,16 @@ The Android SDK parse the request IP address to generate geolocation properties Learn more about [geolocation](/docs/tracking-best-practices/geolocation). ## App Links Tracking + The Mixpanel library has built in support for tracking in-bound and out-bound [App Links](https://developers.facebook.com/docs/applinks). 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](https://github.com/BoltsFramework/Bolts-Android) >= v1.1.2 -- [Android Support Library v4](https://developer.android.com/topic/libraries/support-library/features#v4)+. + +- [Bolts Framework](https://github.com/BoltsFramework/Bolts-Android) \>= v1.1.2 +- [Android Support Library v4](https://developer.android.com/topic/libraries/support-library/features#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. + 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** @@ -850,6 +884,7 @@ If a user comes to your app via an App Link, Mixpanel will automatically track a **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 Java ... bolts.AppLinkNavigation.navigateInBackground(this, "http://anotherapp.com/app/link"); @@ -862,14 +897,14 @@ This guide demonstrates how to route events from Mixpanel's Android SDKs via a p 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](https://github.com/mixpanel/tracking-proxy). This config redirects any calls made to your proxy server to Mixpanel. +**Step 1: Set up a proxy server** The simplest way is to use our [sample nginx config](https://github.com/mixpanel/tracking-proxy). 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** + ```java // route data to your proxy server mixpanel.setServerURL("https://"); @@ -880,10 +915,12 @@ mixpanel.setServerURL("https://"); 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** + ```java // 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`: @@ -893,5 +930,48 @@ You can also set your backup host in your `AndroidManifest.xml`: 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()`](https://github.com/mixpanel/mixpanel-android) overload. There is no passive default at the call site; you must pass `true` or `false` when you initialize. + +```java +// 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](https://docs.mixpanel.com/docs/tracking-methods/sdks/swift#legacy-automatically-tracked-events) 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): + +```xml + +``` + ## Release History -[See All Releases](https://github.com/mixpanel/mixpanel-android/releases). + +[See All Releases](https://github.com/mixpanel/mixpanel-android/releases). \ No newline at end of file