Android delivery hardening
On some Android manufacturers notifications arrive late or not at all. This guide explains why, how Pushizo measures it, and how to take users to the right settings screen in your app.
On some Android manufacturers notifications arrive late or not at all. This guide explains why, how Pushizo measures it, and how to take users to the right settings screen in your app. Decision record: docs/adr/0092-android-teslimat-guclendirme.md.
The problem
On Xiaomi, Redmi, POCO, Huawei, Honor, Oppo, Realme, OnePlus, Vivo, iQOO, Samsung, Meizu, Asus, Tecno and Infinix devices, the manufacturer's own battery and auto-start manager stops apps running in the background. Even when the FCM message reaches the device, the app is not started and the notification is not shown. FCM does not report this; on the server the message looks "sent".
Pushizo does two things:
- It measures. The SDK on the device sends a delivery receipt for every message. The dashboard groups these receipts by manufacturer and Android skin (ROM).
- It guides. The SDK reads the restrictions on the device and offers an API that takes the user to the relevant settings screen.
Requirements
- A version of the Android SDK that includes the
Pushizo.DeliveryAPI. Earlier versions also appear in the report (the manufacturer is derived from the device model), but the restriction summary needs the current SDK. - No extra permission is needed. The SDK does not add the
REQUEST_IGNORE_BATTERY_OPTIMIZATIONSpermission; Google Play accepts it only for certain kinds of apps.
Reading the device status
val status = Pushizo.Delivery.status() ?: return
status.vendor // HsDeviceVendor.XIAOMI, HUAWEI, OPPO, VIVO, SAMSUNG … OTHER
status.rom // "hyperos", "miui", "emui", "coloros", "oneui" …
status.batteryOptimizationExempt // is the app exempt from battery optimization
status.backgroundRestricted // has the user restricted background activity
status.standbyBucket // ACTIVE, WORKING_SET, FREQUENT, RARE, RESTRICTED
status.risk // NONE, ELEVATED, HIGH
status.recommendedSettings // settings screens worth opening| Risk | Meaning |
|---|---|
NONE | No known obstacle |
ELEVATED | Notifications may be delayed: a manufacturer with aggressive battery management and no battery exemption, a rarely-used app bucket, or data saver on |
HIGH | Notifications most likely do not arrive: notification permission or channel is off, or background activity is restricted |
Android does not let an app read whether auto-start is allowed. For that reason the SDK treats the risk as ELEVATED on aggressive manufacturers when there is no battery exemption.
Taking the user to the settings screen
Use the ready-made dialog. Its text ships in 22 languages; if the user accepts, the relevant settings screen opens.
if (Pushizo.Delivery.shouldShowGuidance()) {
Pushizo.Delivery.showGuidance(activity) { opened ->
// opened: whether a settings screen was opened
}
}shouldShowGuidance() returns true when there is a risk and the dialog has not been shown in the last 14 days. Change the interval with shouldShowGuidance(minIntervalDays = 30). The SDK never shows the dialog on its own; you choose the right moment. Suggestion: right after the user completes an action where notifications are useful (an order, a booking, a follow).
If you use your own UI, open the screen directly:
Pushizo.Delivery.openSettings(context) // the screen that best fits the status
Pushizo.Delivery.openSettings(context, HsDeliverySetting.AUTO_START) // auto-start manager
Pushizo.Delivery.openSettings(context, HsDeliverySetting.BATTERY_OPTIMIZATION) // battery settings
Pushizo.Delivery.openSettings(context, HsDeliverySetting.NOTIFICATIONS) // notification settings
Pushizo.Delivery.openSettings(context, HsDeliverySetting.APP_DETAILS) // app detailsopenSettings tries the manufacturer's own screen first. If the screen does not exist on the device or may not be opened, it falls back to a standard Android screen: the battery optimization list, then app details, then settings. It returns true if a screen was opened and never throws.
You can override the dialog text in your app's strings.xml using the same names: hs_delivery_title, hs_delivery_message, hs_delivery_message_vendor, hs_delivery_open_settings.
Delivery health in the dashboard
The Analytics → Android tab shows:
- Delivery rate (delivered / sent) and the time from send to arrival on the device (median and 90th percentile).
- Manufacturer table: devices, restricted devices, sent, delivered, open rate, delay, deprioritized messages.
- Device restrictions: background restricted, battery optimization on, in a rarely-used bucket, battery or data saver on, notification channel or permission off.
- Breakdown by Android skin (MIUI, HyperOS, EMUI, ColorOS, One UI …).
- Recommendations: the step to take based on your data.
| Recommendation | When it appears | What to do |
|---|---|---|
| SDK update | Fewer than half of the devices report diagnostics | Update the Android SDK in your app |
| Manufacturer guidance | Delivery rate on manufacturers with aggressive battery management is at least 5 points lower than on others | Take users to settings with showGuidance |
| Background restriction | At least 10% of reporting devices are restricted | Ask these users to remove the restriction with an in-app message |
| Battery exemption | Battery optimization is on for at least 80% of devices from aggressive manufacturers | Ask users to remove the battery restriction for critical notifications |
| Priority downgrade | FCM lowered the priority of at least 5% of delivered messages | Use high priority only for visible notifications |
| Notification permission | Permission is off on at least 30% of devices | Ask for permission at the right moment, with an explanation first |
No recommendation is produced for small samples (fewer than 10 devices or 20 sends).
API
The same report is available from the public API (analytics:read scope). Without from and to it covers the last 30 days; compare=true also returns the previous period; format=csv downloads the manufacturer table as CSV.
curl "https://api.pushizo.com/v1/apps/$APP_ID/analytics/android-delivery?compare=true" \
-H "Authorization: Bearer $PUSHIZO_API_KEY"{
"devices": { "total": 1840, "reporting": 1512, "restricted": 131, "restricted_rate": 0.0866, "aggressive_vendor": 1204 },
"totals": { "sent": 52310, "delivered": 44102, "delivery_rate": 0.8431, "median_delay_seconds": 4, "p90_delay_seconds": 310 },
"aggressive": { "sent": 33120, "delivered": 26010, "delivery_rate": 0.7853 },
"others": { "sent": 19190, "delivered": 18092, "delivery_rate": 0.9428 },
"vendors": [
{ "vendor": "xiaomi", "aggressive": true, "devices": 612, "sent": 17400, "delivered": 12870, "delivery_rate": 0.7397, "median_delay_seconds": 9 }
],
"recommendations": ["vendor_guidance", "battery_exemption"]
}What the SDK reports
Only the following fields are sent with the subscription registration; they contain no personal data and are not sent while privacy consent is pending:
| Field | Example |
|---|---|
manufacturer, brand | xiaomi, redmi |
rom, rom_version | hyperos, 1.0.2.0 |
delivery.battery_optimization_exempt | false |
delivery.background_restricted | false |
delivery.standby_bucket | active, working_set, frequent, rare, restricted |
delivery.power_save_mode, delivery.data_saver, delivery.channel_blocked | false |
When the manufacturer, ROM, battery exemption or background restriction changes, the server is updated right away. The bucket and saver modes are written at most once a day.
The delivery receipt is hardened too: while the app is in the background the receipt is written to the persistent queue and also sent by a scheduled job, so it arrives even if the process is stopped. The receipt carries the moment the device received the message; the delay is computed from that moment.
Limits
- The state of the auto-start permission cannot be read. Whether the user changed the setting shows in the improved delivery rate.
- Manufacturer screens are undocumented and change between versions. An outdated screen does no harm; the SDK falls back to the standard screen.
- Bridge SDKs (Flutter, React Native, Capacitor, Cordova, Unity, .NET MAUI, Kotlin Multiplatform) use the native Android SDK. Diagnostics and the hardened receipt arrive on their own once the native version is upgraded. The
Pushizo.Deliverycalls (status,openSettings,showGuidance,shouldShowGuidance) are available in the bridges too; usage is in the "Android delivery hardening" section of each bridge's SDK page. On iOS and other platforms the calls are harmless: the status is "unsupported / no risk" and no settings screen or dialog opens. - The report covers Android channels only (FCM, Huawei HMS, Amazon ADM).
Notifications to Huawei devices (HMS Push Kit)
Huawei devices without Google Play Services cannot receive Firebase (FCM) notifications. Pushizo sends to these devices through Huawei Push Kit with the hms_push channel…
Additional push channels
Amazon ADM, Windows WNS, fallback channel, smartwatch, live updates, carousel, VoIP and App Clip (ADR-0052).