How Analytics Works
Analytics data starts as individual interactions in the visitor's browser and ends as figures on a dashboard. This page describes that path: the four kinds of interaction dotCMS records, when the browser sends them, and how they are grouped into visitors and sessions.
Four Event Types#
| Event | Internal name | What it means | What it takes to get it |
|---|---|---|---|
| Page View | pageview | A visitor loaded or viewed a page. | On by default on Traditional sites. In headless it comes from the React component, or from your own pageView() call. |
| Content Click | content_click | A visitor clicked a link or button inside a tracked content item. | Off by default. Turn it on and dotCMS marks your content for tracking. |
| Content Impression | content_impression | A content item became visible on screen long enough to count as seen. | Off by default. Turn it on and dotCMS marks your content for tracking. |
| Conversion | conversion | A visitor completed a goal you defined. | Always sent from your own code, after the goal actually succeeds. |
Out of the box you get page views, and nothing else
Clicks and impressions are disabled by default in both delivery models, and even once enabled they only cover content dotCMS can mark for tracking. Conversions are never automatic in any setup — you always send them yourself.
So a freshly configured site reports page views only. See Traditional or Headless setup for the toggles and the markup.
Page View records the page URL, title, host, path, protocol, query string, hash, encoding and locale, plus the visitor's screen resolution, viewport size and language, and any UTM campaign parameters present in the URL. See the Ingest API for the exact payload. It is the one event that needs no markup — any page reached by the tracking script is counted.
Content Click fires when a visitor clicks an <a> or <button> inside a tracked content item. Only those two element types are tracked, and only inside content carrying the tracking markup — a click anywhere else on the page produces nothing. It captures the element's text, type, id, class and href, plus its position on the page. Rapid duplicate clicks are throttled at 300 ms. Any data-* attributes you add to the element are captured with the event.
Content Impression fires when a tracked content item is at least 50% visible for at least 750 ms — distinguishing "rendered somewhere on the page" from "actually seen". As with clicks, only content carrying the tracking markup is watched. Each content item counts at most once per session. Both the visibility fraction and the dwell time are configurable, as is the maximum number of items watched on a page.
Conversion events are always sent manually from your code, and only after the action has actually succeeded. See Conversions.
When Events Are Sent#
Events are queued in the browser and sent together when the batch reaches 15 events or every 5 seconds, whichever comes first. Any events still queued when the visitor leaves the page are flushed on pagehide using keepalive, so they survive navigation.
Batch size and flush interval are both tunable, and batching can be turned off entirely so each event is sent immediately — see Traditional or Headless setup.
Delivery is best-effort
The analytics service accepts a batch and writes it asynchronously. In rare failure conditions — the service shedding load under saturation, or a write failing after the batch was accepted — those events are dropped rather than retried. Analytics totals are a very close approximation of traffic, not an audited count; do not use them where an exact figure matters, such as billing.
Traffic source is not captured
Events do not record where a visitor came from. Campaign attribution is available through the UTM parameters on the landing URL, which are captured on the page view — so tag your campaign links if you need to attribute traffic.
Visitors and Sessions#
- Visitor ID — a random identifier stored in the browser and reused across visits to recognize a returning visitor. It is not a personal identifier and is not shared across sites.
- Session — a single continuous visit. A new session starts when the visitor has been inactive for 30 minutes, when the clock passes midnight UTC, or when the visitor arrives with a different UTM campaign.
Editing mode is never tracked
Analytics is automatically disabled when a page is open in the Universal Visual Editor (UVE). Your editing activity never generates events.