Analytics — Reference
The Analytics surface is the per-site measurement plane for an SGEN site. It owns traffic capture, engagement aggregation, event collection, dashboard widget rendering, and the date-range and segment filters that drive every view inside the module. This reference covers the shape of the surface — its actions, data model, capability matrix, and consent pipeline — for platform engineers and integrators who need to understand it before extending it, scripting against it, or pulling its data into an external warehouse.
Measurement plane
Everything answering who visited what, when, and what they did traces back to a record managed here — across visitors, sessions, pageviews, events, and segments.
Read-heavy by design
Heavier processing (sampling, percentile computation, retention math) runs against a derived store rebuilt on a fixed cadence. The dashboard reads from the derived store, not from raw event rows.
Consent-gated
The ingestion endpoint enforces consent at write time. Events tied to a denied consent category never enter the raw store — there is no "captured but hidden" state.
Overview
Analytics lives under the Analytics module in SG-Admin. The module renders four primary views — the overview dashboard, the traffic report, the engagement report, and the events report — and exposes a small set of read operations for filtering by date range, segment, and dimension. Writes against the surface are limited to event ingestion (called by tracked surfaces) and configuration writes (segment definitions, custom event names, dashboard widget layout).
The module is paired by convention with the Tracking Consent surface — the consent record on a visitor decides which event categories are captured for that session. Analytics never reads from a tracking source that the consent surface has not authorized.
A second surface — cross-site analytics — lives one level above the per-site module, in SG-Dashboard. Cross-site rollups read from the same per-site stores but aggregate across the operator's full portfolio. This page covers the per-site surface only; the cross-site rollup has its own reference.
Where it lives in SG-Admin: Sidebar: SG-Admin → Analytics · URL prefix: /sg-admin/analytics/
Actions
The Analytics surface exposes the following operations. Each is described by what it returns or writes, not by its internal method name.
Overview
Overview dashboard
Returns the headline metrics for the selected date range — visitors, sessions, pageviews, average session duration — with a period-over-period delta against the equivalent prior window. Includes a daily-bucket time series for the primary metric and three side-panel rollups (top pages, top sources, top events). The default range is the last 30 days; the picker supports preset windows (today, 7d, 30d, 90d, custom) and a comparison toggle.
Traffic
Traffic report
Drills into the traffic dimension. Returns rows by source (direct, search, referral, social, email, paid), by medium (organic, cpc, etc.), by referring host, and by landing page. Supports column sort, segment filter, and a secondary dimension overlay (for example, source × device).
Engagement
Engagement report
Drills into the engagement dimension. Returns rows by page path with pageviews, unique visitors, average time on page, exit rate, and scroll depth. Includes a per-page filter for entry pages, exit pages, and pages that received internal-link traffic only.
Events
Events report
Lists the named events captured in the date range, with count, unique-visitor count, and per-event property breakdowns. Custom events are mixed with system events (page-view, session-start, form-submit, cta-click) in the same list, distinguished by an origin column.
Real-time
Real-time view
A live counter of active sessions in the last 5 minutes, with a top-pages-right-now list and a top-events-in-the-last-hour stream. Polls server-side at a fixed interval; the dashboard never reads from the raw store directly for this view.
Filtering
Date-range filter
A standalone control that scopes every report on the page. Accepts preset windows, an absolute range, and a comparison range. The filter state lives in the URL so a dashboard view is shareable by link.
Segments
Segment filter, save, and delete
Constrains every report to a named slice of the visitor base. Segments are saved by the operator and re-applied on demand — each segment is a list of dimension predicates joined by AND; the surface supports compound segments via segment-of-segments. Saved segments can be private (per operator) or shared (visible to all operators on the site). Removing a saved segment falls the affected reports back to the unsegmented view; no historical data is lost.
Export
Export
Produces a CSV or JSON snapshot of the current report view with the current filter state applied. Used for offline analysis or for syncing into an external warehouse. Exports respect the consent surface — events captured under a denied consent category do not appear.
Layout
Widget layout
A write operation against the dashboard. Sets which widgets render on the overview, their order, and their size. Stored per operator so each operator's overview reflects their priorities. Widget layout writes are debounced at the client — rapid drag-and-drop reorders coalesce into one persisted state when the operator releases the active widget.
Ingestion
Event ingestion (system endpoint)
Not exposed in the SG-Admin UI. Tracked surfaces (public pages, forms, custom event calls) post events to a dedicated ingestion endpoint that writes into the raw store. The ingestion endpoint enforces consent at write time — denied categories never reach the store.
Data model
The Analytics surface reads from a derived store rebuilt on a fixed cadence and writes to a raw event store on every captured event. The two stores share a conceptual record shape.
| Field | Type | Notes |
|---|---|---|
event_id | string | Primary key. Stable per event. |
site_id | integer | Foreign key to the site. Every event belongs to one site. |
visitor_id | string | Anonymous identifier. Persists across sessions for the same browser unless cleared. |
session_id | string | Per-session identifier. Re-rolls after 30 minutes of inactivity. |
event_name | string | One of the system names (page-view, session-start, form-submit, cta-click, video-play, download, session-end) or a custom name. |
event_origin | enum | system or custom. |
page_path | string | Path of the page the event fired on. |
referrer | string | Optional. Document referrer at the time of event. |
source | enum | direct, search, referral, social, email, paid. Derived at write time. |
medium | string | Optional. organic, cpc, email, etc. |
device | enum | desktop, tablet, mobile. |
browser | string | Browser family name. |
country | string | ISO 3166 country code. Resolved from IP at write time, then IP is dropped. |
consent_categories | array | The consent categories the visitor authorized at the time of capture. |
properties | JSON | Optional event-specific key/value pairs. |
occurred_at | timestamp | Event time. |
Consent semantics: the ingestion endpoint reads the visitor's consent record before writing. Events tied to a denied category never enter the raw store. The store does not retain any consent-denied event — there is no "captured but hidden" state.
Retention: the raw store retains events for the window configured under Settings → Analytics → Retention (default 14 months). The derived store retains aggregates indefinitely. Reports that query a date range beyond the raw retention window return aggregate-only data and disable the per-event drill-down.
Visitor and session identifiers: stored client-side under the consent-controlled storage category. If consent is revoked, the identifiers are dropped on the next page load and the visitor appears as new on subsequent captures.
TRACKED SURFACE ANALYTICS STORES
┌──────────────────────────┐
│ Public page load │
│ Form submit │
│ CTA click │ ──── consent check
│ Custom event call │ │
└──────────────────────────┘ allowed │ ▼ ┌────────────────────┐ │ Raw event store │ retention: 14 months │ (per-event rows) │ (Settings configurable) └────────┄──────────┘ │ rebuild on fixed cadence ▼ ┌────────────────────┐ │ Derived store │ retention: indefinite │ (aggregates + │ │ rollups + sample) │ └────────┄──────────┘ │ reads ▼ ┌────────────────────┐ │ Dashboard + Reports│ │ + Export │ └────────────────────┘Permissions
Access to the Analytics surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Analytics surface.
Layer 2 — per-action capability. Within SG-Admin, each Analytics action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| View overview dashboard | ✔ | ✔ | ✔ |
| Run traffic report | ✔ | ✔ | ✔ |
| Run engagement report | ✔ | ✔ | ✔ |
| Run events report | ✔ | ✔ | ✔ |
| View real-time | ✔ | ✔ | ✔ |
| Apply segment filter | ✔ | ✔ | ✔ |
| Save segment (private) | ✔ | ✔ | — |
| Save segment (shared) | ✔ | ✔ | — |
| Delete segment | ✔ | ✔ (own only) | — |
| Export | ✔ | ✔ | — |
| Edit widget layout | ✔ | ✔ | ✔ (own layout) |
| Configure retention | ✔ | — | — |
| Configure custom event names | ✔ | ✔ | — |
Custom roles defined under Settings → Roles override the default map. The capability slugs are stable; the role slugs are configurable.
Consent-aware filtering. Every report respects the visitor's recorded consent at capture time. An operator with full Analytics access still cannot read events that were never captured because consent was denied. The capability map does not override the consent gate.
Audit. Every configuration write — segment save, segment delete, widget layout change, custom event name change, retention change — emits an Activity Log entry. Read operations (running a report, exporting a view) are not audited by default; an optional flag under Settings → Analytics enables read-audit for compliance-sensitive sites.
REQUEST ► /sg-admin/analytics/...
│
▼
┌────────────────────────┐
│ Admin gate │ unauth ► reject
└──────────┄─────────────┘ │ authed ▼
┌────────────────────────┐
│ Role capability check │ role lacks cap ► reject
└──────────┄─────────────┘ │ allowed ▼
┌────────────────────────┐
│ Consent filter │ denied categories ► never in store
│ (applied at read) │ (nothing to gate, nothing to return)
└──────────┄─────────────┘ │ passes ▼ report renders │ ▼
(optional) Activity Log entry
— writes always, reads only when read-audit is onHeads up This page describes the shape of the Analytics surface for platform engineers and integrators. Customer-facing how-tos for reading the dashboard, building a segment, and exporting a report live in the Analytics section of the customer docs.