mParticle SDK for Android apps
Java Groovy
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
android-core
android-kit-base Expose session-start and session-end to kit API Jan 18, 2017
gradle/wrapper
kit-plugin
kits
scripts
.gitignore
.gitmodules
.travis.yml
LICENSE
README.md
build.gradle
gradlew
gradlew.bat
settings-kits.gradle
settings.gradle

README.md

Android SDK

Maven Central Status

Hello! This is the public repo of the mParticle Android SDK. mParticle's mission is straightforward: make it really easy to use all of the great services in the app ecosystem. Our SDKs and platform are designed to be your abstraction layer and data hub, and we do the work of integrating with each individual app service so you don't have to.

The platform has grown to support 80+ partners in the ecosystem, including developer tools, analytics, attribution, marketing automation, and advertising services. We also have a powerful audience engine that sits atop our platform to let you action on all of your data - learn more here!

Core SDK

mParticle's Android integration is powered by a Core library, which supports mParticle's server-side integrations and audience platform.

You can grab the Core SDK via Maven Central. Please reference the badge above and follow the releases page to stay up to date with the latest version.

dependencies {
    compile 'com.mparticle:android-core:4.10.0'
}

Kits

Several integrations require additional client-side add-on libraries called "kits." Some kits embed other SDKs, others just contain a bit of additional functionality. Kits are designed to feel just like server-side integrations; you enable, disable, filter, sample, and otherwise tweak kits completely from the mParticle platform UI. The Core SDK will detect kits at runtime, but you need to add them as dependencies to your build:

dependencies {
    compile (
        'com.mparticle:android-example-kit:4.10.0',
        'com.mparticle:android-another-kit:4.10.0',
    )
}

Kits are deployed as individual artifacts in Maven Central, and each has a dedicated repository if you'd like to view the source code. Review the table below to see if you need to include any kits:

Kit Maven Artifact
Adjust android-adjust-kit
Appboy android-appboy-kit
AppsFlyer android-appsflyer-kit
Apptentive android-apptentive-kit
Apptimize android-apptimize-kit
Apteligent android-apteligent-kit
Branch Metrics android-branch-kit
Button android-button-kit
comScore android-comscore-kit
Flurry android-flurry-kit
ForeSee android-foresee-kit
Kahuna android-kahuna-kit
Kochava android-kochava-kit
Leanplum android-leanplum-kit
Localytics android-localytics-kit
Radar android-radar-kit
Reveal Mobile android-revealmobile-kit
Tune android-tune-kit
Urban Airship android-urbanairship-kit
Wootric android-wootric-kit

Optional Dependencies

Google Play Services Ads

The Google Play Services Ads framework is necessary to collect the Android Advertisting ID. AAID collection is required by all attribution and audience integrations, and many other integrations. Include the -ads artifact, a subset of Google Play Services:

    compile 'com.google.android.gms:play-services-ads:9.0.0'
Google Cloud Messaging

mParticle supports several marketing automation and push messaging integrations. These require that mParticle register for an instance id (formely known as a push registration token) using the Google Play Services Cloud Messaging framework. Include the -gcm artifact, a subset of Google Play Services:

    compile 'com.google.android.gms:play-services-gcm:9.0.0'

Install Referrer

In order for attribution, deep linking, and many other integrations to work properly, add the mParticle ReferrerReceiver to your manifest file within the <application> tag:

<receiver android:name="com.mparticle.ReferrerReceiver" android:exported="true">
    <intent-filter>
        <action android:name="com.android.vending.INSTALL_REFERRER"/>
    </intent-filter>
</receiver>

Show me the code

Grab your mParticle key and secret from your app's dashboard and add them as string resources in your app:

<?xml version="1.0" encoding="utf-8" ?>
<!-- ex. src/main/res/values/mparticle.xml -->
<resources>
    <string name="mp_key">APP KEY</string>
    <string name="mp_secret">APP SECRET</string>
</resources>

You can also pass your key/secret programmatically in the method below.

Initialize the SDK

Call start from the onCreate method of your app's Application class. It's crucial that the SDK be started here for proper session management. If you don't already have an Application class, create it and then specify its fully-qualified name in the <application> tag of your app's AndroidManifest.xml.

package com.example.myapp;

import android.app.Application;
import com.mparticle.MParticle;

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        MParticle.start(this);
    }
}

Warning: It's generally not a good idea to log events in your Application.onCreate(). Android may instantiate your Application class for a lot of reasons, in the background, while the user isn't even using their device.

Proguard

Proguard is a minification/optimization/obfuscation tool that's extremely useful, and it can also cause some sticky bugs. The mParticle SDK is already minified so there's no need to...double-minify it. If you're using Gradle there's nothing to do - we include a consumer-proguard rules file inside our AAR which Gradle will automatically include in your build. If you're not using Gradle, please add those same rules manually - see here for the latest.

Read More

Just by initializing the SDK you'll be set up to track user installs, engagement, and much more. Check out our doc site to learn how to add specific event tracking to your app.

License

Apache License 2.0