Clone this wiki locally
mParticle Android Push
The mParticle platform supports multiple push and marketing automation services. In the context of Android, push is facilitated over the Google Cloud Messaging (GCM) service. The mParticle Android SDK is able to handle registration for GCM, as well as parsing and optionally displaying GCM messages. Use this overview to help your understanding of push and to troubleshoot when necessary.
If you're new to push in the context of Android start here and at the linked resources for an overview.
Android vs. iOS
The Android platform and the Google Cloud Messaging Service have a significantly different design than the iOS platform and the Apple Push Notification Service (APNS). Among all of the differences, there are two key differences to always keep in mind:
On Android, even in the latest version (6.0 Marshmallow), you do not need to ask users for push permissions. You still need to define permissions in your application's manifest file as described later in this document, but these permissions are implicitly granted when the user installs your app. This is very different than iOS where the operating system forcibly shows the users a dialog that they can choose to deny. If you'd like, per good practice, you can decide to design your own dialog, preferences pane, or other settings mechanism that allows users to disable push - but there is technically no way that the user can prevent you from acquiring a push token after they've installed your app.
2. Showing Notifications
Coming from iOS it's common for developers and app owners to equate push messages with the displaying of a notification on the device. On Android, the two concepts are completely decoupled: a GCM message is simply a free-form blob of data that you can send to your app - it's completely up to you to determine what you'd like to do or trigger based on that blob of data. Some examples are:
- Waking your application up to tell it to request some data
- Sending data directly to an app so that it doesn't need to make a seperate API request
- Or, commonly, sending a human-readable message, so that you can show the user a notification, or otherwise display some UI based on the content of the message
The Android operating system does not in any way facilitate displaying a notification on the device. On iOS, APNS messages must follow a strict format, and the operating system automatically turns APNS messages into notifications on the device.
GCM Architecture Basics
Interaction with GCM is all done by way of a Google Account and a Google Console App that you must create. Regardless of which push integration/service you use - you will need to create this app, enable it for GCM, and acquire two items:
- A server key associated with your Google Console App. This is how your push provider will authenticate with GCM when it attempts to send push messages to your users (ex.
- The project ID, or sender ID, of your Google Console App (ex.
See the Google Developers Console here: https://console.developers.google.com
- User installs your app. If your app has been correctly instrumented to push, permissions are implicitly granted to your app to register for and receive GCM messages.
- Your app tells the mParticle SDK that it should register for GCM, either via programmatic API invocation, or via XML configuration.
- The mParticle SDK uses your configured Google Console App project ID to request a push registration token.
- The Android Operating System and Google Play Services requests a registration token on your app's behalf, and returns the token to the mParticle SDK.
- The mParticle SDK sends the push token to your configured push provider(s). Your push providers store this push token for later use.
Tokens may change based on a number of scenarios, so the mParticle SDK will continually requests and sync push tokens on subsequent application launches.
Sending a GCM push
- You navigate to your configured push provider(s) (ex. Appboy), and create a campaign or otherwise configure it to send a push message to the GCM service.
- The push provider uses the server key of your Google Console App to authenticate with GCM, and together with the GCM tokens/associated users that mParticle has provided, the provider sends a blob of data (note that this can be in any format, and will differ across every provider) to GCM for delivery to each device.
- The Android Operating System receives the blob of data, and sends a
com.google.android.c2dm.intent.RECEIVEbroadcast to your application.
- The mParticle sees this broadcast, and starts a service to parse it further.
- The mParticle SDK will decifer the originating integration of the GCM message based on the format of the GCM message blob. At this point mParticle will either attempt to show a simple notification message itself, or it will forward the GCM message to any embedded Kits, such as Appboy, and leave it up to the Kit to parse the message and optionally show a notification.
- Follow this wizard to create/edit a Google Console app and enable it for GCM, and save your Server API Key and Sender ID for later use.
- Configure your push provider(s), such as Appboy, with the Server API Key that you saved from #1.
- Enable the push provider(s) in the mParticle integrations dashboard
- Add the Google Play Services GCM SDK to your application (
com.google.android.gms:play-services-gcm) as described here.
- Add the mParticle Core SDK to your application if you haven't already.
- If using Appboy or Kahuna, add the Appboy or Kahuna Kit.
- Verify that you have updated your
AndroidManifest.xmlas described below.
Using the Sender ID acquired above, enable push via the mParticle SDK by either:
Calling the following API on app start-up, or when you deem appropriate if you would like to give users a choice:
MParticle.getInstance().Messaging().enablePushNotifications("<insert sender id here>");
<?xml version="1.0" encoding="utf-8" ?> <resources> ... <bool name="mp_enablePush">true</bool> <string name="mp_pushSenderId">INSERT SENDER ID HERE</string> ... </resources>
In order to register for and receive push messages, you must add the following to your AndroidManifest.xml file:
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.GET_ACCOUNTS" /> <uses-permission android:name="android.permission.WAKE_LOCK" /> <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" /> <!-- Adjust the following for your application name --> <permission android:name="YOUR-APPLICATION-PACKAGE-NAME.permission.C2D_MESSAGE" android:protectionLevel="signature"/> <uses-permission android:name="YOUR-APPLICATION-PACKAGE-NAME.permission.C2D_MESSAGE" />
Add the following broadcast receiver to your manifest.
MPReceiver is used to listen for GCM messages as they are received, it will then pass the given
<receiver android:name="com.mparticle.MPReceiver" android:permission="com.google.android.c2dm.permission.SEND"> <intent-filter> <action android:name="com.google.android.c2dm.intent.RECEIVE" /> <!-- Use your package name as the category --> <category android:name="YOUR-APPLICATION-PACKAGE-NAME" /> </intent-filter> </receiver>
Finally, add the the following service to your manifest.
MPService is used to actually parse GCM messages as they are received.
<service android:name="com.mparticle.MPService" />
Special Appboy Considerations
As stated above, GCM messages are composed of a free-form blob, and do not imply that a notification will be shown, or what will happen if/when a notification is tapped. When using the Appboy Kit, you must add Appboy's additional BroadcastReceiver, and implement and add an additional
BroadcastReceiver to your manifest to trigger the proper behavior when a push is received and tapped. This receiver specifically listens for particular Appboy Intent actions that the Appboy Kit will fire after the mParticle SDK has forwarded a push message to it:
<receiver android:name="com.appboy.AppboyGcmReceiver"> <intent-filter> <category android:name="YOUR-APPLICATION-PACKAGE-NAME" /> </intent-filter> </receiver> <receiver android:name="YOURBROADCASTRECEIVERNAME" android:exported="false" > <intent-filter> <!-- Replace YOUR-APPLICATION-PACKAGE-NAME with the package name of your app --> <action android:name="YOUR-APPLICATION-PACKAGE-NAME.intent.APPBOY_PUSH_RECEIVED" /> <action android:name="YOUR-APPLICATION-PACKAGE-NAME.intent.APPBOY_NOTIFICATION_OPENED" /> </intent-filter> </receiver>
You should confirm that your receiver is properly registered by sending a GCM message, and setting a breakpoint or logging a message within the
onReceive method for your receiver.