Sign up for a Parse account to implement this tutorial and more!

Sign Up

Icon_android_push
Android Push Notifications

This tutorial provides you with a step-by-step guide to configuring your Android application for push.

Android
Push Notifications

Download code for this tutorial:

.zip File GitHub

Push notifications let your application notify a user of new messages or events even when the user is not actively using your application. On Android devices, when a device receives a push notification, your application's icon and a message appear in the status bar. When the user taps the notification, they are sent to your application. Notifications can be broadcast to all users, such as for a marketing campaign, or sent to just a subset of users, to give personalized information.

The Parse library provides push notifications by using Google Cloud Messaging (GCM) if possible. On devices that do not support GCM (such as the Amazon Kindle Fire), Parse will use a background service that maintains a persistent connection to the Parse Cloud to deliver pushes. This allows Parse Push to work on all devices running Android 2.2 or higher.

1. Registering for the Push Service

To use push notifications, your application must register the following service and broadcast receivers. Add the following XML to your AndroidManifest.xml file immediately before the closing </application> tag:

<service android:name="com.parse.PushService" />
<receiver android:name="com.parse.ParseBroadcastReceiver">
  <intent-filter>
    <action android:name="android.intent.action.BOOT_COMPLETED" />
    <action android:name="android.intent.action.USER_PRESENT" />
  </intent-filter>
</receiver>
<receiver android:name="com.parse.GcmBroadcastReceiver"
    android:permission="com.google.android.c2dm.permission.SEND">
  <intent-filter>
    <action android:name="com.google.android.c2dm.intent.RECEIVE" />
    <action android:name="com.google.android.c2dm.intent.REGISTRATION" />

    <!--
      IMPORTANT: Change "com.parse.tutorials.pushnotifications" to match your app's package name.
    -->
    <category android:name="com.parse.tutorials.pushnotifications" />
  </intent-filter>
</receiver>

If you modify the package name of the tutorial app, change the android:name attribute of <category> element above to match your application's package name.

2. Setting Permissions

Next, your application must have the permissions needed to receive pushes and show notifications. Make sure that these permissions are present in your AndroidManifest.xml file, typically immediately before the <application> tag:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

<!--
  IMPORTANT: Change "com.parse.tutorials.pushnotifications.permission.C2D_MESSAGE" in the lines below
  to match your app's package name + ".permission.C2D_MESSAGE".
-->
<permission android:protectionLevel="signature"
    android:name="com.parse.tutorials.pushnotifications.permission.C2D_MESSAGE" />
<uses-permission android:name="com.parse.tutorials.pushnotifications.permission.C2D_MESSAGE" />

If you modify the package name of the tutorial app, change the android:name attribute in the last two lines of the snippet above to match your application's package name.

3. Add your Parse API keys

Create or open your Application class, and add the following line to your onCreate method:

Parse.initialize(this, "YOUR_APP_ID", "YOUR_CLIENT_KEY");

Make sure to replace "YOUR_APP_ID" and "YOUR_CLIENT_KEY" with your Parse app's id and client key. You can find these in your app's Settings page.

4. Enable Push Notifications

Finally, your application needs to inform the Parse Push Service that it is ready for notifications. The simplest way to get started is to specify a Activity to be used for all push notifications by default. Add these two lines of code the onCreate method of your Application class:

PushService.setDefaultPushCallback(this, YourDefaultActivity.class);

To track statistics around application opens, add the following to the onCreate method of your main Activity:

ParseAnalytics.trackAppOpened(getIntent());

You will also need to add import statements. Eclipse should prompt you automatically to do this:

import com.parse.Parse;
import com.parse.ParseAnalytics;
import com.parse.PushService;

5. Send a Test Push Notification

At this point, you're ready to send push notifications. Unlike iOS, Android push notifications do work from the emulator, so you can use the emulator to test out push.

Push Notifications tab

In your Parse dashboard, select the app you want to use to send pushes. Next, navigate to the "Push Notifications" section. From here, you can see all the pushes you've recently sent. To compose a new one, we'll select the "Send a push" button.

From here, you can configure all you'll need to send your push notification. You can use the provided text box to send push notifications to all of your app's users.

6. Send a Targeted Push Notification

Launch your new Android app, and enter your demographic information. Once you save your profile, load your Parse dashboard and navigate to the "Push Notifications" section. Choose "Segment" from the dropdown at the top to show various options for targeting your push notifications. Since we're tracking the user's gender and age, we can now choose to send a push to a specific subset of our userbase.

Targeted push notifications

Advanced targeting on custom fields is available to Pro and Enterprise customers through the Push Console as shown in the screenshot above. You may still send such targeted push notifications by making use of our JavaScript SDK from Cloud Code. For example, the following JavaScript code will target the same users:

var query = new Parse.Query(Parse.Installation);
query.equalTo('gender', 'male');
query.greaterThanOrEqualTo('age', 18);
 
Parse.Push.send({
  where: query, // Set our Installation query
  data: {
    alert: "A test notification from Parse!"
  }
});

You can place this in a Cloud Function that can be called from your Android app using ParseCloud. An alternative would be to use the REST API to programmatically send the push notification from an external server:

curl -X POST \
  -H "X-Parse-Application-Id: your_app_id" \
  -H "X-Parse-REST-API-Key: your_rest_api_key" \
  -H "Content-Type: application/json" \
  -d '{
        "where": {
          "gender": "male",
          "age": { "$gte" :18 }
        },
        "data": {
          "alert": "A test notification from Parse!"
        }
      }' \
  https://api.parse.com/1/push

For more information on Push Notifications in Android, take a look at our Push Guide.