Expand description
Default first-party web analytics (#analytics).
Every rustango-cms site gets privacy-conscious engagement analytics that keeps working when the HTML is served from a CDN and deeply cached. Collection is driven entirely by a client beacon to endpoints that are never cached:
- Pageview —
POST /__cms__/collect(CSRF-exempt,no-store), one row per page load. Seecollect. - Engagement + “active now” — a WebSocket at
/__cms__/ws; the server times connect→disconnect and writes one engagement row on close, and keeps an in-memory per-tenant “active now” gauge. Seews. If the socket can’t open, the beacon falls back to an unloadPOST /__cms__/collect.
The beacon <script> is auto-injected into every rendered public
page (see render.rs), so consumers need no template change. The
one required consumer line is CsrfConfig::exempt_prefix(COLLECT_PATH)
(a sendBeacon POST can’t carry an X-CSRF-Token, and a CDN-cached
page may never have received a CSRF cookie).
Data model + boot table creation: model. Aggregates for the
admin dashboard (/cms-admin/analytics): query. Retention:
retention.
Re-exports§
pub use model::ensure_table;pub use model::AnalyticsEvent;
Modules§
- collect
- Public analytics collector —
POST /__cms__/collect. - model
- Analytics event model + boot-time table/index creation.
- query
- Dashboard aggregates over
cms_analytics_event. - retention
- Analytics retention — delete events older than N days. Run per tenant at boot (servers restart/redeploy regularly).
- ws
- Engagement WebSocket —
GET /__cms__/ws(an HTTP upgrade, so it bypasses both the page cache and CSRF).
Constants§
- BEACON_
JS_ PATH - Beacon script endpoint (GET, immutable-cached).
- COLLECT_
PATH - Public collector endpoint (POST via
sendBeacon). Referenced by the consumer’sCsrfConfig::exempt_prefixand by the beacon JS. - SETTINGS_
SCOPE SiteSettingscope holding the analytics config{ enabled, retention_days }.- WS_PATH
- Engagement WebSocket endpoint (GET upgrade).
Functions§
- beacon_
asset_ version - FNV-1a fingerprint of the beacon JS, for the
?v=cache-buster. - enabled
- Whether analytics is enabled for this render, from the prefetched
SiteSettingscope→value map. Default on (inject unless the"analytics"row explicitly setsenabled: false). - inject_
beacon - Insert the beacon
<script>immediately before the last</body>. No-op when the tag is absent (fragments / non-HTML) — never appends blindly. Runs during render, before the page cache stores the response, so cached HTML carries the tag. - presence_
count - Current “active now” count for a tenant
Host. - serve_
beacon_ js GET /__cms__/a.js— the beacon script, immutable-cached (version busted via the?v=the injected tag carries).