silent-push

name	silent-push
description	Deliver background (silent) pushes to mobile reliably within OS budgets, and design fallbacks. Use when you need data-only pushes for sync or state invalidation.

Silent Push

Instructions

Silent (a.k.a. background, data-only) pushes wake the app briefly to refresh state without showing UI. Both iOS and Android rate-limit them aggressively; treat them as a hint, never a delivery guarantee.

1. When to Use

Good fits:

• Invalidate a local cache after a server-side change.
• Trigger a short sync so the next app open is instant.
• Badge count updates that are not time-critical.

Poor fits:

• Mission-critical state (payments, chat messages you must deliver) -- always pair with a user-visible push or server-side authoritative pull.
• Frequent polling replacement -- OS budgets will silently drop most sends.

2. iOS (APNs)

Set content-available: 1, no alert, apns-push-type: background, priority 5 (required; priority 10 background pushes are throttled).

{
  "aps": { "content-available": 1 },
  "type": "cache_invalidate",
  "entity": "feed"
}

POST /3/device/<token>
apns-push-type: background
apns-priority: 5
apns-topic: com.example.app

iOS throttles background pushes per app and per device (approximately 2–3 per hour, highly dynamic based on Low Power Mode, battery state, and app usage). The app gets ~30 s in application(_:didReceiveRemoteNotification:fetchCompletionHandler:) to do work and call the completion handler.

3. Android (FCM)

Data-only messages (no notification key) are delivered to FirebaseMessagingService.onMessageReceived. Use priority: "normal" by default; high only for user-visible results.

{
  "message": {
    "token": "...",
    "data": { "type": "cache_invalidate", "entity": "feed" },
    "android": { "priority": "NORMAL" }
  }
}

On Android, Doze and App Standby will defer normal-priority pushes. high priority bypasses Doze but burns battery and counts against the app's "push exemption" budget. Apps terminated by the user (swiped from recents on some OEMs) may not receive FCM at all.

4. Budgets

Plan as if you get a few silent pushes per user per day, distributed unevenly. If you need more throughput, switch to user-visible notifications for the highest-priority events and pull-based sync for the rest.

5. Reliability Tradeoffs

Silent push is best-effort. Pair it with a pull:

Silent push (hint) -> app fast-paths next update
                    -> app also pulls on resume / periodic background refresh
Server remains authoritative; delivery loss just means slower freshness.

Never increment an authoritative counter on the client in response to a silent push. Use them to invalidate, not to update.

6. Payload Design

Keep payloads small (< 1 KB) and deterministic:

{ "type": "invalidate", "entity": "orders", "id": "ord_01HX7..." }

The app looks up entity in a dispatch table and triggers the appropriate background task. Version the payload with a v field so old clients ignore types they do not understand.

7. Dedup and Ordering

Pushes can arrive out of order, duplicated, or not at all. Include a monotonically increasing seq per entity; drop older ones:

// Android
val last = prefs.getLong("inv.$entity.$id", 0)
if (data["seq"]!!.toLong() <= last) return
prefs.edit().putLong("inv.$entity.$id", data["seq"]!!.toLong()).apply()
invalidate(entity, id)

8. Send Side

Throttle aggressively per user to stay within provider/OS budgets:

// Node/TS
async function sendSilent(userId: string, payload: SilentPayload) {
  if (!(await budget.consume(userId, category = "silent"))) return; // drop
  const tokens = await tokens.forUser(userId);
  for (const t of tokens) await queue.enqueue({ token: t, payload, priority: "normal" });
}

Deduplicate identical invalidations within a short window (e.g., 10 s) -- many server events often collapse into one cache-bust.

9. Observability

• Log intent vs dispatch vs provider-ack vs app-ack (via a lightweight reply ping if it matters).
• Track the gap: how often the app's next pull happened before the silent push arrived. High gap -> silent push is not helping; reconsider.

Checklist

• Silent push used only for hints, not authoritative updates.
• iOS: apns-push-type: background, priority 5, content-available: 1, no alert.
• Android: data-only FCM with NORMAL priority unless justified.
• Payloads ≤ 1 KB, versioned, contain type + minimal identifiers.
• seq field enables ordering/dedup on the client.
• Pull-based sync is the fallback; server remains authoritative.
• Per-user silent-send budget enforced on the backend.
• Dashboards show delivery gap and drop rate.