Push Notifications
EdgeBase Push manages the complete push token lifecycle on the backend — the part every team rebuilds from scratch. Device tokens are mapped to user IDs with multi-device routing (up to 10 devices per user), automatic token refresh, deduplication, and cleanup of invalid tokens. Add topic-based subscriptions and broadcast messaging on top. Just call send() with a user ID and payload — EdgeBase resolves all devices and delivers through FCM.
Server-side push sending, logs, topic operations, and broadcast are available across all Admin SDKs.
Architecture
EdgeBase uses Firebase Cloud Messaging (FCM) as the single delivery provider for all platforms. Your client apps use the Firebase SDK to obtain FCM registration tokens, which are then stored and managed by EdgeBase.
┌─────────────┐ FCM Token ┌──────────────┐ FCM HTTP v1 ┌─────┐ │ Client App │ ──────────────→ │ EdgeBase │ ──────────────→ │ FCM │ → Device │ (Firebase SDK)│ │ Server (KV) │ │ │ └─────────────┘ └──────────────┘ └─────┘
How it works:
- Token Acquisition — Your client app uses the Firebase SDK to get an FCM registration token.
- Token Registration — The client SDK sends this token to your EdgeBase server, stored in KV mapped to
userIdanddeviceId. - Sending — Your backend calls
admin.push.send(userId, payload). EdgeBase looks up all devices and sends through FCM. - Lifecycle — EdgeBase handles token refresh, deduplication, and automatic cleanup of invalid tokens.
Push vs Realtime and Room
Push is not another realtime channel. Realtime Subscriptions, Presence, Broadcast, and Room all target clients with an active live connection. Push targets registered devices through FCM and is meant for alerts that should arrive even when the app is backgrounded or not currently connected.
For the full five-way comparison, see Choosing Between Subscriptions, Presence, Broadcast, Room, and Push.
Key Features
Multi-Device Management
Up to 10 devices per user. All devices receive notifications. Stale tokens are cleaned up when FCM returns 404/410/UNREGISTERED during a send attempt.
Topic Messaging
Subscribe devices to topics (news, sports) and send to all subscribers at once.
Broadcast
Send to every registered device. All tokens auto-subscribe to the 'all' topic.
Push Logs
24-hour send logs with status (sent, failed, removed) and error details for debugging.
Token Caching
Client SDKs cache tokens locally. Server requests only fire when the token actually changes.
Auto-Unregister
On sign out, the SDK automatically unregisters the device token before clearing the session.
What You Don't Have to Build
Push notification delivery (FCM/APNs) is well-documented. The hard part is everything around it — the backend infrastructure that maps users to tokens across devices, handles token churn, and cleans up stale registrations. This is what EdgeBase manages for you:
| Without EdgeBase | With EdgeBase |
|---|---|
Build a user_tokens table, handle schema migrations | client.push.registerToken() — stored in KV automatically |
| Write token refresh logic (FCM tokens expire/rotate) | Automatic — SDK detects changes and re-registers |
| Handle multi-device (user signs in on phone + tablet) | Built-in — up to 10 devices per user, all receive notifications |
| Detect and remove invalid tokens (uninstalled apps) | Automatic — invalid tokens are cleaned up on failed sends |
| Deduplicate tokens (same device, multiple sign-ins) | Automatic — deviceId-based deduplication |
| Build topic subscription management | client.push.subscribeTopic('news') — one line |
| Build send-to-user API (resolve userId → all device tokens) | admin.push.send(userId, payload) — resolves all devices |
| Set up logging for delivery debugging | Built-in 24h push logs with status and error details |
This is typically 200–500 lines of backend code that every team writes from scratch. EdgeBase eliminates it entirely.
Token Storage
Push tokens are stored in Cloudflare KV (not the database). This design choice is intentional:
- High churn — Push tokens change frequently. KV handles this without migration complexity.
- Edge-cached reads — Token lookups are fast at send time.
- No backup contamination — Invalid tokens don't get restored during database backups.
KV key patterns:
push:user:{userId}→ JSON array of all devices for a user (single source of truth)push:topic:{topic}:{userId}→ Topic subscription recordpush:log:{userId}:{timestamp}→ Send log entries (24h TTL)