Data & background notifications

​

Limitations

• Apps cannot receive silent pushes if:
  • iOS: The app has been closed by the user, such as swiping it away from the app switcher. (See Apple support).
  • Android: The app has been force-quit via device settings or automatically by some manufacturers when swiped away. (Android force-stop behavior).
• Delivery is not guaranteed:
  • Both Apple and Google treat silent notifications as best-effort. iOS may delay or drop delivery under Low Power Mode, Background App Refresh off, or if the app was closed by the user. Android may throttle or batch delivery under Doze or OEM power-saving rules.
  • Apple’s stated ceiling is two or three background notifications per hour: “The number of background notifications allowed by the system depends on current conditions, but don’t try to send more than two or three per hour.” See Pushing background updates to your app. Sending more does not raise the ceiling, it just gets more of them dropped.
  • iOS throttles against an energy and data budget for the whole device, so silent pushes to other apps consume the same budget, and the budget resets about once a day. Apple disables this throttle when you run your app from Xcode, which is why silent pushes look far more reliable in testing than in production. See Technical Note TN2265.
  • Because of this, silent notifications should never be used for critical updates.
• Background execution is time-boxed: iOS gives your app about 30 seconds to finish its work and call the completion handler. Start long transfers with a background session rather than trying to complete them inline.
• Subscribed users only: OneSignal only sends data notifications to subscribed Subscriptions.
• Limited support for cross-platform SDKs:
  • Silent notifications must be handled in native code (Java/Kotlin for Android, Swift/Obj-C for iOS). Wrapper SDKs such as React Native and Flutter have no cross-platform handler for them.
  • iOS requires implementation of application:didReceiveRemoteNotification:fetchCompletionHandler:.
  • Android requires a notification service extension.

​

Sending silent notifications from OneSignal

​

Example API payload

curl -X POST https://api.onesignal.com/notifications \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "external_id": ["user-123"] },
    "target_channel": "push",
    "content_available": true,
    "priority": 5,
    "data": {
      "action": "sync_data",
      "version": "2"
    }
  }'

​

Platform-specific setup

​

iOS background notification setup

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    guard let customData = userInfo["custom"] as? [String: Any],
          let additionalData = customData["a"] as? [String: Any],
          let action = additionalData["action"] as? String else {
        completionHandler(.noData)
        return
    }

    // iOS allows roughly 30 seconds of work. Always call the completion handler,
    // including on the failure path, or iOS throttles future background pushes.
    switch action {
    case "sync_data":
        syncData { didChange in
            completionHandler(didChange ? .newData : .noData)
        }
    default:
        completionHandler(.noData)
    }
}

• Pushing background updates to your app
• Generating a remote notification

​

Android data notification setup

@Keep
class NotificationServiceExtension : INotificationServiceExtension {
    override fun onNotificationReceived(event: INotificationReceivedEvent) {
        val action = event.notification.additionalData?.optString("action", "") ?: ""

        if (action == "sync_data") {
            // A silent push has no content to display, so there is nothing to
            // prevent or show. Hand the work to WorkManager to survive Doze.
            scheduleSync(event.context)
        }
    }
}

@Keep
public class NotificationServiceExtension implements INotificationServiceExtension {

    @Override
    public void onNotificationReceived(INotificationReceivedEvent event) {
        JSONObject additionalData = event.getNotification().getAdditionalData();
        String action = additionalData != null ? additionalData.optString("action", "") : "";

        if (action.equals("sync_data")) {
            // A silent push has no content to display, so there is nothing to
            // prevent or show. Hand the work to WorkManager to survive Doze.
            scheduleSync(event.getContext());
        }
    }
}

• FCM data messages
• Optimize for Doze and App Standby

​

Huawei (HMS) data notification setup

• data: HMS delivers the payload to the device and the OneSignal SDK processes it client-side. This is the type you need for silent notifications on Huawei, and it’s also what the SDK uses to render visible full-featured notifications (images, buttons, confirmed delivery).
• message: HMS Core handles the notification server-side and displays a title and body only. Use data if you need silent delivery or background processing.

​

Sending VoIP notifications

​

FAQ

​

What priority should I use for silent notifications?

​

Do confirmed deliveries work with silent notifications?

​

Can silent notifications be used to detect uninstalls or unsubscribes?

• Send visible notifications (with content) to all your users at least once a month.
• Optionally send silent notifications as a supplemental check.

​

Can I use silent notifications to measure how many users are reachable?

​

Related pages