Skip to main content

Module analytics

Module analytics 

Source
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. See collect.
  • 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. See ws. If the socket can’t open, the beacon falls back to an unload POST /__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’s CsrfConfig::exempt_prefix and by the beacon JS.
SETTINGS_SCOPE
SiteSetting scope 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 SiteSetting scope→value map. Default on (inject unless the "analytics" row explicitly sets enabled: 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).