Push

Push helps you reach out to your users in a timely fashion with important messages. You can use it to inform users about updates to some piece of data, about new services available nearby or that they are winners in a game. Using Custom server code you can set up triggers which send push notifications to a targeted set of people based on changes in the data you specify.

Kinvey brings Android Push Notifications to you through an integration with Google Cloud Messaging (GCM), and iOS Push Notifications through an integration with AWS SNS. While push notifications can only be configured to be used by either iOS or Android devices, our APIs provide support for registering/unregistering devices and associating them with Kinvey users.

Setup

GCM Setup

  1. Navigate to the Google Mobile Services Add Service Wizard and follow the the instructions for creating a project, entering in your app info and adding Google Cloud Messaging to your app. Write down the API Key and Sender ID obtained.

Console Setup

  1. Navigate to the Google Mobile Services Add Service Wizard and follow the the instructions for creating a project, entering in your app info and adding Google Cloud Messaging to your app. Write down the Server API Key and Sender ID obtained.
  2. On the Kinvey's console navigate to Engagement and select Push.
  3. Select Configuration from the top.
  4. In the Android section, enter the API Key and Sender ID (also known as Project Number) obtained in step 1.
  5. Click Save Android

Project Setup

If you don't have the Kinvey Android Client Library added to your project, first take a look at the getting started guide.

Next, obtain the Google Play Services Library by following Google's guide for installing Google Play Services, which will download google-play-services_lib to <myAndroidSdkDirectory>/extras/google/google_play_services/libproject/google-play-services_lib/. If you aren't using gradle, import this as a project into your IDE as an Android Library project and add it as a dependency to your application.

kinvey.properties

To use push features, you must use a property file for initializing the client. Take a look at the getting started guide's section on initializing from a property file first, and then you can add the following GCM specific properties:

# Required settings
gcm.enabled=true
gcm.senderID=mySenderID

To use GCM, gcm.enabled must be set to true. Replace mySenderID with your Sender Id (a.k.a. Project Number)obtained from your Google API Project.

Receiving push messages

You must implement two classes to receive and handle push notifications within your android application. First, create a new class which extends KinveyGCMService. This class provides 5 methods, one for each of the possible GCM actions. By overriding these methods, you can run any code when a message is received (for example, showing a notification or just writing to the logs).

import com.kinvey.android.push.KinveyGCMService;

public class GCMService extends KinveyGCMService {

    @Override
    public void onMessage(String message) {
        displayNotification(message);
    }

    @Override
    public void onError(String error) {
        displayNotification(error);
    }

    @Override
    public void onDelete(String deleted) {
        displayNotification(deleted);
    }

    @Override
    public void onRegistered(String gcmID) {
        displayNotification(gcmID);
    }

    @Override
    public void onUnregistered(String oldID) {
        displayNotification(oldID);
    }


    //This method will return the WakefulBroadcastReceiver class you define in the next step
    public Class getReceiver() {
        return GCMReceiver.class;
    }



    private void displayNotification(String message){
        NotificationCompat.Builder mBuilder = new NotificationCompat.Builder(this)
            .setSmallIcon(R.drawable.ic_launcher)
            .setContentTitle(getApplicationContext().getResources().getString(R.string.app_name))
            .setContentText(message);
        NotificationManager mNotificationManager = (NotificationManager) getSystemService(Context.NOTIFICATION_SERVICE);
        mNotificationManager.notify(1, mBuilder.build());
    }
}

After defining the class which will handle receiving messages, you have to register this class with GCM. Create a new class in the same package as the above, and extend the Android class WakefulBroadcastReceiver.

public class GCMReceiver extends WakefulBroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        ComponentName comp = new ComponentName(context.getPackageName(), com.myPackage.GCMService.class.getName());
        startWakefulService(context, (intent.setComponent(comp)));
        setResultCode(Activity.RESULT_OK);
    }
}

In the above code sample, replace com.myPackage.GCMService with the fully qualified name of the KinveyGCMService you created earlier. Also, visit your KinveyGCMService implementation and have the method getReceiver() return the WakefulBroadcastReceiver class you just created.

Manifest changes

To use GCM for push notifications, add the following permissions to your project's AndroidManifest.xml file within the <manifest> tags:

<uses-sdk android:minSdkVersion="8" android:targetSdkVersion="17"/>
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

Also add the following lines within the <manifest> tags, however replacing com.myPackage with your app's package name.

<permission android:name="com.myPackage.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />
<uses-permission android:name="com.myPackage.permission.C2D_MESSAGE" />

Next, within your <application> tag, register the receiver and service you created earlier. Replace com.myPackage with your application's package, and ensure that the receiver name is set to match the custom WakefulBroadcastReceiver and the service name is set to match the KinveyGCMService.

    <receiver
        android:name="com.myPackage.GcmBroadcastReceiver"
        android:permission="com.google.android.c2dm.permission.SEND" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="com.myPackage" />
        </intent-filter>
    </receiver>
    <service android:name=".GCMService" />

Registering the Device

Now that you have configured your manifest and added the two necessary classes, it is necessary to register a device to receive Push notifications. To register the active user to receive push notifications on the current device, use the following:

myClient.push().initialize(getApplication());

After registration has completed, your application will be notified via the onRegistered(…) method of the KinveyGCMService.

Push registration occurs in the context of an initialized Kinvey client and a logged-in Kinvey user (either explicit or implicit).

Disabling Push Notifications

Similarly, the following code will disable push notifications for the current active user and your app will receive results through the KinveyGCMService.

myClient.push().disablePush();
Got a question?