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:
- Generating a Remote Notification
-
-
Field Summary
Fields Modifier and Type Field 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 Description ApnsPayloadBuilder()
-
Method Summary
Modifier and Type Method 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
setSound(String soundFileName)
Sets the name of the sound file to play when the push notification is received.ApnsPayloadBuilder
setSound(String soundFileName, boolean isCriticalAlert, double soundVolume)
Sets the name of the sound file to play when the push notification is received along with its volume and whether it should be presented as a critical alert.ApnsPayloadBuilder
setSoundFileName(String soundFileName)
Deprecated.As of v0.13.3, please usesetSound(String)
instead.ApnsPayloadBuilder
setSummaryArgument(String summaryArgument)
Sets the summary argument for this notification.ApnsPayloadBuilder
setSummaryArgumentCount(Integer summaryArgumentCount)
Sets the summary argument count for this notification.ApnsPayloadBuilder
setTargetContentId(String targetContentId)
Sets the identifier of the window to be brought forward by this notification.ApnsPayloadBuilder
setThreadId(String threadId)
Sets the thread ID for this notification.ApnsPayloadBuilder
setUrlArguments(String... arguments)
Sets the list of arguments to populate placeholders in theurlFormatString
associated with a Safari push notification.ApnsPayloadBuilder
setUrlArguments(List<String> arguments)
Sets the list of arguments to populate placeholders in theurlFormatString
associated with a Safari push notification.
-
-
-
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.
-
-
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
- iftrue
, 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 listalertArguments
- arguments to populate placeholders in the localized alert string; may benull
- 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 listalertTitleArguments
- arguments to populate placeholders in the localized alert string; may benull
- 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 listalertSubtitleArguments
- arguments to populate placeholders in the localized subtitle string; may benull
- 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’sInfo.plist
file, or falls back toDefault.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. Iffalse
, no action button is shown under any circumstancesBy default, an action button will be shown.
- Parameters:
showActionButton
-true
to show an action button when the push notification is presented as an alert orfalse
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 ornull
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:
- Declaring Your Actionable Notification Types
-
setSoundFileName
@Deprecated public ApnsPayloadBuilder setSoundFileName(String soundFileName)
Deprecated.As of v0.13.3, please usesetSound(String)
instead.Sets the name of the sound file to play when the push notification is received. According to Apple's documentation, the sound filename should be:
The name of a sound file in your app’s main bundle or in the
Library/Sounds
folder of your app’s container directory.By default, no sound is included in the push notification.
- Parameters:
soundFileName
- the name of the sound file to play, ornull
to send no sound- Returns:
- a reference to this payload builder
- See Also:
DEFAULT_SOUND_FILENAME
-
setSound
public ApnsPayloadBuilder setSound(String soundFileName)
Sets the name of the sound file to play when the push notification is received. According to Apple's documentation, the sound filename should be:
The name of a sound file in your app’s main bundle or in the
Library/Sounds
folder of your app’s container directory.By default, no sound is included in the push notification.
- Parameters:
soundFileName
- the name of the sound file to play, ornull
to send no sound- Returns:
- a reference to this payload builder
- Since:
- 0.13.3
- See Also:
DEFAULT_SOUND_FILENAME
-
setSound
public ApnsPayloadBuilder setSound(String soundFileName, boolean isCriticalAlert, double soundVolume)
Sets the name of the sound file to play when the push notification is received along with its volume and whether it should be presented as a critical alert. According to Apple's documentation, the sound filename should be:
The name of a sound file in your app’s main bundle or in the
Library/Sounds
folder of your app’s container directory.By default, no sound is included in the push notification.
To explicitly specify that no sound should be played as part of this notification, use
setSound(String)
with anull
sound filename.- Parameters:
soundFileName
- the name of the sound file to play; must not benull
isCriticalAlert
- specifies whether this sound should be played as a "critical alert"soundVolume
- the volume at which to play the sound; must be between 0.0 (silent) and 1.0 (loudest)- Returns:
- a reference to this payload builder
- Since:
- 0.13.3
- 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 orfalse
otherwise- Returns:
- a reference to this payload builder
- See Also:
- Pushing Updates to Your App Silently
-
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 orfalse
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
-
setTargetContentId
public ApnsPayloadBuilder setTargetContentId(String targetContentId)
Sets the identifier of the window to be brought forward by this notification. By default, no target content ID is included.- Parameters:
targetContentId
- the identifier of the window to be brought forward by this notification- Returns:
- a reference to this payload builder
- Since:
- 0.13.10
-
setSummaryArgument
public ApnsPayloadBuilder setSummaryArgument(String summaryArgument)
Sets the summary argument for this notification. The summary argument is:
The string the notification adds to the category’s summary format string.
For example in iOS 12, when defining an
UNNotificationCategory
, passing a format string like "%u more messages from %@" to thecategorySummaryFormat
argument, will produce "x more messages from {summaryArgument}.In iOS 12, the default summary format string in English is "%u more notifications" and does not have a placeholder for a summary argument. By default, no summary argument is included in push notification payloads.
- Parameters:
summaryArgument
- the summary argument for this notification; ifnull
, thesummary-arg
key is omitted from the payload entirely- Returns:
- a reference to this payload builder
- Since:
- 0.13.6
- See Also:
- UNNotificationContent
-
setSummaryArgumentCount
public ApnsPayloadBuilder setSummaryArgumentCount(Integer summaryArgumentCount)
Sets the summary argument count for this notification. The summary argument count is:
The number of items the notification adds to the category’s summary format string.
By default, all notifications count as a single "item" in a group of notifications. The summary argument count controls how many "items" in a "stack" of notifications are represented by a specific notification. If, for example, a notification informed a user that seven new podcasts are available, it might be helpful to set the summary argument count to 7. When "stacked," the notification would contribute an item count of 7 to the total number of notifications reported in the summary string (for example, "7 more podcasts").
By default, notifications count as a single "item" in a group of notifications, and so the default summary argument count is 1 (even if no summary argument count is specified in the notification payload). If specified, summary argument count must be positive.
- Parameters:
summaryArgumentCount
- the summary argument count for this notification; ifnull
, thesummary-arg-count
key is omitted from the payload entirely- Returns:
- a reference to this payload builder
- Since:
- 0.13.6
- See Also:
- UNNotificationContent
-
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 theurlFormatString
value and the order of the placeholders in the URL format string determines the order of the values supplied by theurl-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; ifnull
, theurl-args
key is omitted 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 theurlFormatString
value and the order of the placeholders in the URL format string determines the order of the values supplied by theurl-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; ifnull
, theurl-args
key is omitted 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 objectvalue
- 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 (4096 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 aTokenUpdate
message- Returns:
- a JSON representation of an MDM "wake up" notification payload
- Since:
- 0.12
- See Also:
- Mobile Device Management (MDM) Protocol
-
-