OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Confirmed Deliveries

Tracking received rates on notifications.

Confirmed Deliveries provides near-perfect click-through rate numbers and gives app developers a new peace of mind when getting a confirmation that their notifications have successfully delivered.

Every device that receives a notification sent through our platform will now acknowledge successful receipt back to OneSignal, data that is then available to all paying customers. In the Message Report for a notification, look for the Confirmed metric.

How do Confirmed Deliveries work?

To understand Confirmed Delivery, you must first understand what goes into delivering a notification to a device. In general, push providers must go through Apple and Google in order to deliver notifications. This means that there are multiple "hops" between OneSignal servers and the intended device.

Without device-level confirmation of notification delivery, OneSignal can only confirm the successful delivery to Apple Push Notification service and Firebase Cloud Messaging servers. However, our new Confirmed Deliveries feature now takes the form of an extra network request, from the device back to OneSignal servers acknowledging the notification:

When the Android App receives the push, it sends a confirmation to our servers letting us know the app itself has received the push. On iOS Apps, you must have the iOS Notification Service Extension setup for the confirmed delivery to be counted. Also make sure you are using a version of our SDK that supports this feature, see below Supported SDKs Table to make sure you have the minimum version or higher.

Why are Confirmed Deliveries important?

Confirmed Deliveries provide a true understanding of what is happening with your messages and help you monitor the health of your messaging pipeline and use metrics to better debug your implementation.

Click-Through Rate

Without Confirmed Deliveries, click-through rates are calculated by dividing the number of confirmed notification opens by the total number of subscriber devices targeted:

Without Confirmed Deliveries

However, "phantom subscribers" will result in less accurate CTR over time. These devices are ones that have never unsubscribed (e.g. by deleting your app), but are no longer used or are powered off.

For example, say someone who just upgraded to a new smartphone throws their old device in a drawer and never touches it again. Despite permanent inactivity, this device is technically still subscribed to your app. When calculated this way, CTRs become gradually less accurate due to these "phantom subscribers." This can be seen in the graph below:

This can be visualized in the graph below:

This model assumes users upgrade their phones every 24 months and a 10% "true" CTR (CTR only of ACTIVE devices). You can see that on the 24th month, the click through rate was half of the initial percentage since there are twice as many subscribed devices.

A better way to calculate CTR is to divide the number of devices that received a notification by the number of devices that clicked a notification:

With Confirmed Deliveries

Up until now, OneSignal didn't have a way to calculate how many devices actually received the notification. With Confirmed Deliveries, you will now be equipped with the power of near-perfect delivery statistics.

Why isn't this offered by most push providers?

To confirm device-level delivery of a notification, push-providers must process an extra inbound request for each push. This leads to a large burst in traffic to their servers, which requires heavy infrastructure. Processing inbound requests requires more than simply sending requests. When OneSignal's infrastructure sends out pushes at a sustained speed of one million pushes per second, it must then be able to handle over one million incoming confirmed deliveries at the same rate.

Supported SDKs

Make sure you have the minimum SDK version or higher installed. We recommend using the latest version of the OneSignal SDK.

SDK

Minimum SDK Version

Details

Android Native SDK

3.12.0

Supported

iOS Native SDK

2.12.2

Supported

React Native SDK

3.6.0

Supported

Unity SDK

2.11.0

Supported

Cordova/Ionic/PhoneGap SDK

2.8.0

Supported

Xamarin SDK

3.7.0

Supported

Flutter SDK

2.3.1

Supported

Web Push SDK

Coming Soon

Coming Soon


FAQ

Why does OneSignal provide this functionality?

We know that customer communication is a critical part of your infrastructure. It is important to us that our customers are successful and empowered with these core insights to make the best possible decisions with and get the most out of their messages.

How can I increase Confirmed Deliveries?

Correctly tracking Confirmed Deliveries requires devices to have the minimum version of the OneSignal SDK that supports this feature and setup the OneSignal SDK according to our Setup Guide. Using our API only to add devices or omitting steps from our setup will cause Confirmed Deliveries to be unaccounted for that platform.

Confirmed Deliveries cannot be triggered if a device is turned off. If a device is offline when the push is sent, it has 3 days default time to come back online to get the push. You can increase or decrease this time with the Time To Live parameter.

Also, a Confirmed Delivery may be missed if the device has unstable network connection at the time of receiving the push. The push may get received and clicked, generating a click response, but the network may not have been strong enough to send the received event.

Other possible reasons for inaccurate Confirmed Deliveries:

Missing or Incorrect iOS Notification Service Extension Implementation

The iOS Notification Service Extension and iOS SDK App Groups setup must be included in your iOS mobile app for Confirmed Deliveries to be counted. If you send a test message to your iOS mobile app and the Confirmed Delivery is not counted, please update the OneSignal SDK and check the Mobile Setup Guide.

Android Devices Force Quitting the App

Some android device manufacturers put apps into a "force quit state" when you swipe the app away which causes the device to not get notifications for your app when it is not running. Unfortunately this is a manufacturer issue that affects all push providers.

We have a list of common devices and fixes for this in our Notification Not Shown Guide. We also wrote a blog post about this and many 3rd party sites discuss this as well, like: https://dontkillmyapp.com/

To try educating your users about this, you could setup In-App Messages to target users on Android and make sure they have battery optimizations for your app turned off or they are setting keeping your app running when swiped away.

Inactive Devices

As described above in the section Why Are Confirmed Deliveries Important, users do not normally unsubscribe from all their apps or websites when they get new devices or retire their old ones. In fact you may have some devices at home that are subscribed to apps you have not visited in years!

Using Segments you can check all device record's that have not opened your app or website in over x amount (1 year, 6 months, event 1 hour) of time using the "Last Session" filter.

If you have devices that have not returned back to the app or site you can delete these devices. However, make sure you do not accidentally delete active users.

Mutable Content (iOS)

All push notifications sent to iOS devices automatically include the mutable-content parameter set to 1. This allows for the notification to be processed by the Service Extension which is required in order to make Confirmed Deliveries work correctly.

Safari Not Supported

Confirmed Deliveries on web requires the use of Service Workers. Safari does not use Service Workers in the same way as Chromium based browsers and therefore does not support Confirmed Deliveries at this time.

How to track which devices confirmed delivery?

Currently Confirmed Deliveries only tracks how many devices confirmed. It does not track which devices confirmed yet.

In order to track which specific devices confirmed receiving the push, (for example you want to send an email, In-App Message or SMS if they did not confirm) you would need to target devices individually either with the include_player_ids or include_external_user_ids targeting parameters on our Create notification REST API.

You will want to save the device ids targeted and notification "id" provided in the API Response. Further if the device is unsubscribed, you will get the unsubscribed device id in the invalid_player_ids or invalid_external_user_ids response.

After x amount of time has passed that you want to wait for checking if confirmed, you can use the View notification API endpoint with the notification "id" saved from the response.

If received is 0, then they device has not received the push yet. Depending on how long you want to wait, you can set the ttl parameter to discard the push if x time as passed. See Notification Behavior & Payload Information for more details.

Confirmed Delivery Limitations

Displayed but NOT Confirmed

Platform

Details

Android & iOS

  • Networking issue where device couldn’t finish a network call to onesignal.com
  • App or NSE crash after displaying

iOS

  • Network took over 30 seconds (iOS kills the NSE after this timeout) to response.

Confirmed but NOT Displayed

Platform

Details

Android & iOS

  • Notification does display BUT user doesn’t notice it due to low visibility; such as no sound, vibration, or grouped within to many other notifications.

  • Too many apps open on the device taking up too much memory - Possible but not likely. iOS NSE uses very little RAM. Android, possible on some low RAM devices under rare cases.

iOS

  • App is foreground AND one of the following:
    • OneSignal’s InFocus displaying is set to NONE
    • Another SDK or library suppressed the notification

Android

  • User turns off notifications at the device level and does not open app yet
  • User turns off notification category / channel for the notification that we tried to display
  • OneSignal NES is not displaying our notification we may be miss reporting it

Delivered status but NOT Displayed AND NOT Confirmed

Not really a “Confirmed Delivered” issue but covering here for completeness.

Plataform

Details

iOS

  • Device is offline and two or more notifications are sent
    • Apple’s APNs server only stores-and-forwards 1 (the most recent) notification per app.

Android

  • Device is offline and two or more notifications are sent with the same collapse_id
    • By design collapse_id replaces the stores-and-forward push on FCM’s server

Updated about 19 hours ago


What's Next

Delivery
Outcomes

Confirmed Deliveries


Tracking received rates on notifications.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.