com.relayrides.pushy.apns.util

Class ApnsPayloadBuilder

java.lang.Object

com.relayrides.pushy.apns.util.ApnsPayloadBuilder

public class ApnsPayloadBuilder
extends Object

A utility class for constructing JSON payloads suitable for inclusion in APNs push notifications. Payload builders are reusable, but are not thread-safe.

Author:

Jon Chambers

See Also:

Local and Push Notification Programming Guide - Apple Push Notification Service - The Notification Payload

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_SOUND_FILENAME The name of the iOS default push notification sound ("default").

Constructor Summary

Constructors

Constructor and Description
ApnsPayloadBuilder() Constructs a new payload builder.

Method Summary

Methods

Modifier and Type	Method and Description
ApnsPayloadBuilder	addCustomProperty(String key, Object value) Adds a custom property to the payload.
String	buildWithDefaultMaximumLength() Returns a JSON representation of the push notification payload under construction.
String	buildWithMaximumLength(int maximumPayloadLength) Returns a JSON representation of the push notification payload under construction.
ApnsPayloadBuilder	setAlertBody(String alertBody) Sets the literal text of the alert message to be shown for the push notification.
ApnsPayloadBuilder	setAlertTitle(String alertTitle) Sets a short description of the notification purpose.
ApnsPayloadBuilder	setBadgeNumber(Integer badgeNumber) Sets the number to display as the badge of the icon of the application that receives the push notification.
ApnsPayloadBuilder	setCategoryName(String categoryName) Sets the name of the action category name for interactive remote notifications.
ApnsPayloadBuilder	setContentAvailable(boolean contentAvailable) Sets whether the payload under construction should contain a flag that indicates that new content is available to be downloaded in the background by the receiving app.
ApnsPayloadBuilder	setLaunchImageFileName(String launchImageFilename) Sets the image to be shown when the receiving app launches in response to this push notification.
ApnsPayloadBuilder	setLocalizedActionButtonKey(String localizedActionButtonKey) Sets the key of a string in the receiving app's localized string list to be used as the label of the "action" button if the push notification is displayed as an alert.
ApnsPayloadBuilder	setLocalizedAlertMessage(String localizedAlertKey, String[] alertArguments) Sets the key of a message in the receiving app's localized string list to be shown for the push notification.
ApnsPayloadBuilder	setLocalizedAlertTitle(String localizedAlertTitleKey, String[] alertTitleArguments) Sets the key of the title string in the receiving app's localized string list to be shown for the push notification.
ApnsPayloadBuilder	setShowActionButton(boolean showActionButton) Sets whether an "action" button should be shown if the push notification is displayed as an alert.
ApnsPayloadBuilder	setSoundFileName(String soundFileName) Sets the name of the sound file to play when the push notification is received.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_SOUND_FILENAME

public static final String DEFAULT_SOUND_FILENAME

The name of the iOS default push notification sound ("default").

See Also:

setSoundFileName(String), Constant Field Values

Constructor Detail

ApnsPayloadBuilder

public ApnsPayloadBuilder()

Constructs a new payload builder.

Method Detail

setAlertBody

public ApnsPayloadBuilder setAlertBody(String alertBody)

Sets the literal text of the alert message to be shown for the push notification. A literal alert message may not be set if a localized alert message key is already specified.

By default, no message is shown.

Parameters:

alertBody - the literal message to be shown for this push notification

See Also:

setLocalizedAlertMessage(String, String[])

setLocalizedAlertMessage

public ApnsPayloadBuilder setLocalizedAlertMessage(String localizedAlertKey,
                                          String[] alertArguments)

Sets the key of a message in the receiving app's localized string list to be shown for the push notification. The message in the app's string list may optionally have placeholders, which will be populated by values from the given alertArguments.

By default, no message is shown.

Parameters:

localizedAlertKey - a key to a string in the receiving app's localized string list

alertArguments - arguments to populate placeholders in the localized alert string; may be null

setAlertTitle

public ApnsPayloadBuilder setAlertTitle(String alertTitle)

Sets a short description of the notification purpose. The Apple Watch will display this as part of the notification. According to Apple's documentation, this should be:

A short string describing the purpose of the notification. Apple Watch displays this string as part of the notification interface. This string is displayed only briefly and should be crafted so that it can be understood quickly.

Parameters:

alertTitle - the description to be shown for this push notification

See Also:

setLocalizedAlertTitle(String, String[])

setLocalizedAlertTitle

public ApnsPayloadBuilder setLocalizedAlertTitle(String localizedAlertTitleKey,
                                        String[] alertTitleArguments)

Sets the key of the title string in the receiving app's localized string list to be shown for the push notification. The message in the app's string list may optionally have placeholders, which will be populated by values from the given alertArguments.

Parameters:

localizedAlertTitleKey - a key to a string in the receiving app's localized string list

alertTitleArguments - arguments to populate placeholders in the localized alert string; may be null

setLaunchImageFileName

public ApnsPayloadBuilder setLaunchImageFileName(String launchImageFilename)

Sets the image to be shown when the receiving app launches in response to this push notification. According to Apple's documentation, this should be:

The filename of an image file in the application bundle; it may include the extension or omit it. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot, uses the image identified by the UILaunchImageFile key in the application’s Info.plist file, or falls back to Default.png.

Parameters:

launchImageFilename - the filename of an image file in the receiving app's bundle to be shown when launching the app from the push notification

setShowActionButton

public ApnsPayloadBuilder setShowActionButton(boolean showActionButton)

Sets whether an "action" button should be shown if the push notification is displayed as an alert. If true and no localized action button key is set, the default label (defined by the receiving operating system) is used. If @{code true} and a localized action button key is set, the string for that key is used as the label of the action button. If false, no action button is shown under any circumstances

By default, an action button will be shown.

Parameters:

showActionButton - true to show an action button when the push notification is presented as an alert or false to show an alert with no action button

setLocalizedActionButtonKey

public ApnsPayloadBuilder setLocalizedActionButtonKey(String localizedActionButtonKey)

Sets the key of a string in the receiving app's localized string list to be used as the label of the "action" button if the push notification is displayed as an alert. By default, the OS-default label will be used for the action button.

Parameters:

localizedActionButtonKey - a key to a string in the receiving app's localized string list

setBadgeNumber

public ApnsPayloadBuilder setBadgeNumber(Integer badgeNumber)

Sets the number to display as the badge of the icon of the application that receives the push notification. If the badge number is 0, the badge is removed from the application icon. If null, the badge is left in its current state. By default, no change is made to the badge.

Parameters:

badgeNumber - the number to display as the badge of application or null to leave the badge unchanged

setCategoryName

public ApnsPayloadBuilder setCategoryName(String categoryName)

Sets the name of the action category name for interactive remote notifications.

Parameters:

categoryName - the action category name

setSoundFileName

public ApnsPayloadBuilder setSoundFileName(String soundFileName)

Sets the name of the sound file to play when the push notification is received. According to Apple's documentation, the value here should be:

...the name of a sound file in the application bundle. The sound in this file is played as an alert. If the sound file doesn't exist or default is specified as the value, the default alert sound is played.

By default, no sound is included in the push notification.

Parameters:

soundFileName - the name of the sound file to play, or null to send no sound

See Also:

DEFAULT_SOUND_FILENAME

setContentAvailable

public ApnsPayloadBuilder setContentAvailable(boolean contentAvailable)

Sets whether the payload under construction should contain a flag that indicates that new content is available to be downloaded in the background by the receiving app. By default, no content availability flag is included in the payload.

Parameters:

contentAvailable - true to include a flag that indicates that new content is available to be downloaded in the background or false otherwise

See Also:

iOS App Programming Guide - App States and Multitasking - Background Execution and Multitasking - Implementing Long-Running Background Tasks

addCustomProperty

public ApnsPayloadBuilder addCustomProperty(String key,
                                   Object value)

Adds a custom property to the payload. Values are mapped to JSON types according to the mapping table at https://code.google.com/p/json-simple/.

According to Apple's documentation:

Providers can specify custom payload values outside the Apple-reserved aps namespace. Custom values must use the JSON structured and primitive types: dictionary (object), array, string, number, and Boolean. You should not include customer information (or any sensitive data) as custom payload data. Instead, use it for such purposes as setting context (for the user interface) or internal metrics. For example, a custom payload value might be a conversation identifier for use by an instant-message client application or a timestamp identifying when the provider sent the notification. Any action associated with an alert message should not be destructive—for example, it should not delete data on the device.

Parameters:

key - the key of the custom property in the payload object

value - the value of the custom property

buildWithDefaultMaximumLength

public String buildWithDefaultMaximumLength()

Returns a JSON representation of the push notification payload under construction. If the payload length is longer than the default maximum (2048 bytes), the literal alert body will be shortened if possible. If the alert body cannot be shortened or is not present, an IllegalArgumentException is thrown.

Returns:

a JSON representation of the payload under construction (possibly with an abbreviated alert body)

buildWithMaximumLength

public String buildWithMaximumLength(int maximumPayloadLength)

Returns a JSON representation of the push notification payload under construction. If the payload length is longer than the given maximum, the literal alert body will be shortened if possible. If the alert body cannot be shortened or is not present, an IllegalArgumentException is thrown.

Parameters:

maximumPayloadLength - the maximum length of the payload in bytes

Returns:

a JSON representation of the payload under construction (possibly with an abbreviated alert body)