Push Notifications

We’ve just released Push Notifications API and we’d really value your feedback, so please let us know if you encounter any problems or if there’s anything we could do to make the experience better.

Push notifications allow you to send a message to a user even when your app is closed or inactive. This provides a powerful way of increasing engagement with your users by allowing you to initiate the communication.

In this tutorial, we’ll add push notifications to a native Android application, allowing us to notify the user even if the application is closed and their phone is locked.

(note - we also support iOS, see our documentation for more details).

How push notifications work

With Android devices, all push notifications are sent through the same transport service – Google Cloud Messenger (GCM). This allows many applications to receive notifications without requiring an open connection for each one.

Before a device can receive a message, it registers with GCM and gets a token. This token can then be used (along with a second key) to send notifications to your device.

The Pusher library takes care of device registration and abstracts away individual devices by introducing interests. This allows you to message a particular user or several thousand users in exactly the same way.

What we’ll cover

We’ll look at taking an existing Android application and learn how to:

Configure Push Notifications
Set up Pusher & our Android library
Subscribe to an interest
Send a push notification

Getting your application ready for push notifications

The first step is to get your application ready to receive push notifications from Google’s Cloud Messaging system.

To do this - visit the developer wizard which will guide you through the process.

You need to get two things:

Your server key - copy this down somewhere as you’ll need to refer to it.
google-services.json - download this to add to your application later

Setting up your Pusher app

If you haven’t already - sign up for a free Pusher account.

Log into the dashboard and create a new app. Once you’re in the app, you’ll see a tab titled “Push Notifications”. Select that, then navigate to the GCM section.

This is where you can add your server key. Once you have entered your server key switch back to the “App Keys” tab and copy down the Pusher keys for your app (you’ll need them later).

Install Pusher Android library

Add GCM config to your application

We want to add the google-services.json details to your application so you can use the right credentials when connecting to GCM.

To do this, add the json file to your project, and then use the Google Services Gradle plugin to build the settings into your project.

// build.gradle
dependencies {
    classpath 'com.google.gms:google-services:3.0.0'
    // ...
}

// app/build.gradle
apply plugin: 'com.google.gms.google-services'

Install our Android library

You can install our pusher-websocket-android library using Gradle (along with the play-services for GCM support). Update your project Gradle file with:

repositories {
    maven { url 'http://clojars.org/repo' }
}

dependencies {
    compile 'com.google.android.gms:play-services-gcm:9.0.0'
    compile 'com.pusher:pusher-websocket-android:0.3.1'
}

You then need to update your AndroidManifest.xml with the following entries:

<manifest>
  <!-- ... -->

  <!-- GCM permissions -->
  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
  <uses-permission android:name="android.permission.WAKE_LOCK" />

  <application>
    <!-- ... -->

    <!-- <application> -->
    <!-- GCM Receiver  -->
    <receiver
        android:name="com.google.android.gms.gcm.GcmReceiver"
        android:exported="true"
        android:permission="com.google.android.c2dm.permission.SEND" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="gcm.play.android.samples.com.gcmquickstart" />
        </intent-filter>
    </receiver>

    <!-- Pusher's GCM listeners and services -->
    <receiver
        android:name="com.google.android.gms.gcm.GcmReceiver"
        android:exported="true"
        android:permission="com.google.android.c2dm.permission.SEND" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="gcm.play.android.samples.com.gcmquickstart" />
        </intent-filter>
    </receiver>

    <service
        android:name="com.pusher.android.notifications.gcm.PusherGCMListenerService"
        android:exported="false" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        </intent-filter>
    </service>

    <service
        android:name="com.pusher.android.notifications.gcm.GCMInstanceIDListenerService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID"/>
        </intent-filter>
    </service>

    <service
        android:name="com.pusher.android.notifications.gcm.GCMRegistrationIntentService"
        android:exported="false">
    </service>

    <!-- ... -->
  </application>

  <!-- ... -->
</manifest>

Subscribing to a topic

Now that we’ve got all of our necessary dependencies installed it’s time to start implementing the functionality in our application. The first thing we need to do is check that the play services are available on this device - to do that, we can add the following method in our main application class:

private boolean playServicesAvailable() {
    GoogleApiAvailability apiAvailability = GoogleApiAvailability.getInstance();
    int resultCode = apiAvailability.isGooglePlayServicesAvailable(this);
    if (resultCode != ConnectionResult.SUCCESS) {
        if (apiAvailability.isUserResolvableError(resultCode)) {
            apiAvailability.getErrorDialog(this, resultCode, PLAY_SERVICES_RESOLUTION_REQUEST)
            .show();
        } else {
            finish();
        }
        return false;
    }
    return true;
}

This allows us to check if the service is available and request access from the user if necessary.

We can use this method to check ensure that the user can receive push notifications, and then we can start using the Pusher Android library. We can create a new PusherAndroid instance, then register the user to receive push notifications through Pusher.

if (playServicesAvailable()) {
  PusherAndroid pusher = new PusherAndroid("YOUR_APP_KEY");
  PushNotificationRegistration nativePusher = pusher.nativePusher();

  // pulled from your google-services.json
  String defaultSenderId = getString(R.string.gcm_defaultSenderId);
  nativePusher.registerGCM(this, defaultSenderId);

  // Ready to subscribe to topics!
}

Now all that’s left to do is to subscribe to interests that the user is interested in. We can do this using the subscribe method:

nativePusher.subscribe("kittens");

And we’re done! Now whenever a message is triggered on “kittens” it’ll be sent to this device!

Sending a push notification

To send a push notification through Pusher you set up a client in exactly the same way as you would for any other message - in fact you can use this client to send websocket data just as before.

There are a few rules around the payload data for a push notification. It must contain a gcm object (or apns for iOS), at a minimum - this object should define a ‘title’ and an ‘icon’ (for more options, check out our Android documentation)

Once you have your payload, you can distribute it by calling notify with the topic you’d like to send it to. For example, the Ruby script below will send a push notification to all users listening on the “kittens” interest:

require 'pusher'

pusher = Pusher::Client.new(
  app_id:    'APP_ID',
  key:       'KEY',
  secret:    'SECRET',
  cluster:   'CLUSTER',
  encrypted: true
)

data = {
  gcm: {
    notification: {
      title: "Hello World!",
      icon: "icon"
    }
  }
}

puts pusher.notify(["kittens"], data)

Lock your phone and run this script - you should see a push notification on your lock screen!

How To Add Push Notifications To Your Native Android Apps