Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README for the quick start guide #749

Merged
merged 1 commit into from
Jun 28, 2021
Merged

Improve README for the quick start guide #749

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/workflows/android.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,14 @@ on:

jobs:
build:
runs-on: macos-latest
runs-on: macos-11
steps:
- name: Checkout the code
uses: actions/checkout@v2
- name: Run Unit test
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 27
profile: Nexus 5
script: ./gradlew createDebugCoverageReport
- name: Lint
run: ./gradlew lint
Expand Down
129 changes: 92 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<img src="https://github.com/mixpanel/mixpanel-android/blob/assets/mixpanel.png?raw=true" alt="Mixpanel Android Library" height="150"/>
</p>

# Latest Version [![Build Status](https://travis-ci.org/mixpanel/mixpanel-android.svg)](https://travis-ci.org/mixpanel/mixpanel-android)
# Latest Version

##### _May 18, 2021_ - [v5.9.1](https://github.com/mixpanel/mixpanel-android/releases/tag/v5.9.1)

Expand All @@ -11,8 +11,11 @@
<!-- MarkdownTOC -->

- [Quick Start Guide](#quick-start-guide)
- [Installation](#installation)
- [Integration](#integration)
- [Install Mixpanel](#1-install-mixpanel)
- [Initialize Mixpanel](#2-initialize-mixpanel)
- [Send Data](#3-send-data)
- [Check for Success](#4-check-for-success)
- [FAQ](#i-want-to-know-more)
- [I want to know more!](#i-want-to-know-more)
- [Want to Contribute?](#want-to-contribute)
- [Changelog](#changelog)
Expand All @@ -25,64 +28,116 @@

Check out our **[official documentation](https://mixpanel.com/help/reference/android)** for more in depth information on installing and using Mixpanel on Android.

<a name="installation"></a>
## Installation
## 1. Install Mixpanel
You will need your project token for initializing your library. You can get your project token from [project settings](https://mixpanel.com/settings/project).

### Dependencies in *app/build.gradle*
**Step 1 - Add the mixpanel-android library as a gradle dependency:**
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, you can simply declare it as dependency in your build.gradle file.

Add the following lines to the `dependencies` section in *app/build.gradle*

```gradle
implementation "com.mixpanel.android:mixpanel-android:5.+"
implementation "com.google.firebase:firebase-messaging:17.3.4" // optional, if push notifications are used
implementation "com.android.installreferrer:installreferrer:1.1" // optional, if you want to know how users installed your app
```java
dependencies {
implementation 'com.mixpanel.android:mixpanel-android:5.+'
}
```

On Jan 1, 2022, we’ll remove the [Messages & Experiments](https://mixpanel.com/blog/why-were-sunsetting-messaging-and-experiments/#:~:text=A%20year%20from%20now%2C%20on,offering%20discounts%20for%20getting%20started) feature from Mixpanel. For now, you can choose to opt in to our beta version without the Messages & Experiments feature support.

```gradle
implementation "com.mixpanel.android:mixpanel-android:6.0.0-beta+"
```
Once you've updated your build.gradle file, you can force Android Studio to sync with your new configuration by clicking the Sync Project with Gradle Files icon at the top of the window.

### Permissions in *app/src/main/AndroidManifest.xml*
![Sync Android With Gradle](https://storage.googleapis.com/cdn-mxpnl-com/static/readme/android-sync-gradle.png)

```xml
<!-- This permission is required to allow the application to send events and properties to Mixpanel -->
<uses-permission android:name="android.permission.INTERNET" />
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`.

<!-- 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" />
**Step 2 - Add permissions to your AndroidManifest.xml:**
In order for the library to work you'll need to ensure that you're requesting the following permissions in your AndroidManifest.xml:

<!-- This permission is optional but recommended so events will contain information about bluetooth state -->
<uses-permission android:name="android.permission.BLUETOOTH" />
```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" />
```
At this point, you're ready to use the Mixpanel Android library inside Android Studio.

<a name="integration"></a>
## Integration
## 2. Initialize Mixpanel
Once you've set up your build system or IDE to use the Mixpanel library, you can initialize it in your code by calling MixpanelAPI.getInstance with your application context and your Mixpanel project token. You can find your token in [project settings](https://mixpanel.com/settings/project).

### Initialization
```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_TOKEN");
}
}
```
[See all configuration options](http://mixpanel.github.io/mixpanel-android/index.html)

Initialize Mixpanel in your main activity *app/src/main/java/com/mixpanel/example/myapplication/MainActivity.java*. Usually this should be done in [onCreate](https://developer.android.com/reference/android/app/Activity.html#onCreate(android.os.Bundle)).
## 3. Send Data
Let's get started by sending event data. You can send an event from anywhere in your application. Better understand user behavior by storing details that are specific to the event (properties). After initializing the library, Mixpanel will [automatically collect common mobile events](https://mixpanel.com/help/questions/articles/which-common-mobile-events-can-mixpanel-collect-on-my-behalf-automatically). You can enable/disable automatic collection through your [project settings](https://help.mixpanel.com/hc/en-us/articles/115004596186#enable-or-disable-common-mobile-events). Also, Mixpanel automatically tracks some properties by default. [learn more](https://help.mixpanel.com/hc/en-us/articles/115004613766-Default-Properties-Collected-by-Mixpanel)

```java
String projectToken = YOUR_PROJECT_TOKEN; // e.g.: "1ef7e30d2a58d27f4b90c42e31d6d7ad"
MixpanelAPI mixpanel = MixpanelAPI.getInstance(this, projectToken);
JSONObject props = new JSONObject();
props.put("source", "Pat's affiliate site");
props.put("Opted out of email", true);

mixpanel.track("Sign Up", props);
```
Remember to replace `YOUR_PROJECT_TOKEN` with the token provided to you on mixpanel.com.
In addition to event data, you can also send [user profile data](https://developer.mixpanel.com/docs/android#storing-user-profiles). We recommend this after completing the quickstart guide.

### Tracking
## 4. Check for Success
[Open up Live View in Mixpanel](http://mixpanel.com/report/live) to view incoming events.

After installing the library into your Android app, Mixpanel will <a href="https://mixpanel.com/help/questions/articles/which-common-mobile-events-can-mixpanel-collect-on-my-behalf-automatically" target="_blank">automatically collect common mobile events</a>. You can enable/disable automatic collection through your project settings.
Once data hits our API, it generally takes ~60 seconds for it to be processed, stored, and queryable in your project.

With the `mixpanel` object created in [the last step](#integration) a call to `track` is all you need to send additional events to Mixpanel.
# FAQ
**I want to stop tracking an event/event property in Mixpanel. Is that possible?**

```java
mixpanel.track("Event name no props")
Yes, in Lexicon, you can intercept and drop incoming events or properties. Mixpanel won’t store any new data for the event or property you select to drop. [See this article for more information](https://help.mixpanel.com/hc/en-us/articles/360001307806#dropping-events-and-properties).

JSONObject props = new JSONObject();
props.put("Prop name", "Prop value");
props.put("Prop 2", "Value 2");
mixpanel.track("Event name", props);
**I have a test user I would like to opt out of tracking. How do I do that?**

Mixpanel’s client-side tracking library contains the [optOutTracking()](http://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#optOutTracking--) method, which will set the user’s local opt-out state to “true” and will prevent data from being sent from a user’s device. More detailed instructions can be found in the section, [Opting users out of tracking](android#opting-users-out-of-tracking).

**Why aren't my events showing up?**

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. You can call [flush()](http://mixpanel.github.io/mixpanel-android/com/mixpanel/android/mpmetrics/MixpanelAPI.html#flush--) manually if you want to force a flush at a particular moment for example before your application is completely shutdown.

If your events are still not showing up after 60 seconds, check if you have opted out of tracking. You can also enable Mixpanel debugging and logging, it allows you to see the debug output from the Mixpanel Android library. To enable it, you will want to add the following permission within your AndroidManifest.xml inside the `<application>` tag:

```java
...
<application>
<meta-data
android:name="com.mixpanel.android.MPConfig.EnableDebugLogging"
android:value="true" />
...
</application>
...
```

<a name="i-want-to-know-more"></a>
Expand Down