Android SDK - Google Cloud Messaging Utility Module
Last updated: Aug 15th, 7:18am
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 software 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 WLW. 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 WLW 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.
1< ?xml version="1.0" encoding="utf-8"? >2< manifest xmlns:android="http://schemas.android.com/apk/res/android" ... >3...4< uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" / >5< uses-permission android:name="<your package name>.permission.C2D_MESSAGE" / >6< uses-permission android:name="android.permission.GET_ACCOUNTS" / >7< uses-permission android:name="android.permission.WAKE_LOCK" / >8< permission android:name="< your package name >.permission.C2D_MESSAGE"9 android:protectionLevel="signature" / >10< uses-permission android:name="<your package name>.permission.C2D_MESSAGE" / >11< /manifest >
Set UI Package GCM Service Listeners
To invoke the callback methods returned by the WLW 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.IGCMUtilityServiceListeneror 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 WLW.
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 WLW.
| Item | Description |
|---|---|
| UI Method | public void isRegisteredWithPaydiant (); |
| Success | void onIsRegisteredWithPaydiantSuccess(boolean status);TRUE if the device already has a valid registration IDFALSE 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 WLW 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 WLW 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 WLW 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 WLW service.
Note: If the app has already called the Register for GCM and WLW Messaging method to simultaneously enable the GCM service and subscribe to messaging from WLW, 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 WLW.
| 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 WLW
Invoke this method to unsubscribe the device from receiving messages from the WLW 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 WLW (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 WLW
Invoke this method to disconnect the device’s from messaging registration with both GCM servers and the WLW 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 |