Managing the notification tray

Use this guide to understand and control what happens to your push notifications after they display on a device: what clicking and dismissing do, when Android redisplays notifications, how badges stay in sync, and which SDK tools let you manage the tray from your app code. This page covers mobile push (Android and iOS). For web push behavior, see Web push notification behavior.

---

​

Notification lifecycle in the tray

Every OneSignal notification displayed on a device is tracked by the SDK. What happens next determines whether it can ever reappear:

---

​

Click and dismiss behavior

Clicking a notification opens your app (or the notification’s launch URL), removes the notification from the tray, and fires the addClickListener() callback with the notification payload and the clicked action button ID. If the clicked notification belongs to a group, the SDK updates or removes the group summary. Clicked notifications are never restored. Dismissing a notification (swiping it away or tapping Clear all in the tray) marks it as dismissed and updates the badge count and any group summary. Dismissed notifications are never restored. The SDK does not provide a dismiss listener; dismissal is tracked internally. Notifications displayed while your app is in the foreground first pass through the foreground lifecycle listener, where you can prevent display.

---

​

Restored notifications (Android)

Android can force-remove notifications without user action: on device reboot, app update, and force-quit (including aggressive battery managers on some devices). The Android SDK automatically redisplays (restores) affected notifications the next time the app cold starts, so delivered messages the user never saw or dismissed are not lost. Restored notifications reappear silently on the low-importance Restored category. Only notifications that were not clicked or dismissed, are within their TTL, and were received in the last 7 days are restored, up to 49 notifications. Full eligibility rules and controls are in Restored notifications (Android). To reduce restores, use a shorter ttl when sending or clear consumed notifications with the SDK methods below. iOS has no restore behavior.

---

​

Badge behavior

On iOS, badges are set by the notification payload (ios_badgeType and ios_badgeCount) and require an App Group so the service extension can update counts accurately. By default, the SDK clears the badge when the app opens. On Android, the app icon badge reflects the number of active OneSignal notifications in the tray and is managed through notification categories. The SDK updates the count automatically when notifications are displayed, dismissed, clicked, or cleared, and resets it to 0 when you call clearAllNotifications(). Setup, per-platform options, and troubleshooting are covered in Badges.

---

​

Clearing notifications programmatically

Clear notifications when their content has been consumed in your app, not on app lifecycle events. The common patterns:

• Content-consumed sync: the user opens the screen the notifications point to (an inbox, message center, or activity feed), so the notifications are now redundant. Clear all of them, or use the targeted methods if only some content was consumed.
• Logout: clear everything so the previous user’s notifications are not visible to the next user.

Avoid clearing on every app launch or foreground to “keep the tray clean.” Notifications in the tray drive re-engagement, and clearing them removes that entry point. If you are managing notification buildup, use collapse_id when sending to replace notifications instead of stacking them, or a shorter TTL to expire undelivered ones.

​

clearAllNotifications()

Removes your app’s notifications from the tray and resets the badge count to 0. On Android, this removes only OneSignal-created notifications and marks them as dismissed so they are not restored. On iOS, this removes all of your app’s delivered notifications, including local notifications and pushes from other providers. See the full method reference.

​

removeNotification() and removeGroupedNotifications() (Android)

Remove a single notification by its Android notification ID, or all notifications in a group by its group key. Removed notifications are marked as dismissed and are not restored. Use these when only part of the tray’s content was consumed, such as one conversation out of several. See the method reference.

---

​

Customizing notifications with service extensions

Service extensions run before a notification displays, letting you modify its appearance, receive background data, or prevent display entirely:

• On Android, implement INotificationServiceExtension and use setExtender() to change NotificationCompat options, or call event.preventDefault() to suppress display.
• On iOS, use a UNNotificationServiceExtension (the OneSignalNotificationServiceExtension created during setup) for rich media, badge increments, and confirmed delivery.

---

​

FAQ

​

Why do old notifications reappear when the app opens on Android?

The Android SDK restores notifications that were force-removed from the tray, such as after a device reboot, app update, or force-quit. Notifications the user dismissed or clicked are not restored. See Restored notifications (Android) for eligibility rules and controls.

​

Does TTL remove a notification from the tray after it expires?

No. TTL controls how long an undelivered message waits for an offline device, and on Android it also bounds which notifications can be restored. It never removes a notification already displayed in the tray. To remove displayed notifications, use the clearing methods.

​

Can I clear the badge without clearing the tray?

Yes on iOS: the badge clears automatically when the app opens (unless disabled), leaving tray contents in place. On Android, the badge reflects active notifications in the tray, so it cannot be set independently of them. See Badges.

​

Is there a listener for when a user dismisses a notification?

No. The SDK tracks dismissal internally to prevent restoring dismissed notifications, but does not expose a dismiss event. The click listener covers clicks only.

---