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. Anything that answers a question of the shape who visited what, when, and what did they do traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or pulling its data into an external warehouse. Customer-facing how-tos for reading the dashboard and reading individual report views live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
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/ - View templates:
application/views/Admin/Analytics/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Analytics [Last 30 days ▾] [Export] │├──────────────────────────────────────────────────────────────────────┤│ Visitors Sessions Pageviews Avg session ││ ─────── ──────── ───────── ──────────── ││ 14,208 18,742 51,309 2m 41s ││ ▲ 12.4% ▲ 8.7% ▲ 14.1% ▼ 0.6% ││ ││ ┌───────────────────────── Daily visitors ─────────────────────────┐││ │ ▁▂▄▃▅▆▇▅▃▄▆▇█▆▅▃▅▆▇▆▄▃▂▃▅▇▆▄▃ │││ └───────────────────────────────────────────────────────────────────┘││ ││ Top pages Top sources Top events ││ ─────────────────── ────────────────── ───────────────────── ││ /pricing 4,812 google 9,201 form-submit 1,204 ││ / 3,914 direct 3,802 cta-click 2,891 ││ /docs/users 2,118 referral 2,418 video-play 1,015 ││ /blog/launch 1,604 email 1,902 download 412 │└──────────────────────────────────────────────────────────────────────┘Actions
The Analytics surface exposes the following operations. Each is described by what it returns or writes, not by its internal method name.
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 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 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 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 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.
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.
Segment filter
Constrains every report to a named slice of the visitor base — for example, visitors from organic search who viewed the pricing page. 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.
Save segment
Persists a segment definition under a chosen name. The definition is stored alongside the site, scoped per operator (private) or shared (visible to all operators on the site). Saved segments appear in the segment-filter picker.
Delete segment
Removes a saved segment. Reports that referenced the deleted segment fall back to the unsegmented view; no historical data is lost.
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.
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.
Event ingestion (system endpoint)
Not exposed in the SG-Admin UI. The 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. |
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 | ✔ | ✔ | — |
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 onRelated references
- Tracking Consent — Reference. The consent record decides which event categories enter the raw store. Analytics never reads from a tracking source that consent has not authorized.
- Settings — Reference. Owns retention windows, custom event name definitions, read-audit toggle, and the consent-category mapping.
- SG-Dashboard — Reference. Cross-site analytics rolls up from per-site stores documented here.
- Forms — Reference. Form-submit events fire into the Analytics ingestion endpoint and appear in the events report.
- Users — Reference. Saved segments and widget layouts are scoped per operator. Operator removal triggers cleanup of private segments and personal widget layouts.
- Pages — Reference. Page-view events resolve
page_pathagainst the page record at report render time, so renamed pages show the latest title on the engagement report. - Activity Log — Reference. Configuration writes against Analytics emit Activity Log entries; the log is the audit trail for the surface.
/docs/analytics.