Reference of the Notification object used to specify content when sending notifications via the REST API
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!"}}
Localization
| Field | Type | Description |
|---|---|---|
| locale | string | The locale in the form xx or xx_XX.When set, only subscribers with a matching locale will be eligible. When not set, the notification can be used as a fallback for subscribers without a matching locale. |
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/broadcastLets application code decide what screen to launch. - wonderpush://notificationOpen/noopPerforms 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:maxhighdefaultlow- 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 defaultsmall- 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
actions for notification clicks and buttonsEach 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 | updateInstallationaddPropertyremoveProperty | 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) | updateInstallationaddPropertyremoveProperty | object | Use "installation": {"custom":…} instead. |
| .tags | addTagremoveTag | 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. |