Push Notifications Overview

Push Notifications Overview

Instructions

Push notifications are a privileged channel. They drive retention and support real-time features, but every mis-send erodes trust. This skill covers the flow end-to-end and the mistakes that cost engagement.

1. Architecture at 10,000 feet

Server -> FCM (Android, all)  -> Device (system tray) -> App handler
       -> APNs (iOS)          -> Device (system tray) -> App handler

• Android: FCM is the transport. Even if you use Firebase or a third party, the wire is FCM.
• iOS: APNs is the transport. FCM routes to APNs under the hood when you use Firebase.
• Token lifecycle: the device registers, you store {userId, platform, token} on the server, and invalidate on sign-out or token rotation.

2. Notification vs Data Messages

Silent pushes are throttled (APNs apns-priority: 5, background mode; Android high vs normal priority with Doze). Do not rely on them for time-critical delivery.

3. Permissions

• iOS: ask with UNUserNotificationCenter.current().requestAuthorization(options:). Prompt in a thoughtful moment, not at first launch. Support provisional authorization (.provisional) to deliver quietly until the user opts in.
• Android 13+: POST_NOTIFICATIONS runtime permission required. If the user denies, the app must still function.

Track permission state and respect it. Never "re-prompt" by navigating to Settings repeatedly.

4. Payload Shapes

// FCM common payload (server)
{
  "message": {
    "token": "DEVICE_TOKEN",
    "notification": { "title": "New message", "body": "Alex sent you a photo" },
    "data": { "conversationId": "c_123", "type": "message.new" },
    "android": { "priority": "HIGH", "notification": { "channel_id": "messages" } },
    "apns": {
      "headers": { "apns-priority": "10", "apns-push-type": "alert" },
      "payload": { "aps": { "alert": { "title": "New message", "body": "..." }, "sound": "default", "thread-id": "c_123" } }
    }
  }
}

Rules:

• Keep payload under 4 KB.
• Put routing info in data (stable keys, versioned).
• Keep user-visible copy in notification.
• Always include a type string in data so clients can dispatch.

5. Client Handling

// iOS
class NotificationHandler: NSObject, UNUserNotificationCenterDelegate {
    func userNotificationCenter(_ c: UNUserNotificationCenter,
                                didReceive response: UNNotificationResponse) async {
        let userInfo = response.notification.request.content.userInfo
        Router.shared.handle(notification: userInfo)
    }
    // Silent/data push:
    func application(_ app: UIApplication,
                     didReceiveRemoteNotification userInfo: [AnyHashable : Any]) async -> UIBackgroundFetchResult {
        await SyncService.shared.handle(userInfo)
        return .newData
    }
}

// Android
class AppMessagingService : FirebaseMessagingService() {
    override fun onMessageReceived(msg: RemoteMessage) {
        val type = msg.data["type"] ?: return
        when (type) {
            "message.new" -> Notifications.showMessage(this, msg)
            "sync.pull"   -> WorkManager.getInstance(this).enqueue(OneTimeWorkRequestBuilder<SyncWorker>().build())
        }
    }
    override fun onNewToken(token: String) { TokenRegistry.sync(token) }
}

// Flutter (firebase_messaging)
FirebaseMessaging.onMessage.listen((msg) => Router.handle(msg.data));
FirebaseMessaging.onMessageOpenedApp.listen((msg) => Router.handle(msg.data));
FirebaseMessaging.onBackgroundMessage(_bg);

// React Native (@react-native-firebase/messaging)
messaging().onMessage(async (msg) => Router.handle(msg.data));
messaging().onNotificationOpenedApp((msg) => Router.handle(msg.data));
messaging().setBackgroundMessageHandler(async (msg) => { await sync(msg.data); });

6. Channels, Categories, and Grouping

• Android: declare NotificationChannels at startup (messages, marketing, security). Users can disable per-channel.
• iOS: use UNNotificationCategory with actions (Reply, Archive). Use thread-id to group.
• Never send marketing and transactional on the same channel.

7. Deep Linking From Notifications

A notification tap is a deep link with extra context. Reuse the same router (see deep-links-universal-links). Buffer the notification intent if the navigator is not mounted yet.

8. Testing

• APNs: send from curl with a provider token; use sandbox APNs in development builds.
• FCM: curl against the v1 HTTP API or use the Firebase console for one-off tests.
• iOS simulator: xcrun simctl push booted bundle.id payload.apns.
• Android emulator: Firebase Test Lab or real device. Emulator support is limited.
• Write integration tests that assert routing from payload to screen, not the transport.

9. Observability

Track, per notification:

• Sent, delivered (where observable), opened.
• Conversion to the intended action.
• Error classes: invalid token, quota exceeded, payload too large.

Rotate and invalidate stale tokens; batch-delete tokens that return Unregistered for 7 consecutive days.

10. Anti-Patterns

• Marketing blasts on a transactional channel.
• Prompting for permission on first launch before any value is demonstrated.
• Putting user PII in the payload; the OS and intermediaries can see it.
• Relying on silent pushes for time-critical delivery.
• Not versioning data payload keys.
• Sending the same message to multiple devices of the same user without deduplication.

Checklist

• Token registration and invalidation happen on sign-in, sign-out, and token rotation.
• Permission is requested in a contextual moment, and respected.
• Payloads are under 4 KB and include a versioned type in data.
• Android notification channels are declared; iOS categories/thread-ids are set.
• Notification tap routes through the same deep-link router.
• Silent pushes are not used for time-critical delivery.
• No PII in payloads.
• Delivery and open metrics are tracked; stale tokens are pruned.
• Integration tests cover payload-to-screen routing.