Multi-platform mobile push notifications. Notifications are declared
with the defpush macro and delivered through Firebase Cloud Messaging
(FCM) and the Apple Push Notification service (APNs) behind a unified
service, with job-backed reliable delivery and delivery analytics.
| Namespace | Purpose |
|---|---|
| Pure: locale resolution and template rendering |
|
|
| Pure: delivery planning + error classification (retryable / permanent / token-invalid) |
| Pure: device-token lifecycle logic (registration, rotation, deactivation) |
| Pure: delivery analytics aggregation |
| Protocols: |
| Orchestrator dispatching to platform providers |
| FCM provider — async parallel delivery via |
| APNs provider — async parallel delivery via |
| REST endpoints (devices, callback, stats) |
The defpush macro defines notifications declaratively with i18n locale
maps, deep links, priority, TTL, collapse keys, and retry configuration.
Device token lifecycle is managed end to end — registration, rotation, soft-deactivation, and cleanup of stale tokens. Tokens are stored with multi-tenant support.
send-push!, schedule-push! and broadcast! enqueue :push/send and
:push/broadcast jobs, so the :wagoe/jobs module must be enabled; the
handlers and queue are wired only then. Each device’s result is recorded in
push_send_log, and a token the provider reports invalid is deactivated.
A failed send to one device is not retried; a job retries only when its
handler throws.
An HMAC-secured callback endpoint accepts client-reported delivery and
open events, recorded in push_analytics_events. Each push’s data carries
notification-id, provider-message-id and callback-token; the app posts
them back with device-token, platform and event-type (delivered or
opened). Each device gets its own token, valid for seven days by default and for that
notification, device and platform only; a repeat is answered but counted once.
The sent row and its callbacks share callback_id. This needs
:callback-secret in :wagoe/push: without it pushes carry no token, every
callback is refused with 403, and push warns at boot unless both providers are
mocks.
Two optional :wagoe/push keys tune the token:
| Key | Default | Meaning |
|---|---|---|
|
| How long a token verifies. Raise it when a push’s provider TTL is longer, or a late callback is refused. |
|
| Refuse tokens in the 1.0 form, which verify for any notification and device and never expire. |
| Endpoint | Purpose |
|---|---|
| Register and list the caller’s device tokens |
| Read or unregister one; a registration’s |
| HMAC-secured delivery/open analytics callback (public) |
| Per-notification delivery stats ( |
The module mounts these routes itself. Every route but the callback needs a signed-in user.
| Table | Holds |
|---|---|
| Registered device tokens |
| Per-send delivery records |
| Client-reported delivery/open events |
Mock providers are included for dev/test, and Integrant wiring is provided for all components.
Can you improve this documentation? These fine people already did:
thijscreemers & Thijs CreemersEdit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |