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.

Author:

Jon Chambers

See Also:

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

Field Summary

static String

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

Constructor Summary

ApnsPayloadBuilder()
Constructs a new payload builder.

Method Summary

void	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.
void	setAlertBody(String alertBody) Sets the literal text of the alert message to be shown for the push notification.
void	setBadgeNumber(Integer badgeNumber) Sets the number to display as the badge of the icon of the application that receives the push notification.
void	setLaunchImage(String launchImageFilename) Sets the image to be shown when the receiving app launches in response to this push notification.
void	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.
void	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.
void	setShowActionButton(boolean showActionButton) Sets whether an "action" button should be shown if the push notification is displayed as an alert.
void	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 void 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 void 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

setLaunchImage

public void setLaunchImage(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 void 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 void 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 void 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

setSoundFileName

public void 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

addCustomProperty

public void 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 (256 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)