From e5beaf4906d3b88a659e29e8b6edec65bb5d6949 Mon Sep 17 00:00:00 2001
From: Peter Chien <peter.chien@mixpanel.com>
Date: Tue, 2 May 2017 17:10:16 -0700
Subject: [PATCH] readme updates

---
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 72 insertions(+), 19 deletions(-)

diff --git a/README.md b/README.md
index 2cfdda1c2..9235994b9 100644
--- a/README.md
+++ b/README.md
@@ -2,27 +2,78 @@
   <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 [![Build Status](https://travis-ci.org/mixpanel/mixpanel-android.svg)](https://travis-ci.org/mixpanel/mixpanel-android)
+
 ##### _April 24, 2017_ - [v5.0.2](https://github.com/mixpanel/mixpanel-android/releases/tag/v5.0.2)
 
-Quick Installation
-------------------
-Check out our **[official documentation](https://mixpanel.com/help/reference/android)** to learn how to install the library on Android Studio. It takes less than 2 minutes!
+# Table of Contents
+
+<!-- MarkdownTOC -->
+
+- [Quick Start Guide](#quick-start-guide)
+    - [Installation](#installation)
+    - [Integration](#integration)
+- [I want to know more!](#i-want-to-know-more)
+- [Want to Contribute?](#want-to-contribute)
+- [Changelog](#changelog)
+- [License](#license)
+
+<!-- /MarkdownTOC -->
+
+<a name="quick-start-guide"></a>
+# Quick Start Guide
+
+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
 
-**TLDR;**
+### Dependencies in *app/build.gradle*
+
+Add Mixpanel and Google Play Services to the `dependencies` section in *app/build.gradle*
+
+```gradle
+compile "com.mixpanel.android:mixpanel-android:5.+"
+compile "com.google.android.gms:play-services:7.5.0+"
+```
+
+### Permissions in *app/src/main/AndroidManifest.xml*
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<uses-permission android:name="android.permission.BLUETOOTH" />
+```
 
-`
-compile "com.mixpanel.android:mixpanel-android:5.+" 
-`
+<a name="integration"></a>
+## Integration
+
+### Initialization
+
+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)).
 
 ```java
 String projectToken = YOUR_PROJECT_TOKEN; // e.g.: "1ef7e30d2a58d27f4b90c42e31d6d7ad" 
 MixpanelAPI mixpanel = MixpanelAPI.getInstance(this, projectToken);
-mixpanel.track("My first event!");
 ```
-I want to know more!
---------------------
+Remember to replace `YOUR_PROJECT_TOKEN` with the token provided to you on mixpanel.com.
+
+### Tracking
+
+With the `mixpanel` object created in [the last step](#integration) a call to `track` is all you need to start sending events to Mixpanel.
+
+```java
+mixpanel.track("Event name no props")
+
+JSONObject props = new JSONObject();
+props.put("Prop name", "Prop value");
+props.put("Prop 2", "Value 2");
+mixpanel.track("Event name", props);
+```
+
+<a name="i-want-to-know-more"></a>
+# I want to know more!
+
 No worries, here are some links that you will find useful:
 * **[Sample app](https://github.com/mixpanel/sample-android-mixpanel-integration)**
 * **[Android integration video tutorial](https://www.youtube.com/watch?v=KcpOa93eSVs)**
@@ -30,17 +81,19 @@ No worries, here are some links that you will find useful:
 
 Have any questions? Reach out to [support@mixpanel.com](mailto:support@mixpanel.com) to speak to someone smart, quickly.
 
-Want to Contribute?
--------------------
+<a name="want-to-contribute"></a>
+# Want to Contribute?
+
 The Mixpanel library for Android is an open source project, and we'd love to see your contributions!
-We'd also love for you to come and work with us! Check out our **[opening positions](http://boards.greenhouse.io/mixpanel/)** for details.
+We'd also love for you to come and work with us! Check out our **[opening positions](https://mixpanel.com/jobs/#openings)** for details.
+
+<a name="changelog"></a>
+# Changelog
 
-Changelog
----------
 See [wiki page](https://github.com/mixpanel/mixpanel-android/wiki/Changelog).
 
-License
--------
+<a name="license"></a>
+# License
 
 ```
 See LICENSE File for details. The Base64Coder,