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 100+ 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!
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 {
implementation 'com.mparticle:android-core:5.2.1'
}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 {
implementation (
'com.mparticle:android-example-kit:5.2.1',
'com.mparticle:android-another-kit:5.2.1'
)
}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:
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:
implementation 'com.google.android.gms:play-services-ads:11.6.2'mParticle supports several marketing automation and push messaging integrations. These require that mParticle register for an instance id using the Firebase Cloud Messaging framework:
implementation 'com.google.firebase:firebase-messaging:11.6.2'In order for attribution, deep linking, and many other integrations to work properly, the mParticle SDK collects the Google Play Install referrer string, which tracks the original link that brought the user to Google Play.
There are two different ways to collect this value - you only need to implement one.
Google now supports a library that surface the referrer string:
Simply add this dependency to your app and the mParticle SDK will detect it:
implementation 'com.android.installreferrer:installreferrer:1.0'Alternatively, you can add the mParticle ReferrerReceiver to your manifest file within the <application> tag. The mParticle SDK
will collect any campaign referral information and automatically forward it to kits (such as AppsFlyer, Kochava, and Adjust) and server-side integrations.
If you have no other BroadcastReceiver that listens for the INSTALL_REFERRER intent, you can just add the mParticle receiver:
<receiver android:name="com.mparticle.ReferrerReceiver" android:exported="true">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER"/>
</intent-filter>
</receiver>Google Play will only deliver the INSTALL_REFERRER Intent to a single BroadcastReceiver - you cannot have multiple in your manifest. If you already have your own receiver, or otherwise have multiple receivers that require
referral data, you must expose your own BroadcastReceiver in your manifest and then forward the received Intent to mParticle:
public class ExampleReceiver extends BroadcastReceiver {
@Override
public void onReceive(Context context, Intent intent) {
//process the Intent/send to other receivers as desired, and
//send the Context and Intent into mParticle's BroadcastReceiver
new com.mparticle.ReferrerReceiver().onReceive(context, intent);
}
}-
Grab your mParticle key and secret from your workspace's dashboard and construct an
MParticleOptionsobject. -
Call
startfrom theonCreatemethod of your app'sApplicationclass. It's crucial that the SDK be started here for proper session management. If you don't already have anApplicationclass, create it and then specify its fully-qualified name in the<application>tag of your app'sAndroidManifest.xml.
package com.example.myapp;
import android.app.Application;
import com.mparticle.MParticle;
public class MyApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
MParticleOptions options = MParticleOptions.builder(this)
.credentials("REPLACE ME WITH KEY","REPLACE ME WITH SECRET")
.setLogLevel(MParticle.LogLevel.VERBOSE)
.identify(identifyRequest)
.identifyTask(
new BaseIdentityTask()
.addFailureListener(this)
.addSuccessListener(this)
)
.build();
MParticle.start(options);
}
}Warning: It's generally not a good idea to log events in your
Application.onCreate(). Android may instantiate yourApplicationclass for a lot of reasons, in the background, while the user isn't even using their device.
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.
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.