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 these types of 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:

1. Remove the OneSignal contents property from your Create notification requests. If you are sending from the dashboard, do not include a "Message".
2. Add the OneSignal content_available property set to true from your Create notification requests. If you are sending from the dashboard, this is under Platform Settings > Send to Apple iOS > "Content available" checkbox.
3. 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 omitted
• badge is omitted
• sound is omitted
• category is omitted
• thread_id is omitted
• subtitle is omitted
• contents is omitted
• headings 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.