The Notification object

This object represents what the user will see. It is split into 3 main fields: alert and push. alert controls what the user will see in the notification center, and push controls various payload and push options.

The simplest form of notification you can create contains only a text alert:

{"alert":{"text": "Hello, WonderPush!"}}

Alert

Field	Type	Description
alert.text	string	The message to display in the notification center.
alert.title	string	The title of the notification to display in the notification center.
alert.targetUrl	a URL	The content that should be displayed when the user clicks the notification. missing, `null` or `wonderpush://notificationOpen/default`, the default. Simply shows the application. any deeplink URL (eg.: `yourapp://targetScreen?someParams`) The OS of the user device will resolve this accordingly. any HTTP URL (eg.: `https://www.yourwebsite.com/somePage?someTrackingInfo`) The OS of the user device will resolve this accordingly. It will point to your application if supported, or else will open the web browser. `wonderpush://notificationOpen/broadcast` Lets application code decide what screen to launch. * `wonderpush://notificationOpen/noop` Performs no action. Use this for your notification buttons. Clicking the notification itself should always have some visible feedback so avoid this value. More info on how to handle your own deeplinks: Android, iOS.
alert.tag	string, `null` or missing	If a notification using the same tag is currently displayed, it will be updated, otherwise, a new notification is shown.
alert.actions	array of objects	An optional list of background actions to perform when the user clicks the notification. See the list of available actions.
alert.ios	object	iOS specific options
alert.android	object	Android specific options
alert.web	object	Web specific options

The following table presents the iOS specific options that can be user in the alert.ios field:

Field	Type	Description
alert.ios.sound	string	The name of a sound file in the app bundle or in the `Library/Sounds` folder of the app’s data container. 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. The audio must be in one of the audio data formats that are compatible with system sounds; see UNNotificationSound / Prepare Sounds Resources for details.
alert.ios.badge	integer	The number to display as the badge of the app icon. If this property is absent, the badge is not changed. To remove the badge, set the value of this property to `0`.
alert.ios.titleLocKey	string	The key to a title string in the `Localizable.strings` file for the current localization. The key string can be formatted with `%@` and `%n$@` specifiers to take the variables specified in the `alert.ios.titleLocArgs` array. See Localized Formatted Strings for more information.
alert.ios.titleLocArgs	array of string	Variable string values to appear in place of the format specifiers in `alert.ios.titleLocKey`. See Localized Formatted Strings for more information.
alert.ios.subtitle	string	A second line of title.
alert.ios.subtitleLocKey		The key to a subtitle string in the `Localizable.strings` file for the current localization. The key string can be formatted with `%@` and `%n$@` specifiers to take the variables specified in the `alert.ios.subtitleLocArgs` array. See Localized Formatted Strings for more information.
alert.ios.subtitleLocArgs		Variable string values to appear in place of the format specifiers in `alert.ios.subtitleLocKey`. See Localized Formatted Strings for more information.
alert.ios.body	string	The text of the alert message. This field is just like `alert.text`, but presented with the iOS specific name for convenience.
alert.ios.locKey	string	A key to an alert-message string in a `Localizable.strings` file for the current localization (which is set by the user’s language preference). The key string can be formatted with `%@` and `%n$@` specifiers to take the variables specified in the `alert.ios.locArgs` array. See Localized Formatted Strings for more information.
alert.ios.locArgs	array of string	Variable string values to appear in place of the format specifiers in `alert.ios.locKey`. See Localized Formatted Strings for more information.
alert.ios.actionLocKey	string	If a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”. See Localized Formatted Strings for more information.
alert.ios.launchImage	string	The filename of an image file in the app bundle, with or without the filename extension. 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 app’s `Info.plist` file, or falls back to `Default.png`. This property was added in iOS 4.0.
alert.ios.category	string	Provide this key with a string value that represents the `identifier` property of the `UIMutableUserNotificationCategory` object you created to define custom actions. To learn more about using custom actions, see Registering Your Actionable Notification Types.
alert.ios.attachments	array of objects	A list of media attachments to add to the notification. iOS 10 only shows the first one but you may use the others in you have your own Notification Content Extension. Requires at least SDK v1.2.2.0.
alert.ios.attachments[].id	string	An optional identifier for use in your own Notification Content Extension if you have one.
alert.ios.attachments[].url	string	The URL to the media to download and attach to the notification. See the following documentation for supported file formats and associated file size limits. Prefer using HTTPS.
alert.ios.attachments[].type	string	The type of the file that `.url` points to. Necessary if the URL does not end with a proper file extension. Valid official iOS values are: `public.png`, `public.jpeg`, `com.compuserve.gif`, `com.microsoft.waveform-audio`, `public.aiff-audio`, `public.mp3`, `public.mpeg-4-audio`, `public.mpeg`, `public.mpeg-2-video`, `public.mpeg-4`, `public.avi`. Valid file-extension-like values are: `png`, `jpg`, `jpeg`, `gif`, `wav`, `wave`, `aiff`, `mp3`, `m4a`, `mp4a`, `mpg`, `mpeg`, `mp2`, `m2v`, `mp4`, `avi`. Valid mime-type-like values are: `image/png`, `image/x-png`, `image/jpeg`, `image/gif`, `audio/wav`, `audio/x-wav`, `audio/aiff`, `audio/x-aiff`, `audio/mpeg`, `audio/mp3`, `audio/mpeg3`, `audio/mp4`, `video/mpeg`, `video/x-mpeg1`, `video/mpeg2`, `video/x-mpeg2`, `video/mp4`, `video/mpeg4`, `video/avi`.
alert.ios.attachments[].options	object	Optional list of additional raw options to pass to the notification attachment constructor method.
alert.ios.contentAvailable	integer	Provide this key with a value of `1` to indicate that new content is available. Including this key and value means that when your app is launched in the background or resumed, `application:didReceiveRemoteNotification:fetchCompletionHandler:` is called. Note that WonderPush automatically detects when this should be set to `1`, like when adding a payload to the notification.
alert.ios.mutableContent	integer	Provide this key with a value of `1` to indicate that the Notification Service Extension can run and modify the notification. Necessary for media attachments. Note that WonderPush sets this to `1` by default in order to support media attachments, but you can override this if necessary.
alert.ios.threadId	string	Provide this key with a string value that represents the app-specific identifier for grouping notifications. If you provide a Notification Content app extension, you can use this value to group your notifications together.
alert.ios.targetContentId	string	The identifier of the window to bring forward.
alert.ios.foreground	object	Permits to customize some behavior if the notification is to be displayed while the application is foreground.
alert.ios.foreground.autoOpen	boolean	Whether to automatically do as if the user clicked the notification if received while in foreground.
alert.ios.foreground.autoDrop	boolean	Whether to automatically do as if the user swiped the notification if received while in foreground.
alert.ios.buttons	array of objects	A list of up to 3 buttons to add to the notification.
alert.ios.buttons[].label	string	The button label
alert.ios.buttons[].targetUrl	URL	The content to open when clicking on the button, as an alternative to clicking on the notification itself.
alert.ios.buttons[].actions	array of objects	A list of background options to perform when clicking on the button. See the list of available actions.

You can read more about those fields in the Apple documentation about The Remote Notification Payload.

If neither alert.ios.foreground.autoOpen nor alert.ios.foreground.autoDrop are set, the SDK presents the notification. On iOS 10, if you properly integrated the SDK v1.2.2.0 or later the OS itself will present the notification. On prior versions of iOS or if the your code does not call [WonderPush setupDelegateForUserNotificationCenter] on initialization, the SDK will present an alert with the notification title and text.

The following table presents the Android specific options that can be user in the alert.android field:

Field	Type	Description
alert.android.channel	string	The Android O notification channel to post the notification to. Prior to Android O, the WonderPush SDK can associate user preferences just about the same way. The notification uses the default channel configured in the SDK if no value is provided.
alert.android.type	string	One of: missing, or `null`: Default style, with expandable text. `none`: No style, the text will be shown on a single line. `bigText`: In the big text style, the expanded and collapsed state can show a different content. `bigPicture`: The big picture style can display a large picture below a line of text. * `inbox`: Displays multiple sentences when expanded, each on a single line.
alert.android.bigTitle	string or HTML Valid for: `bigText`, `bigPicture` and `inbox`.	An alternate title when the notification is expanded.
alert.android.bigText	string or HTML Valid for: `bigText`.	An alternate content when the notification is expanded.
alert.android.summaryText	string or HTML Valid for: `bigText`, `bigPicture` and `inbox`.	A last line of text to show under a horizontal ruler.
alert.android.bigLargeIcon	URL or resource name Valid for: `bigPicture`.	An alternate large icon to show then the notification is expanded. Prefer using HTTPS.
alert.android.bigPicture	URL Valid for: `bigPicture`.	A large picture to display when the notification is expanded. Prefer using HTTPS.
alert.android.lines	array of strings or HTML Valid for: `inbox`.	A list of single line sentences to show when the notification is expanded.
alert.android.html	boolean	Whether to treat every displayable string in this object as being HTML styled. Only simple HTML styling tags are supported by Android
alert.android.title	string or HTML	Set the first line of text in the platform notification template.
alert.android.text	string or HTML	Set the second line of text in the platform notification template.
alert.android.subText	string or HTML	This provides some additional information that is displayed in the notification.
alert.android.info	string or HTML	A small piece of additional information pertaining to this notification. The platform template will draw this on the last line of the notification, at the far right (to the right of a smallIcon if it has been placed there).
alert.android.ticker	string or HTML	Set the "ticker" text which is sent to accessibility services.
alert.android.priority	string	One of: `max` `high` `default` `low` * `min`
alert.android.persons	array of URIs	Add a person that is relevant to this notification. The system will also attempt to resolve `mailto:` and `tel:` schema URIs.
alert.android.category	string	One of the Notification category constants, like `message`, `promo` or `reminder`.
alert.android.color	string	One of the Color constants, or an `#RRGGBB` color code.
alert.android.group	string	Set this notification to be part of a group of notifications sharing the same key. Grouped notifications may display in a cluster or stack on devices which support such rendering.
alert.android.groupTargetUrl	string or `null`	By default, clicking on the unfolded group notification will use the `targetUrl` of the last received notification. You can override this using this field. You can also give `null` to prevent the unfolded group notification from being clickable.
alert.android.sortKey	string	Set a sort key that orders this notification among other notifications from the same package. This can be useful if an external sort was already applied and an app would like to preserve this. Notifications will be sorted lexicographically using this value, although providing different priorities in addition to providing sort key may cause this value to be ignored.
alert.android.localOnly	boolean	Set whether or not this notification should not bridge to other devices. Some notifications can be bridged to other devices for remote display. This hint can be set to recommend this notification not be bridged.
alert.android.number	integer	Set the large number at the right-hand side of the notification. This is equivalent to `alert.android.info`, although it might show the number in a different font size for readability.
alert.android.onlyAlertOnce	boolean	Set this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing.
alert.android.when	timestamp in milliseconds	Add a timestamp pertaining to the notification (usually the time the event occurred). For apps targeting N and above, this time is not shown anymore by default and must be opted into by using `alert.android.showWhen`.
alert.android.showWhen	boolean	Control whether the timestamp set with `alert.android.when` is shown in the content view. For apps targeting N and above, this defaults to false. For earlier apps, the default is true.
alert.android.usesChronometer	boolean	Show the when field as a stopwatch. Instead of presenting when as a timestamp, the notification will show an automatically updating display of the minutes and seconds since `alert.android.when`. Useful when showing an elapsed time (like an ongoing phone call). The counter can also be set to count down to `alert.android.when` when using `alert.android.chronometerCountDown`.
alert.android.chronometerCountDown	boolean	Sets the Chronometer to count down from `alert.android.when`, instead of counting up. This is only relevant if `alert.android.usesChronometer` has been set to true.
alert.android.timeoutAfter	duration in milliseconds	Specifies a duration in milliseconds after which this notification should be automatically closed. This is a built-in Android feature.
alert.android.visibility	string	One of: `private` (the default) `secret` * `public`
alert.android.lights	boolean or object	Set the desired color for the indicator LED on the device, as well as the blink duty cycle (specified in milliseconds). Not all devices will honor all (or even any) of these values. Use `false to deactivate`, `true` to user the default values, an object to override some values.
alert.android.lights.color	string	The LED color.
alert.android.lights.on	number of milliseconds	How long should the LED stay on.
alert.android.lights.off	number of milliseconds	How long should the LED stay off.
alert.android.vibrate	boolean or array of integers	Should the notification vibrate using the default pattern, or the provided one.
alert.android.sound	URL or resource identifier	Set the sound to play. It will be played using the default audio attributes for notifications. A notification that is noisy is more likely to be presented as a heads-up notification.
alert.android.ongoing	boolean	Set whether this is an "ongoing" notification. Ongoing notifications cannot be dismissed by the user.
alert.android.progress	boolean or 0 to 100 integer	Set the progress this notification represents. The platform template will represent this using a progress bar. Use `true` to set an undetermined state, or a number from 0 to 100 to set the corresponding percent completion to display.
alert.android.smallIcon	resource identifier	Set the small icon resource, which will be used to represent the notification in the status bar. The platform template for the expanded view will draw this icon in the left, unless a large icon has also been specified, in which case the small icon will be moved to the right-hand side.
alert.android.largeIcon	URL or resource identifier	Add a large icon to the notification content view. In the platform template, this image will be shown on the left of the notification view in place of the small icon (which will be placed in a small badge atop the large icon). Prefer using HTTPS.
alert.android.buttons	array of objects	A list of up to 3 buttons to add to the notification in the notification center.
alert.android.buttons[].label	string	The button label.
alert.android.buttons[].icon	resource identifier	The icon to display next to the button label.
alert.android.buttons[].targetUrl	URL	The content to open when clicking on the button, as an alternative to clicking on the notification itself.
alert.android.buttons[].actions	array of objects	A list of background options to perform when clicking on the button. See the list of available actions.
alert.android.allowSystemGeneratedContextualActions	boolean	Determines whether the platform can generate contextual actions for a notification. Android defaults this to true.
alert.android.badgeIconType	string	Sets which icon to display as a badge for this notification. This value might be ignored, for launchers that don't support badge icons. One of: `none`, the default `small` * `large`
alert.android.colorized	boolean	Set whether this notification should be colorized using `alert.android.color` for the background color. This should only be used for high priority ongoing tasks like navigation, an ongoing call, or other similarly high-priority events for the user. For most `alert.android.type` styles, the coloring will only be applied if the notification is for a foreground service notification.
alert.android.extras	object	Any extras to put on the system notification object. Android already puts some keys of its own. These extras can be retreived when listing active notifications in the system.
alert.android.foreground	object	Permits to override any of the above options if the notification is displayed while the application is foreground.
alert.android.foreground.priority	string	See `alert.android.priority`. Defaults to `high` in order to get the notification presented as heads-up by the system above your application.
alert.android.foreground.autoOpen	boolean	Whether to automatically do as if the user clicked the notification if received while in foreground.
alert.android.foreground.autoDrop	boolean	Whether to automatically do as if the user swiped the notification if received while in foreground.

HTML styling support is limited to about the following tags:

<br>
<h1> <h2> <h3> <h4> <h5> <h6>
<b> <i> <u> <big> <small> <strong> <em> <strike> <sub> <sup>
<a href="http://www.example.com">Link</a>
<div align="left|center|right">
<p dir="ltr|rtl">
<font size="24" color="red" face="Monospace"> <tt>
<blockquote> <cite> <dfn>

The following table presents the Web specific options that can be user in the alert.web field:

Field	Type	Description
alert.web.dir	string	`auto`, `ltr` or `rtl`. How the text should be aligned. Helps supporting right-to-left languages.
alert.web.lang	string	The notification’s language specifies the primary language for the notification’s title, body and the title of each of its buttons. Its value is a string. The empty string indicates that the primary language is unknown. Any other string must be interpreted as a language tag. Validity or well-formedness are not enforced.
alert.web.body	string	Text text to display in the notification. This is the Web specific name of the `alert.text` field.
alert.web.icon	URL	The HTTPS URL of the icon to display next to the notification. Must use HTTPS.
alert.web.badge	URL	A small icon displayed when there is not enough space to display the notification itself. It may also be displayed inside the notification with less visual priority than the icon itself. Must use HTTPS.
alert.web.image	URL	The HTTPS URL of the big image to display below to the notification. Must use HTTPS.
alert.web.sound	URL	The sound to play.
alert.web.vibrate	array of integer	The vibration pattern.
alert.web.timestamp	timestamp in milliseconds	Indicates the time of the event for which the notification is shown.
alert.web.renotify	boolean	Indicates if the user should get a visual notification after a notification has been updated.
alert.web.silent	boolean	Indicates that no sounds or vibrations should be made.
alert.web.noscreen	boolean	Indicates that the screen of the device should not be enabled.
alert.web.requireInteraction	boolean	Indicates that on devices with a sufficiently large screen, the notification should remain readily available until the user activates or dismisses the notification. WonderPush sets this by default in order to prevent some browsers from automatically dismissing the notification after a few seconds.
alert.web.sticky	boolean	Indicates that the end user should not be able to easily clear the notification.
alert.web.buttons	array of objects	A list of buttons to add to the notification. Note: The Notification API specification uses the name `actions` for that.
alert.web.buttons[].label	string	The notification button label.
alert.web.buttons[].action	string	The notification button identifier. An identifier is automatically generated if not specified.
alert.web.buttons[].icon	URL	A small button icon to display next to the button label.
alert.web.buttons[].targetUrl	URL	The URL of the page to show when clicking on that button, as an alternative to clicking on the notification itself.
alert.web.buttons[].actions	array of objects	The optional list of actions that the button should perform. See the list of available actions.

For more information, you can read the Notification API living standard, but beware, it's a bit dry.

Push options

Field	Type	Description
push.payload	object	Custom payload to merge with the notification payload itself. On the contrary to the `custom` argument, this enabled you to control the whole notification payload. Be careful when writing into the `_wp` field (reserved for the WonderPush SDK) or `aps` field (reserved for Apple notifications).
push.custom	object	A key value mapping of custom data to give in the notification payload under the `custom` key.
push.expirationDate	timestamp in milliseconds, or a string date using format `YYYY-MM-DDTHH:MM:SS.MMM+HH:MM`	The date after which the notification should be dropped if not already delivered to a user's device. Use 0 to try only once.
push.expirationTime	duration in milliseconds, or something like "10 minutes"	The duration after which the notification should be dropped if not already delivered to a user's device. Use 0 to try only once.
push.priority	string	`normal` or `high`
push.receiveActions	array of objects	An optional list of background actions to perform when the SDK receives the notification. See the list of available actions.
push.android	object	You can override any of the above keys for Android devices. The following subkeys allow you to further control some Android-specific options.
push.android.delayWhenIdle	boolean	Indicates whether the message should not be sent until the device becomes active.
push.android.collapseKey	string	This parameter defines a group of messages that can be collapsed, so that only the last message gets sent when notifications can be delivered to a device anew.
push.android.restrictedPackageName	string	This parameter specifies the package name of the application where the registration tokens must match in order to receive the message.
push.ios	object	You can override any of the above keys for iOS devices. The following subkeys allow you to further control some Android-specific options.
push.ios.collapseId	string	Multiple notifications with the same collapse identifier are displayed to the user as a single notification on iOS 10+. The value of this key must not exceed 64 bytes. Defaults to the value of `alert.ios.tag` or `alert.tag`, or to the used `campaignId`.
push.web	object	You can override any of the above keys for Web devices.
push.web.topic	string	Collapsing multiple push messages with the same topic server-side, that is before they are delivered. 32 characters maximum, alphanumeric, dash or underscore (`[a-zA-Z0-9_-]`).

Available `actions` for notification clicks and buttons

Each action is composed of a type field, and any additional fields required by the chosen type.
We present below one table per supported action type.

Field	Valid for	Type	Description
.type	All	string	`"close"`: Simply closes the in-app dialog box. If not given explicitly, this action is always added implicitly. `"trackEvent"`: Tracks a user event. This has the same effect as if you had called the `trackEvent()` method of the SDK manually, only you control it dynamically using push notifications. `"updateInstallation"`: Modify the installation custom properties. This has the same effect as if you had called the `putInstallationCustomProperties()` method of the SDK manually, only you control it dynamically using push notifications. `"addProperty"`: Add one or more values to the existing values of a given property, instead of replacing the whole list. This has the same effect as if you had called the `addProperty()` method of the SDK manually, only you control it dynamically using push notifications. `"removeProperty"`: Add one or more values to the existing values of a given property, instead of replacing the whole list. This has the same effect as if you had called the `removeProperty()` method of the SDK manually, only you control it dynamically using push notifications. `"addTag"`: Add one or more tag. This has the same effect as if you had called the `addTag()` method of the SDK manually, only you control it dynamically using push notifications. `"removeTag"`: Remove one or more tag. This has the same effect as if you had called the `removeTag()` method of the SDK manually, only you control it dynamically using push notifications. `"removeAllTags"`: Remove all tags. This has the same effect as if you had called the `removeAllTags()` method of the SDK manually, only you control it dynamically using push notifications. `"method"`: Automatically triggers a registered callback. Take a look at the demo applications source code on GitHub to see how you can listen to those callbacks. `"link"`: Opens the given URL in the browser, or using any application that is bond with it in the system. `"rating"`: Opens the application store of device platform, on the page corresponding to your application. `"closeNotifications"`: Selectively closes visible notifications. `"subscribeToNotifications"`: Subscribes the user to push notifications, possibly prompting her for permission. `"unsubscribeFromNotifications"`: Unsubscribes the user from push notifications.
.event	`trackEvent`	object	The event that should be tracked.
.event.type	`trackEvent`	string	The event type, like the first argument of the `trackEvent()` method of the SDK.
.event.custom	`trackEvent`	object	Optional custom data to attach to the event payload. See the accepted format.
.installation	`updateInstallation` `addProperty` `removeProperty`	object	New data to merge to the installation. Only the `custom` field is currently allowed. Any new field will be created, and any existing field will be overwritten. See the accepted format of this field.
.custom (deprecated)	`updateInstallation` `addProperty` `removeProperty`	object	Use `"installation": {"custom":…}` instead.
.tags	`addTag` `removeTag`	array of strings	The list of tags to add or remove.
.method	`method`	string	The callback method name.
.methodArgs	`method`	string	The callback argument value.
.url	`link`	string	The URL or deeplink to open.
.tag	`closeNotifications`	string or `null`	Selects notifications with the given tag (or without tag if `null` is given) to be closed. Note that Android also supports these platform-specific fields: `.channel` (string or `null`): Matches the notification channel. `null` matches the default channel. See `alert.android.channel`. `.group` (string or `null`): Matches the notification group key. `null` matches ungrouped notifications. See `alert.android.group`. `.category` (string or `null`): Matches the notification category. See `alert.android.category`. `.sortKey` (string or `null`): Matches the notification sort key. See `alert.android.sortKey`. Note that iOS also supports these platform-specific fields: `.threadId` (string or `null`): Matches the notification thread id. See `alert.ios.threadId`. `.category` (string or `null`): Matches the notification category. See `alert.ios.category`. `.targetContentId` (string or `null`): Matches the notification target content id. See `alert.ios.targetContentId`.

Alert

Push options

Available actions for notification clicks and buttons

Available `actions` for notification clicks and buttons