Mobile SDK Android: EPZPushNotificationService
From ePrize Developers Wiki
Revision as of 23:08, 6 November 2014
Overview
The EPZPushNotificationService class is a Singleton class that provides the necessary logic to interface a user's device with the HelloWorld Push Notification Service. It provides the methods to subscribe/unsubscribe a device, retrieve and save push notification preferences, retrieve full notification data, and even record custom actions taken for specific notifications.
To be able to successfully subscribe a device and achieve full integration with the service, your application must be set up with the necessary permissions, as outlined in the "Update your app's Manifest file" section of the main Mobile_SDK_Android page.
Since this class is a Singleton, you will not create an instance of it. Rather, you will simply reference it via the getInstance() method in order to access the data stored within the class, and methods to be called from the class.
For example, to subscribe a user's device:
EPZPushNotificationService.getInstance().subscribeUserDevice();
...or to fetch a user's push notification preferences:
EPZPushNotificationService.getInstance().fetchPushNotificationPreferences();
Public Methods
getInstance
public static synchronized EPZPushNotificationService getInstance()
Returns
EPZPushNotificationService singleton instance.
configure
public void configure(Map<String, Object> options) throws Exception
Configures the push service with options set in the "options" argument. This method must be called before interacting with any other methods of the push service (e.g. subscribing a user's device, fetching push notification preferences, etc).
Parameters
options A map of options used for configuration. Valid options (and their value type) are listed below:
- EPZConstants.CONFIG_KEY_PUSH_KEY (String) required
Your push key. - EPZConstants.CONFIG_KEY_APP_CONTEXT (Context) required
A Context of the application package. - EPZConstants.CONFIG_KEY_GCM_SENDER_ID (String) required
The Project Number value of the Google Cloud Messaging-enabled project from the Google Developers Console. - EPZConstants.CONFIG_KEY_APP_ID (String)
The application package value. If not specified, will use the package name of your application. - EPZConstants.CONFIG_KEY_NOTIFICATION_ICON_SMALL (Integer)
Resource id for the small notification icon used in building the default Notification when a push notification is received.
- EPZConstants.CONFIG_KEY_PUSH_KEY (String) required
Important Note:
As mentioned in the Getting Started section, if you have requested using a different Push Key for development/testing than you are for your final production release, you will need to use a unique App Package for each. The app package does not need to be your exact package name, as it is just used as a unique identifier for your app in the Push Notification Service back-end. As such, simply adding ".dev" to the end of this value will suffice for using in your development/testing. Just be sure to make note of this when submitting the appropriate information to your HelloWorld account team or Producer.
In this case, you will need to be sure you include the EPZConstants.CONFIG_KEY_APP_ID key/value pair when you call the configure method..
Throws
Exception if any required configuration parameters are not specified.
getAppContext
public Context getAppContext()
Returns
Context The context of the application package, as specified in the configure method.
setAppContext
public void setAppContext(Context context)
Method to set the application context.
Parameters
context A Context of the application package.
isSupported
public boolean isSupported(Activity activity)
Parameters
activity Parent Activity for creating the error dialog, if necessary, when Google Play Services is not available.
Returns
Boolean flag of the availability of Google Play Services on the device.
userIsSubscribed
public boolean userIsSubscribed()
Returns
Boolean flag for whether or not the user is subscribed to the EPZPushNotificationService.
subscribeUserDevice
public void subscribeUserDevice()
Method to subscribe the device with Google Cloud Messaging and the EPZPushNotificationService.
This method will publish a EPZPushSubscribeEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushSubscribeEvent(EPZPushSubscribeEvent event) {
if (event.error != null) {
// There was an error subscribing the user.
} else {
// Subscription was successful. You can now safely fetch push preferences.
}
}
unsubscribeUser
public void unsubscribeUser()
Method to unsubscribe the device from the EPZPushNotificationService.
This method will publish a EPZPushUnsubscribeEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushUnsubscribeEvent(EPZPushUnsubscribeEvent event) {
if (event.error != null) {
// There was an error unsubscribing the user.
} else {
// Unsubscription was successful.
}
}
fetchPushNotificationPreferences
public void fetchPushNotificationPreferences()
Method to retrieve a user's push notification preferences.
This method will publish a EPZPushPreferencesFetchEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushPreferencesFetchEvent(EPZPushPreferencesFetchEvent event) {
if (event.error != null) {
// There was an error fetching push preferences.
} else {
// Fetching push preferences was successful.
}
}
launchPushPreferencesActivity
public void launchPushPreferencesActivity(Context context)
Method that launches the SDK's default EPZPushPreferencesViewController activity, which uses PreferenceScreens to display the preferences to the user, where they can set individual preference values.
This method will publish a EPZPushPreferencesViewLifecycleEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushPreferencesViewLifecycleEvent(EPZPushPreferencesViewLifecycleEvent event) {
if (event.error != null) {
// There was an error launching the push preferences activity.
} else {
if (event.eventName.equals(EPZConstants.LIFECYCLE_EVENT_OPEN)) {
// Push preferences view has been created and is open.
} else if (event.eventName.equals(EPZConstants.LIFECYCLE_EVENT_CLOSE)) {
// Push preferences view is closing.
}
}
}
Parameters
context Activity context used to start the EPZPushPreferencesViewController activity.
updatePreferenceOptIn
public void updatePreferenceOptIn(Map<String, Boolean> values)
Method to update the value of EPZPreferenceItem object(s).
Parameters
values Map<String, Boolean> with key values of EPZPreferenceItem preference IDs, and values of the new boolean value to which it should be set.
savePushNotificationPreferences
public void savePushNotificationPreferences()
Method to save a user's push preferences.
This method will publish a EPZPushPreferencesSaveEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushPreferencesSaveEvent(EPZPushPreferencesSaveEvent event) {
if (event.error != null) {
// There was an error saving push preferences.
} else {
// Saving push preferences was successful.
}
}
Note: This method uses the preference values stored in the EPZPushNotificationService singleton instance, which are updated automatically using the method updatePreferenceOptIn(). As such, for custom implementations of displaying push preferences to the user (e.g. not using the built-in EPZPushPreferencesViewController), you will need to ensure you call the update method in order to keep track of changes in a user's preference values.
fetchAdditionalNotificationData
public void fetchAdditionalNotificationData(String notificationID, boolean isForEPZBroadcastReceiver)
Method to fetch additional notification data for the specified notification ID.
This method will publish a EPZPushNotificationDataEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushNotificationDataEvent(EPZPushNotificationDataEvent event) {
if (event.error != null) {
// There was an error fetching the additional notification data.
} else {
// Fetching additional notification data was successful.
}
}
Parameters
notificationID The notification ID used to retrieve corresponding notification data.
isForEPZBroadcastReceiver Boolean flag alerting the EPZPushNotificationService as to whether or not the originator of the method call is the EPZBroadcastReceiver. This is necessary because the EPZBroadcastReceiver does not subscribe to the EPZPushNotificationDataEvent as the parent app will normally do. (Note: If this value is set to true, the EPZBusProvider will not publish the EPZPushNotificationDataEvent, but will dispatch one of the implementation methods in the EPZPushNotificationServiceListener, which is only intended for internal logic of the SDK.)
recordActionForPushNotification
public void recordActionForPushNotification(String notificationID, String actionName, String actionValue)
Method to record an action (event) for a specific notification ID.
This method will publish a EPZPushActionEvent to the EPZBusProvider, which your application can subscribe to and react accordingly. Note that when subscribing to and handling this event, you should always perform a conditional check to see whether or not the event's error property is null, and perform your next code decisions accordingly.
Sample event subscription method implementation:
@Subscribe
public void handlePushActionEvent(EPZPushActionEvent event) {
if (event.error != null) {
// There was an error recording the action.
} else {
// Recording action was successful.
}
}
Parameters
notificationID The notification ID to associate with the action, as gleaned from the initial notification.
actionName The name of the action (event). While this is an open value, you may use the Constant values EPZ_PUSH_ACTION_NAME_RECEIVED and EPZ_PUSH_ACTION_NAME_OPENED, as defined in EPZConstants, as they provide a good base to normalize action names across your application.
actionValue The value of the action (event). While this is an open value, you may wish to use a boolean string value ("0" or "1") for this value, especially if using the predefined constant action names EPZ_PUSH_ACTION_NAME_RECEIVED or EPZ_PUSH_ACTION_NAME_OPENED, as defined in EPZConstants.
getPushNotificationPreferences
public ArrayList<EPZPreferenceItem> getPushNotificationPreferences()
Method to retrieve top-level EPZPreferenceItem objects.
Note: Each item may have nested preference items, accessed via the EPZPreferenceItem getChildren() method.
Returns
ArrayList<EPZPreferenceItem> Array of EPZPreferenceItem objects.
getPushNotificationPreferenceItem
public EPZPreferenceItem getPushNotificationPreferenceItem(String preferenceID)
Parameters
preferenceID The preference item ID to match.
Returns
EPZPreferenceItem object for the specified preference ID. This may be null if there is no object found for the specified ID value.
getRegistrationId
public String getRegistrationId()
Returns
String value of device ID registered with the push notification service.
getPushKey
public String getPushKey()
Returns
String value of push key associated with the push notification service, as specified in the configure method.
