com.turo.pushy.apns.util

Class ApnsPayloadBuilder

java.lang.Object

com.turo.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 - Payload Key Reference

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAXIMUM_PAYLOAD_SIZE The default maximum size, in bytes, for a push notification payload.
static String	DEFAULT_SOUND_FILENAME The name of the iOS default push notification sound.

Constructor Summary

Constructors

Constructor and Description
ApnsPayloadBuilder()

Method Summary

Modifier and Type	Method and Description
ApnsPayloadBuilder	addCustomProperty(String key, Object value) Adds a custom property to the payload.
static String	buildMdmPayload(String pushMagicValue) Returns a JSON representation of a Mobile Device Management "wake up" payload.
String	buildWithDefaultMaximumLength() Returns a JSON representation of the push notification payload under construction.
String	buildWithMaximumLength(int maximumPayloadSize) Returns a JSON representation of the push notification payload under construction.
ApnsPayloadBuilder	setActionButtonLabel(String action) Sets the literal text of the action button to be shown for the push notification for Safari push notifications only.
ApnsPayloadBuilder	setAlertBody(String alertBody) Sets the literal text of the alert message to be shown for the push notification.
ApnsPayloadBuilder	setAlertSubtitle(String alertSubtitle) Sets a subtitle for the 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	setLocalizedAlertSubtitle(String localizedAlertSubtitleKey, String... alertSubtitleArguments) Sets the key of the subtitle string 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	setMutableContent(boolean mutableContent) Sets whether the receiving device may modify the content of the push notification before displaying it.
ApnsPayloadBuilder	setPreferStringRepresentationForAlerts(boolean preferStringRepresentationForAlerts) Sets whether this payload builder will attempt to represent alerts as strings when possible.
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.
ApnsPayloadBuilder	setThreadId(String threadId) Sets the thread ID for this notification.
ApnsPayloadBuilder	setUrlArguments(List<String> arguments) Sets the list of arguments to populate placeholders in the urlFormatString associated with a Safari push notification.
ApnsPayloadBuilder	setUrlArguments(String... arguments) Sets the list of arguments to populate placeholders in the urlFormatString associated with a Safari push notification.

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.

See Also:

setSoundFileName(String), Constant Field Values

DEFAULT_MAXIMUM_PAYLOAD_SIZE

public static final int DEFAULT_MAXIMUM_PAYLOAD_SIZE

The default maximum size, in bytes, for a push notification payload.

See Also:

buildWithDefaultMaximumLength(), Constant Field Values

Constructor Detail

ApnsPayloadBuilder

public ApnsPayloadBuilder()

Method Detail

setPreferStringRepresentationForAlerts

public ApnsPayloadBuilder setPreferStringRepresentationForAlerts(boolean preferStringRepresentationForAlerts)

Sets whether this payload builder will attempt to represent alerts as strings when possible. Older versions of the APNs specification recommended representing alerts as strings when only a literal alert body was provided, but recent versions recommend representing alerts as dictionaries regardless. This method is provided primarily for backward-compatibility. By default, payload builders will always represent alerts as dictionaries.

Parameters:

preferStringRepresentationForAlerts - if true, then this payload builder will represent alerts as strings when possible; otherwise, alerts will always be represented as dictionaries

Returns:

a reference to this payload builder

Since:

0.8.2

setAlertBody

public ApnsPayloadBuilder setAlertBody(String alertBody)

Sets the literal text of the alert message to be shown for the push notification. Clears any previously-set localized alert message key and arguments.

By default, no message is shown.

Parameters:

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

Returns:

a reference to this payload builder

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. Clears any previously-set literal alert body.

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

Returns:

a reference to this payload builder

See Also:

setAlertBody(String)

setAlertTitle

public ApnsPayloadBuilder setAlertTitle(String alertTitle)

Sets a short description of the notification purpose. Clears any previously-set localized title key and arguments. The Apple Watch will display the title 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.

By default, no title is included.

Parameters:

alertTitle - the description to be shown for this push notification

Returns:

a reference to this payload builder

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. Clears any previously-set literal alert title. 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

Returns:

a reference to this payload builder

setAlertSubtitle

public ApnsPayloadBuilder setAlertSubtitle(String alertSubtitle)

Sets a subtitle for the notification. Clears any previously-set localized subtitle key and arguments.

By default, no subtitle is included. Requires iOS 10 or newer.

Parameters:

alertSubtitle - the subtitle for this push notification

Returns:

a reference to this payload builder

Since:

0.8.1

setLocalizedAlertSubtitle

public ApnsPayloadBuilder setLocalizedAlertSubtitle(String localizedAlertSubtitleKey,
                                                    String... alertSubtitleArguments)

Sets the key of the subtitle string in the receiving app's localized string list to be shown for the push notification. Clears any previously-set literal subtitle. The message in the app's string list may optionally have placeholders, which will be populated by values from the given alertSubtitleArguments.

By default, no subtitle is included. Requires iOS 10 or newer.

Parameters:

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

alertSubtitleArguments - arguments to populate placeholders in the localized subtitle string; may be null

Returns:

a reference to this payload builder

Since:

0.8.1

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

Returns:

a reference to this payload builder

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

Returns:

a reference to this payload builder

setActionButtonLabel

public ApnsPayloadBuilder setActionButtonLabel(String action)

Sets the literal text of the action button to be shown for the push notification for Safari push notifications only. Clears any previously-set localized action key. By default, the OS-default label will be used for the action button.

Parameters:

action - the literal label to be shown on the action button for this notification

Returns:

a reference to this payload builder

Since:

0.8.2

See Also:

setLocalizedActionButtonKey(String), setShowActionButton(boolean)

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. Clears any previously-set literal action button label. 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

Returns:

a reference to this payload builder

See Also:

setActionButtonLabel(String), setShowActionButton(boolean)

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

Returns:

a reference to this payload builder

setCategoryName

public ApnsPayloadBuilder setCategoryName(String categoryName)

Sets the name of the action category name for interactive remote notifications. According to Apple's documentation, this should be:

...a string value that represents the identifier property of the UIMutableUserNotificationCategory object you created to define custom actions.

Parameters:

categoryName - the action category name

Returns:

a reference to this payload builder

See Also:

Configuring Categories and Actionable Notifications

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

Returns:

a reference to this payload builder

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

Returns:

a reference to this payload builder

See Also:

Configuring a Silent Notification

setMutableContent

public ApnsPayloadBuilder setMutableContent(boolean mutableContent)

Sets whether the receiving device may modify the content of the push notification before displaying it. Requires iOS 10 or newer.

Parameters:

mutableContent - true if the receiving device may modify the push notification before displaying it or false otherwise

Returns:

a reference to this payload builder

See Also:

UNNotificationServiceExtension

setThreadId

public ApnsPayloadBuilder setThreadId(String threadId)

Sets the thread ID for this notification. According to to the APNs documentation, the thread ID is:

…a string value that represents the app-specific identifier for grouping notifications. The system groups notifications with the same thread identifier together in Notification Center and other system interfaces.

By default, no thread ID is included.

Parameters:

threadId - the thread ID for this notification

Returns:

a reference to this payload builder

Since:

0.8.2

setUrlArguments

public ApnsPayloadBuilder setUrlArguments(List<String> arguments)

Sets the list of arguments to populate placeholders in the urlFormatString associated with a Safari push notification. Has no effect for non-Safari notifications. According to the Notification Programming Guide for Websites:

The url-args key must be included [for Safari push notifications]. The number of elements in the array must match the number of placeholders in the urlFormatString value and the order of the placeholders in the URL format string determines the order of the values supplied by the url-args array. The number of placeholders may be zero, in which case the array should be empty. However, it is common practice to always include at least one argument so that the user is directed to a web page specific to the notification received.

Parameters:

arguments - the arguments with which to populate URL placeholders, which may be an empty list; if null, the url-args key is ommitted from the payload entirely

Returns:

a reference to this payload builder

Since:

0.8.2

See Also:

Notification Programming Guide for Websites - Configuring Safari Push Notifications

setUrlArguments

public ApnsPayloadBuilder setUrlArguments(String... arguments)

Sets the list of arguments to populate placeholders in the urlFormatString associated with a Safari push notification. Has no effect for non-Safari notifications. According to the Notification Programming Guide for Websites:

The url-args key must be included [for Safari push notifications]. The number of elements in the array must match the number of placeholders in the urlFormatString value and the order of the placeholders in the URL format string determines the order of the values supplied by the url-args array. The number of placeholders may be zero, in which case the array should be empty. However, it is common practice to always include at least one argument so that the user is directed to a web page specific to the notification received.

Parameters:

arguments - the arguments with which to populate URL placeholders, which may be an empty array; if null, the url-args key is ommitted from the payload entirely

Returns:

a reference to this payload builder

Since:

0.8.2

See Also:

Notification Programming Guide for Websites - Configuring Safari Push Notifications

addCustomProperty

public ApnsPayloadBuilder addCustomProperty(String key,
                                            Object value)

Adds a custom property to the payload. 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.

The value for the property is serialized to JSON by Gson. For a detailed explanation of how Gson serializes Java objects to JSON, please see the Gson User Guide.

Parameters:

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

value - the value of the custom property

Returns:

a reference to this payload builder

See Also:

Gson.toJson(Object), Gson User Guide - Using Gson

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 ( 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)

Throws:

IllegalArgumentException - if the payload is too large and cannot be compressed by truncating its literal alert message

buildWithMaximumLength

public String buildWithMaximumLength(int maximumPayloadSize)

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:

maximumPayloadSize - the maximum length of the payload in bytes

Returns:

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

Throws:

IllegalArgumentException - if the payload is too large and cannot be compressed by truncating its literal alert message

buildMdmPayload

public static String buildMdmPayload(String pushMagicValue)

Returns a JSON representation of a Mobile Device Management "wake up" payload.

Parameters:

pushMagicValue - the "push magic" string that the device sends to the MDM server in a TokenUpdate message

Returns:

a JSON representation of an MDM "wake up" notification payload

Since:

0.12

See Also:

Mobile Device Management (MDM) Protocol