Data & Background Notifications

Background/Data notifications are "silent" meaning they do not display any message or 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.

🚧
Background/Data Notification Limitations
If you force close the app, it cannot receive background/data notifications.

iOS Apps are force closed when you swipe them away.

Android Apps can be force quit in the settings, but some device manufacturers force quit the app automatically when swiping them away. More details.

Limitations of Non-native SDKs

🚧
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 a special delegate. You can learn more at the bottom of Handling Remote Notifications.
For Android, you will need to implement the NotificationExtenderService.

Setup and Send Silent Notifications

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.

Setting up and sending background notifications in iOS requires 3 components:

1. Notification Service Extension (NSE)

You must have the Notification Service Extension setup in your app. See Step 1 of our iOS Native SDK setup guide to add one to your Xcode project if you have not done so already.

2. Notification Payload Data

You must not send a message (no contents) and you must send content_available to wake the app if it is running in the background.

To add custom data, use the Additional Data Field in the OneSignal Dashboard or with the API data parameter.

3. Handle Notification Data

Native iOS Apps: Process the data within the addForegroundLifecycleListener method while the app is running in the foreground or background.

Non-Native iOS Apps: Process data within the Native iOS API within the AppDelegate application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.

🚧
iOS Force Quit 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

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.

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 notification parameter 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

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.