Configuring Push Notifications

The Geotrigger Service sends push notifications to Android devices using the Google Cloud Messaging for Android (GCM) service.

You must have a Google account set up on your device or emulator in order to register with the GCM server and receive messages.

For backround details on using GCM, please read the GCM Overview on the Android Developers website.

Create a Google API Project

The first step is to create a new Google API Project by navigating to the Google Developers Console site. If you already have a Google API Project, you may continue to the next step. Otherwise, you’ll need to create an API project:

  • Click the Create Project button.
  • Fill in the Project name field, then click Create. You may optionally specify a custom Project ID, but it is not used by the Geotrigger Service in any way.

You’ll be taken to the project page when it has finished being created.

Take note of your Project Number, shown at the top of the page. For example, Project Number: 588978698153

Your Project Number will be used later as your GCM sender ID.

Enabling the GCM Service

  • Select APIs & auth in the left-hand sidebar to view the list of available APIs.
  • Find Google Cloud Messaging for Android and set the toggle to ON.

Obtain a Google API Key

Now that you’ve created a project and enabled Google Cloud Messaging for Android, you’ll need to generate a GCM API Key:

  • In the left-hand sidebar, select APIs & auth > Credentials.
  • Click the Create New Key button in the Public API access section.
  • Select Server key from the Create a new key pop-up.
  • Leave the allowed IPs text area empty, and click Create. Enabling the IP whitelist will prevent the Geotrigger Service from sending notifications to Android devices via GCM.

An entry in the Key for server applications section will appear once your key has been created.

Take note of the API key and verify that the IPs section displays Any IP allowed.

You will add the API key to your ArcGIS Online Application in the next step. This will enable the Geotrigger Service to communicate with the Google Cloud Messaging Service on your behalf.

Update your ArcGIS Application with the Google API Key

  • Navigate to the Applications section of the ArcGIS Developer Site.
  • Click on the small key icon to get to the API Access details for your app.
  • Click the Push Certificates label in the left side bar.
  • Paste your GCM API Key into the API Key field under the Google Cloud Messaging API Key heading.
  • Click the Update Push Certificates button to save your changes.

Update Push Certificates

Configure Your Android Manifest

Having configured GCM and linked your Google API Key with your ArcGIS application, you’re ready to start configuring your Android manifest.

Make sure that you’ve declared the permissions and receiver shown below in your AndroidManifest.xml.

Permissions

Add the following declarations above the application block:


<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.VIBRATE" />




<permission
    android:name="{YOUR_PACKAGE_NAME}.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />


<uses-permission android:name="{YOUR_PACKAGE_NAME}.permission.C2D_MESSAGE" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />

You will need to replace {PACKAGE_NAME} with the value of the package attribute on the top-level manifest declaration. If your AndroidManifest.xml begins like this:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.esri.android.geotrigger.example"
          android:versionCode="1"
          android:versionName="1.0">

Then you will need to replace {PACKAGE_NAME} with com.esri.android.geotrigger.example.

Receiver

Add the following receiver declaration within your application block.

<receiver
    android:name="com.esri.android.geotrigger.MessageReceiver"
    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" />

        
        <category android:name="{YOUR_PACKAGE_NAME}" />
    </intent-filter>
    <intent-filter>
        <action android:name="android.intent.action.PACKAGE_REPLACED" />
        <data android:path="{YOUR_PACKAGE_NAME}"
        android:scheme="package" />
    </intent-filter>
</receiver>

Add your Sender ID to the GeotriggerService

The final step is to configure the Geotrigger SDK for Android to handle push notifications in the way you prefer.

Be sure to provide your application’s Client ID and the GCM Sender ID (Google project Number) when initializing the GeotriggerService.

GeotriggerService.init(context, CLIENT_ID, GCM_SENDER_ID,
        GeotriggerService.TRACKING_PROFILE_ADAPTIVE);

Send a Test Notification to a Device

Before continuing, you should send a test push notification to your device. The best way to do this is to make a request to the device/notify API route from the GeotriggerApiClient included in the Geotrigger SDK for Android. You can use the following code to send a message back to the device that made the API call:

JSONObject params = new JSONObject();
try {
    params.put("text", "Push notifications are working!");
    params.put("url", "http://developers.arcgis.com");
} catch (JSONException e) {
    Log.e(TAG, "Error creating device/notify params", e);
}

GeotriggerApiClient.runRequest(context, "device/notify", params, new GeotriggerApiListener() {
    @Override
    public void onSuccess(JSONObject json) {
        Log.i(TAG, "device/notify success: " + json);
    }

    @Override
    public void onFailure(Throwable error) {
        Log.e(TAG, "device/notify failure", error);
    }
});

If you find that you don’t receive the push notification after a few minutes, you may want to make sure your firewall is set to allow push messages from Google servers.

You may find the Push Notification Test app (third-party) useful for confirming that your device and network are capable of receiving push notifications.

Configuring Push Notifications for your Application

Default Notification Handling

By default, when a trigger is fired and a push message is delivered to the device, the Geotrigger SDK for Android will put a notification in the notification bar that displays the value of the notification.text field you included when the trigger was created. The default notification sound will be played along with vibration, if it is enabled for notifications in the system settings of the device.

When creating triggers, you can also include a value for icon in the notification object that you include when posting to /trigger/create. This value specifies the name of the drawable resource included in your application that you want to use as the icon for push notifications.

Alternatively, you can set a default push icon at runtime:

GeotriggerService.setPushIcon(context, iconName);

Any value you set in this way is overridden by the value of icon in the notification object. If you do not provide an icon via either of these methods, the Geotrigger SDK for Android will default to your application icon (ic_launcher).

You may also specify the name of a sound resource to be played when the push notification is received as the value of notification.sound. Sound files must be placed in the res/raw folder and be in a supported format.

You can also set a default sound file at runtime:

GeotriggerService.setPushSound(context, soundName);

This defualt value will be overridden by the notification.sound value of a trigger notification or device notification.

Disabling the Display of Notification

You can optionally disable the automatic display of notifications when a push message is received. If you do this, the Geotrigger SDK for Android will still receive push messages,

but will not automatically create a status bar notification.

To do this, run the static method above the call to GeotriggerService.init():

GeotriggerService.disablePushNotificationHandling(context);

Handling Push Messages Manually

The perferred method of handling notifications manually is to subclass the GeotriggerBroadcastReceiver and override the onPushMessage method. Then, declare the custom receiver in your AndroidManifest. This will allow your custom receiver to handle push notifications regardless of whether or not your Activity is in the foreground.

The following is a simple example of a custom receiver which shows notifications as Android toasts:

public class MyGeotriggerReceiver extends GeotriggerBroadcastReceiver {
    @Override
    protected void onPushMessage(Context context, Bundle notification) {
        super.onPushMessage(context, data);

        // The notification Bundle has these keys: 'text', 'url', 'sound', 'icon', 'data'
        String msg = String.format("Push Message Received: %s", notification.get("text"));
        Toast.makeText(context, msg, Toast.LENGTH_SHORT).show();
    }
}

In order to register your receiver, you must also add the following to your AndroidManifest:

<receiver
    android:name="com.esri.android.geotrigger.example.MyGeotriggerReceiver"
    android:enabled="true"
    android:exported="false">
    <intent-filter>
        <action android:name="com.esri.android.geotrigger.action.PUSH_MESSAGE_RECEIVED" />
        <action android:name="com.esri.android.geotrigger.action.LOCATION_UPDATE_RECEIVED" />
    </intent-filter>
</receiver>

You must also disable push notification handling as shown above.

Please see the Handling Events guide for more information on how to register to listen for and handle GeotriggerService events.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s