When sending Push Notifications from OneSignal, we gather these requests and send them to Google and/or Apple whom distribute them to your users. These notifications are "held" by their servers until the device becomes online.

OneSignal uses a Custom Payload on our Mobile SDK to differentiate it from other push notifications.

Below are common Advanced Settings for Push Notifications:

Notification Collapsing

If sending frequent notifications, especially on something that is changing like "breaking news", you may want to consider notification collapsing. Collapsing is replacing older or irrelevant notifications with newer ones; solving the problem of notifications piling up and overwhelming users whenever they are not actively checking their new notifications.

Mobile Notification Collapsing - Collapse ID

Collapsing works by only showing the latest notification of a given type, 'collapsing' all the other unread notifications of the same type that come before it. For instance, if you have a weather app and want to update users on the latest weather, you probably want to replace those notifications with whatever is the latest one.

The way notification collapsing works is by adding a collapse_id to particular types of notifications you are sending that you want collapsed together (E.g. the id is weather_update or breaking news). Then, every time you wish to have a future notification override previous ones, you add the same collapse_id to it. If your app sends three notifications, the following would happen:

Sent 1:41pm: "A storm looks like it's approaching. Better grab an umbrella!"
Sent 2:20pm: "The storm in your area seems to be clearing up. Expect sunshine soon."
Sent 2:44pm: "The storm has moved north and the sun will shine the rest of today!"

If a user does not open their device until 4pm, they would only see the third notification. If the user opened their device at 2pm and 4pm, they would see the first notification, and then at 4pm see the third notification.

collapse_id does not work with Data Notifications on iOS, the notification must show data in this case to remove it from view.

Web Notification Collapsing - Web Push Topic

Notifications on our Web SDK are automatically collapsed. This is where the old notification is replaced with the new notification if the user has not clicked it.

For example, Notification 1 is sent and received, the user does not interact with it. Notification 2 is sent and received. Notification 1 is removed and replaced with Notification 2.

You can use the "Web Push Topic" to display more than 1 web push notification at a time on web.

Web Push Topic is any string value you can set when Sending Push Messages from the dashboard or web_push_topic API parameter.

If you do not specify the web_push_topic , each notification will be replaced by a newer notification. If you do specify web_push_topic, you can choose which notifications will be replaced and which notifications will stack.

For example:

Notification 1 sent with web_push_topic: "breaking-news"
Notification 2 sent with web_push_topic: "breaking-news"

Notification 2 will replace Notification 1.

Notification 3 sent with web_push_topic: "sports"
Notification 4 sent with web_push_topic: "weather"

Notification 2, 3 and 4 will all either be left on the screen or docked in the Notification Center.

On Chrome, a maximum of 3 notifications are displayed at any time, even if the other notifications are not related to your site or from OneSignal. This means you can only show 3 categories of notifications to your user, not counting for other notifications that might be displayed at that time.

On Firefox on Windows, many more notifications can be shown at a time (6+).

On Firefox on Mac, and Safari on Mac, only one notification can be shown at a time, even if the other notifications are not related to your site or from OneSignal. Notifications also disappear quickly within 5 seconds and this time is not customizable.

On Chrome/Firefox on Android, multiple notifications can be shown at a time.

Removing Notifications Without Replacing Them

In some cases, you may want notifications to "self-destruct" or be removed from the device without replacing them with others. There are a couple options for this:

Android: Within the Notification Service Extension, use the native Android API setTimeoutAfter method to remove the notification after a certain amount of time.

iOS: Apple provides the native removeDeliveredNotifications(withIdentifiers:) method and getDeliveredNotifications(completionHandler:) method to target the expired notifications and remove them.

Android & iOS: You can send Data & Background Notifications which do not display any content to the user but can remove notifications.

Android: run code in Service Extensions to remove the notification.
iOS: the notifications in the Notification Center are tied to the Badge Count. As long as you have at least 1 badge set, you can send a notification setting the badge count to 0 to remove all notifications for your app.

Web: There is not a way to remove web push notifications without collapsing.

Notification Grouping

See how each platform works:

Notification Priority

Android Notifications can be assigned normal or high priority.

For Android 7.1 and lower, priority handles both "Delivery Priority" and "Display Priority"

For Android 8+, priority handles "Delivery Priority" and Android Notification Categories handles the "Display Priority"

Normal Priority: If the app is in the foreground, normal priority notifications are delivered immediately (except in Doze mode). Choose this setting for things such as new message notifications, syncing your UI, and syncing data in the background.

High Priority: These notifications are delivered immediately, though fall subject to the standby bucket policy on the device.

Set a high priority 10 if you need it to go through any doze mode / other power saving modes. But only use priority 10 when you really need to as there is a daily limit where it might fallback to normal priority.

Time To Live

This is the number of seconds a notification will be held by the Google (FCM) and Apple (APNs) servers before being delivered to your users if their device is not online by the time of sending.

By default, notifications will be held by the Google and Apple servers for 3 days. This means if the device does not come online within 3 days, the message will not be sent to that device.

For example, if you set TTL to 3 hours (10800 seconds) and my device does not have internet connection for 3 hours and 1 second or longer, I will not get the notification.

TTL does not remove the notification from the device once it has been received. You can use the collapse_id to achieve this. See below Notification Collapsing.

For more on setting the TTL parameter, please see Sending Push Messages

iOS Limitation - Apple will only store the most recent notification sent to a device on the APNs servers. If you send multiple notifications to an iOS device while it is offline, only the most recent notification will show when the device comes back online. More information on this in Apple's APNs Overview.

OneSignal Custom Push Payload

Each OneSignal SDK has a Notification Event Observer that gets triggered when a push is clicked or received.

Details on the OneSignal Notification Object and OneSignal Notification Payload.

On Android, our notification payload contains a “custom” key with a nested “i” value. If the notification payload received does not contain this, our SDK will not process the notification.

On iOS, we also have the same “custom” key with nested “i” value, however because Apple has a standard payload it will show all notification sent to the device. So if you send a push from your old platform to a device, do not send the same notification from OneSignal or the user will get it twice.

For iOS Click Handlers, depending on how you handle notification opens you might have to add a check for "custom": { "i": ""} as well. Or if you have your own format, we recommend checking for yours instead.

Adding Notification Data to iOS Root Payload

If you are needing to customize iOS payload, you can set your OneSignal app to include this custom data in the payload using our Update an app method and set additional_data_is_root_payload equal to true

Then any push you send with the data or Additional Data from the dashboard will be available in the APNS payload. For example:

... OneSignal Notification Data
"data": {
   "your-custom-data": "1"
} 

will result int he following sent to the device:

{
    "aps" : {
        "alert" : {
            "title" : "Notification Title",
            "body" : "Notification Body",
        }
    },
    "your-custom-data": "1"
}

Resulting in any additional code checking and handling this your-custom-data key at this location to work.

Doze Mode

Android devices have a doze mode, where messages will be delayed until the device is out of doze mode. High priority messages are delivered but will nevertheless fall subject to the standby bucket policy on the device.

App Standby Buckets

Devices running Android P and newer implement app standby buckets which may lead to notifications being delayed.

The following values may change. See the Android docs for most updated values

Setting	"Jobs" = Normal	"Alarms" = High
Active	No restriction	No restriction
Working set:	Deferred up to 2 hours	Deferred up to 6 mins
Frequent:	Deferred up to 8 hours	Deferred up to 30 mins
Rare:	Deferred up to 24 hours	Deferred up to 2 hours

Notifications when app is closed

iOS devices will always receive notifications. They may be delayed, however, if the app is in Low Power Mode.

Android

A normal close such as swiping your app away is a normal close and won't be an issue on most devices. However, force-closing it through the app settings, task killer, or through Android Studio would result in most Intents (including pushes) preventing services from starting.

Also some Xiaomi and Huawei devices will put your app in a force-closed state after swiping it away or after some time. See the following documentation for more details on this and the logcat message to confirm this.