Package com.eatthepath.pushy.apns.util

Class ApnsPayloadBuilder

java.lang.Object
com.eatthepath.pushy.apns.util.ApnsPayloadBuilder
Direct Known Subclasses:
SimpleApnsPayloadBuilder
public abstract class ApnsPayloadBuilder extends Object

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

Since:
0.14.0
Author:
Jon Chambers
See Also:

  • Field Details

  • Constructor Details

    • ApnsPayloadBuilder

      public ApnsPayloadBuilder()

  • Method Details

    • 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. 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

      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
      Returns:
      a reference to this payload builder
      See Also:

    • setAlertTitle

      public ApnsPayloadBuilder setAlertTitle(String alertTitle)

      Sets a short description of the notification purpose. 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

      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
      Returns:
      a reference to this payload builder

    • setAlertSubtitle

      public ApnsPayloadBuilder setAlertSubtitle(String alertSubtitle)

      Sets a subtitle for the notification. 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. 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

      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:

    • 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:

    • setSoundFileName

      @Deprecated public ApnsPayloadBuilder setSoundFileName(String soundFileName)
      Deprecated.
      As of v0.13.3, please use setSound(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, or null to send no sound
      Returns:
      a reference to this payload builder
      See Also:

    • 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, or null to send no sound
      Returns:
      a reference to this payload builder
      Since:
      0.13.3
      See Also:

    • 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 a null sound filename.

      Parameters:
      soundFileName - the name of the sound file to play; must not be null
      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:

    • 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:

    • 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:

    • 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 the categorySummaryFormat 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; if null, the summary-arg key is omitted from the payload entirely
      Returns:
      a reference to this payload builder
      Since:
      0.13.6
      See Also:

    • 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; if null, the summary-arg-count key is omitted from the payload entirely
      Returns:
      a reference to this payload builder
      Since:
      0.13.6
      See Also:

    • setInterruptionLevel

      public ApnsPayloadBuilder setInterruptionLevel(InterruptionLevel interruptionLevel)

      Sets the interruption level for this notification. By default, no interruption level is included in the payload and a default of InterruptionLevel.ACTIVE is assumed by the receiving device.

      Interruption levels are supported in iOS 15 and newer.

      Parameters:
      interruptionLevel - the interruption level for this notification
      Returns:
      a reference to this payload builder
      Since:
      0.15.0
      See Also:

    • setRelevanceScore

      public ApnsPayloadBuilder setRelevanceScore(Double relevanceScore)

      Sets the relevance score for this notification. By default, no relevance score is included.

      The relevance score is:

      …a number… that the system uses to sort the notifications from your app. The highest score gets featured in the notification summary.
      Parameters:
      relevanceScore - a relevance score, or null if no relevance score should be included in the notification
      Returns:
      a reference to this payload builder
      Since:
      0.15.0

    • setStaleDate

      public ApnsPayloadBuilder setStaleDate(Instant staleDate)

      Sets a "stale" timestamp for Live Activity notification payloads. According to Apple's documentation:

      To provide the best possible user experience and let the person know that the activity displays outdated information, add a timestamp in the optional stale-date field to provide the time when the system will consider the Live Activity to be stale. With each update to the Live Activity, you can advance this stale-date. When you can’t update the Live Activity for some time until it becomes stale, the activityState changes to ActivityState.stale at the specified date. Use the activityStateUpdates stream in your app to monitor the activity state and respond to outdated Live Activities that haven’t received updates
      Parameters:
      staleDate - Instant when the Live Activity will be considered stale
      Returns:
      a reference to this payload builder
      Since:
      0.15.3
      See Also:

    • 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 omitted from the payload entirely
      Returns:
      a reference to this payload builder
      Since:
      0.8.2
      See Also:

    • 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 omitted from the payload entirely
      Returns:
      a reference to this payload builder
      Since:
      0.8.2
      See Also:

    • 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 precise strategy for serializing the values of custom properties is defined by the specific ApnsPayloadBuilder implementation.

      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
      Throws:
      IllegalArgumentException - if the key equals to "aps"

    • setAttributesType

      public ApnsPayloadBuilder setAttributesType(String attributesType)
      Sets the type of iOS ActivityAttributes used for a Live Activity. Must be set for a notification that starts a live activity.
      Parameters:
      attributesType - the type of ActivityAttributes used for a Live Activity
      Returns:
      a reference to this payload builder
      Since:
      0.15.4
      See Also:

    • setAttributes

      public ApnsPayloadBuilder setAttributes(Map<String,Object> attributes)
      Sets the values of iOS ContentState attributes when starting a Live Activity. Must be set for a notification that starts a live activity.
      Parameters:
      attributes - the attributes used to populate the ContentState for the newly-started live activity
      Returns:
      a reference to this payload builder
      Since:
      0.15.4
      See Also:

    • setContentState

      public ApnsPayloadBuilder setContentState(Map<String,Object> contentState)

      Sets the content state object inside content-state payload for Live Activities.

      The precise strategy for serializing the values of custom properties is defined by the specific ApnsPayloadBuilder implementation.

      Parameters:
      contentState - content-state object
      Returns:
      a reference to this payload builder
      Since:
      0.15.2
      See Also:

    • setEvent

      public ApnsPayloadBuilder setEvent(LiveActivityEvent event)

      Sets whether the notification payload will be used for updating the Live Activity or for ending it.

      Parameters:
      event - the type of update event to send to the destination activity
      Returns:
      a reference to this payload builder
      Since:
      0.15.2
      See Also:

    • setTimestamp

      public ApnsPayloadBuilder setTimestamp(Instant timestamp)

      Sets the Live Activity timestamp for the push notification payload.

      Parameters:
      timestamp - Instant at which the Live Activity event occurred
      Returns:
      a reference to this payload builder
      Since:
      0.15.2
      See Also:

    • setDismissalDate

      public ApnsPayloadBuilder setDismissalDate(Instant dismissalDate)

      Sets a dismissal timestamp for Live Activity notifications. According to Apple's documentation:

      When you end a Live Activity, by default the Live Activity appears on the Lock Screen for up to four hours after it ends to allow the user to glance at their phone to see the latest information. To dismiss the Live Activity from the Lock Screen immediately after it ends, provide a date for "dismissal-date" that’s in the past. Alternatively, provide a date within a four-hour window to set a custom dismissal date.
      Parameters:
      dismissalDate - Instant when the Live Activity will be dismissed
      Returns:
      a reference to this payload builder
      Since:
      0.15.2
      See Also:

    • build

      public abstract String build()
      Returns a JSON representation of the push notification payload under construction.
      Returns:
      a JSON representation of the payload under construction
      Since:
      0.14.0
      See Also:
      • buildPayloadMap()

    • buildMdmPayload

      public abstract 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.14.0
      See Also: