Android SDK - Google Cloud Messaging Utility Module

The Google Cloud Messaging utility enables the Android app developer to use the Google Cloud Messaging (GCM) service to display notification messages to the user about the mobile wallet app, even when the app is not currently active (that is, in the background or not logged-in). For example, Messages that might be pushed to a user include notifications about an available softmare update; new available offers, new store locations in a subscribed geo-location, approaching payment account expiration, and other similar events.

Note: When implementing cloud messaging, ensure the app listens for events related to changes to the user’s push notification settings. If a user disables notifications for the app, invoke Disable Messaging from Paydiant. If the user re-enables notifications, invoke Register for Paydiant Messaging.

Also, when a user re-links a previously unlinked device or links a new device to an existing account, the app must prompt the user again to enable push notifications and invoke the corresponding method based on the response.

To implement GCM notifications, developers must ensure that the device is registered with GCM connection servers to receive messaging, and also registered to accept messages specifically from the Paydiant service.

The services exposed in the device info module are located in the following package classes:

Item Description
UI Service com.paydiant.android.ui.service.gcm.GCMUtilityService
Core Service com.paydiant.android.core.facade.PaydiantGCMUtilityFacade

Add GCM Services to Android Manifest File

To invoke the GCM services to register and unregister a device for GCM notifications, add the relevant permission classes to the Android Manifest File for your SDK instance. The following sample shows the required insertion to the AndroidManifest.xml file.

< ?xml version="1.0" encoding="utf-8"? >
< manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >
... 
< uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" / >
< uses-permission android:name=".permission.C2D_MESSAGE" / >
< uses-permission android:name="android.permission.GET_ACCOUNTS" / >
< uses-permission android:name="android.permission.WAKE_LOCK" / >
< permission android:name="< your package name >.permission.C2D_MESSAGE"
        android:protectionLevel="signature" / >
< uses-permission android:name=".permission.C2D_MESSAGE" / >
< /manifest >

Set UI Package GCM Service Listeners

To invoke the callback methods returned by the Paydiant service in response to the methods invoked by the GCM utility module of the SDK, set an implementation of the listener interface in the UI Service class.

Item Description
UI Service com.paydiant.android.ui.service.gcm.IGCMUtilityServiceListener
or an overridden instance of:

com.paydiant.android.ui.service.gcm.GCMUtilityServiceListenerAdapter
Set Listener void setGCMUtilityServiceListener(IGCMUtilityServiceListener listener);
Remove Listener void removeListener();
Call this method to remove the device info listener and set it to null.

Check Current Device Registration

This method checks the registration status of the device with respect to receiving GCM notifications from Paydiant.

Note: This method does not check whether the device is enabled for GCM message notifications, only whether the device is subscribed to receive messages from Paydiant.

Item Description
UI Method public void isRegisteredWithPaydiant ();
Success void onIsRegisteredWithPaydiantSuccess(boolean status);

TRUE if the device already has a valid registration ID
FALSE if no record of registration is detected.
Failure void onGMCUtilityServiceError(PaydiantException e)

The failure callback returns an instance of PaydiantException detailing the nature of the failure and the relevant errors as they relate to the GCM_CHECK_REGISTRATION_EVENT.
Core Method public boolean isRegisteredForGCM ();

Returns raw output

Errors

When checking the device messaging registration status, the following errors are applicable for the GCM_CHECK_REGISTRATION_EVENT:

Error Description
403 Access to the server is prohibited because the user is not logged-in.
500 An unknown error occurred internally in the server.

Register for GCM and Paydiant Messaging

Invoke this method from the UI service package to register the device with GCM connection servers, then automatically use the registration id returned to complete the Paydiant messaging registration. This method is not available in the Core package.

Item Description
UI Method public void register(String senderId);
Parameters senderId - The caller’s unique identifier when accessing the Google API console.
Success void onRegistrationSuccess(String registrationId);

The success callback returns the registrationId that was generated by the GCM service to confirm the registration.
Failure void onGMCUtilityServiceError(PaydiantException e)

The failure callback returns an instance of PaydiantException detailing the nature of the failure and the relevant errors as they relate to the GCM_REGISTRATION_EVENT.
Core Method There is no Core implementation for this call.

Errors

When checking the device messaging registration status, the following errors are applicable for the GCM_REGISTRATION_EVENT:

Error Description
400 Could not register the device due to invalid parameters in the request.
403 Access to the server is prohibited because the user is not logged-in.
500 An unknown error occurred internally in the server.
GCM ERROR_INVALID_SENDER Error message passed from Google’s Cloud Messaging service.
GCM ERROR_SERVICE_NOT_AVAILABLE Error message passed from Google’s Cloud Messaging service.
GCM ERROR_INVALID_PARAMETERS Error message passed from Google’s Cloud Messaging service.

Register for Paydiant Messaging

If the device is already registered with the GCM service, invoke this method from the core or UI service package to register for messaging from the Paydiant service.

Note: If the app has already called the Register for GCM and Paydiant Messaging method to simultaneously enable the GCM service and subscribe to messaging from Paydiant, do NOT invoke this method, as it will put the registration into an unrecoverable state. This call is intended ONLY for devices that have previously registered for the GCM service (perhaps in order to enable messaging from a different app), but have NOT subscribed to receive messages from Paydiant.

Item Description
UI Method public void registerWithPaydiant (String registrationId);
Parameters registrationId - The ID returned by the GCM service to confirm registration.
Success void onRegistrationWithPaydiantSuccess();

The success callback returns no additional parameters.
Failure void onGMCUtilityServiceError(PaydiantException e)

The failure callback returns an instance of PaydiantException detailing the nature of the failure and the relevant errors as they relate to the GCM_REGISTRATION_WITH_PAYDIANT_EVENT.
Core Method public void registerForGCM (String registrationId);
Parameters registrationId - The ID returned by the GCM service to confirm registration.

Errors

When checking the device messaging registration status, the following errors are applicable for the GCM_REGISTRATION_WITH_PAYDIANT_EVENT:

Error Description
400 Could not update device properties due to invalid parameters in the request.
403 Access to the server is prohibited because the user is not logged-in.
500 An unknown error occurred internally in the server.

Disable Messaging from Paydiant

Invoke this method to unsubscribe the device from receiving messages from the Paydiant service. This method does NOT disable the overall GCM registration.

Note: Before invoking this call, check whether the device is currently registered to receive messages from Paydiant (see Check Current Device Registration). Calling this method for an already unregistered device will return an exception.

Item Description
UI Method public void unregisterFromPaydiant();
Success void onUnregistrationWithPaydiantSuccess();

The success callback returns no additional parameters.
Failure void onGMCUtilityServiceError(PaydiantException e)

The failure callback returns an instance of PaydiantException detailing the nature of the failure and the relevant errors as they relate to the GCM_UNREGISTER_WITH_PAYDIANT_EVENT.
Core Method public void unregister ();

Errors

When checking the device messaging registration status, the following errors are applicable for the GCM_UNREGISTER_WITH_PAYDIANT_EVENT:

Error Description
403 Access to the server is prohibited because the user is not logged-in.
400 Can’t unregister because no registration exists.
500 An unknown error occurred internally in the server.

Disable Messaging from GCM and Paydiant

Invoke this method to disconnect the device’s from messaging registration with both GCM servers and the Paydiant service.

Item Description
UI Method public void unregister();
Success void onUnregistrationSuccess();

The success callback returns no additional parameters.
Failure void onGMCUtilityServiceError(PaydiantException e)

The failure callback returns an instance of PaydiantException detailing the nature of the failure and the relevant errors as they relate to the GCM_UNREGISTER_EVENT.
Core Method The Core implementation is not available for this call.

Errors

When checking the device messaging registration status, the following errors are applicable for the GCM_UNREGISTER_EVENT:

Error Description
403 Access to the server is prohibited because the user is not logged-in.
500 An unknown error occurred internally in the server.
GCM ERROR_INVALID_SENDER Error message passed from Google’s Cloud Messaging service
GCM ERROR_SERVICE_NOT_AVAILABLE Error message passed from Google’s Cloud Messaging service

Other Resources

javadocs