Data & Background Notifications
How to send data/background/silent notifications. VoIP notifications using OneSignal. Works with iOS, Android and derivatives like Amazon.
Background/Data notifications are "silent" meaning they do not display any visible message and do not play a sound when received by your app. They are designed to keep your app's data up-to-date by providing a way to "wake up" the app to refresh the data in the background.
Limitations
-
The OneSignal SDK is set up to only send data notifications to subscribed users. If you want to target unsubscribed users with data notifications, you will need to follow this workaround.
-
If you force close/stop/quit the app, it cannot receive background/data notifications
- iOS Apps are force closed when you swipe them away.
- Android Apps can be force stopped in the settings, but some device manufacturers force quit the app automatically when swiping them away. More details.
-
Limited Support for Non-Native SDKs
- If you are using a non-native SDK like Unity, React Native, Cordova, or Flutter, you must use native Java/Kotlin or Swift/Objective-C to implement Data Push Notifications.
- iOS will need to implement Apple's
application:didReceiveRemoteNotification:fetchCompletionHandler:
method. - For Android, you will need to implement the Android Notification Service Extension.
iOS Background Notification Setup
Before getting started, we highly recommend getting familiar with Apple's Pushing Background Updates to Your App and Apple's Guide on Creating Notification Payloads.
Enable Remote Notifications Capability
This should already be done if you followed our Mobile SDK Setup guides.
Background Notification Payload Data
To prevent the notification from visually displaying to users, you must:
- Remove the OneSignal
contents
property from your Create notification requests. If you are sending from the dashboard, do not include a "Message". - Add the OneSignal
content_available
property set totrue
from your Create notification requests. If you are sending from the dashboard, this is under Platform Settings > Send to Apple iOS > "Content available" checkbox. - To add custom data, use the OneSignal
data
property in your Create notification requests. If sending from the dashboard, this is under Advanced Settings > Additional Data.
Handle Notification Data
Process data within the Native iOS API within the AppDelegate
application(_:didReceiveRemoteNotification:fetchCompletionHandler:)
method.
iOS Force Close Limitations
Apple does not allow the processing of background data if the app has been swiped away.
If the app has been swiped away, you will need to add
contents
(a message) to the push (cannot be a background message) and handle the data within the UNNotificationServiceExtension.didReceive method.There is no way to process a background notification when the app has been force quit.
Android Data Notification Setup
Data notifications are handled within the NotificationExtenderService - This can be set up to receive data notifications when your app is not running, or to override how notifications are shown in the notification shade.
Background/Data Notifications with the REST API
OneSignal will automatically send the notification as a data notification under the following conditions:
content_available
:true
alert
is omittedbadge
is omittedsound
is omittedcategory
is omittedthread_id
is omittedsubtitle
is omittedcontents
is omittedheadings
is omitted
Sending VoIP Notifications
OneSignal supports VoIP notifications for iOS. Our SDKs do not support registration for a VoIP token at this time.
See our VoIP Notifications Setup Guide to get started.
FAQ
Can silent data/background notifications help detect unsubscribes or uninstall events?
If the app has been uninstalled or force quit/stopped/closed then silent notifications cannot be used to detect the unsubscribe events because the app cannot accept or send API requests which include the receiving of notifications and sending token validation updates.
Do Confirmed Deliveries work with Silent Push Notifications?
On iOS, unfortunately this is not possible right now.
While we use the NotificationServiceExtension to send the confirmed delivery, iOS will not trigger the NSE if you do not add a message to the body of the push. It is also not possible to work around this by setting a body then making it nil or blank in the NSE. If you try to do that iOS puts back the body and displays it. You can't prevent a notification from showing with the NSE either.
Updated 6 months ago