Traditional vs Headless
dotCMS Analytics tracks the same events and feeds the same dashboards in both delivery models. What changes is how you turn it on and where you configure it.
| Traditional | Headless (Next.js / React) | |
|---|---|---|
| How it is activated | Configure the app on the site, then call the ViewTool in your theme. | Configure the app on the site, then install the SDK and initialize it in code with the Site Auth. |
| Code you add | $!dotAnalytics.code() in the theme or template. | <DotContentAnalytics> / useContentAnalytics, or the standalone script. |
| Where you configure tracking | Content Analytics app → Server-Rendered Pages Configuration. | Your application code. The app's tracking settings and Advanced Configuration do not apply. |
| Where the Site Auth lives | Stored in the app; injected into the generated script. | You copy it into your app config or env var. |
| Auto page-view | On by default. | Depends on the integration — see Headless setup. |
| Impressions / clicks | Toggled in the app; both off by default. | Enabled in SDK config; the app's toggles have no effect. |
| Custom events & conversions | window.dotAnalytics.track(…) / .conversion(…) | track(…) / conversion(…) from the hook. |
| Where it runs | LIVE pages of a configured site; disabled while editing. | Anywhere your app runs; disabled inside UVE. |
The Same in Both Modes#
- The Content Analytics app has to be configured on the site. Headless does not skip it — that is where the Site Auth comes from, and without it events are rejected. What headless does skip is the rest of the app: the tracking toggles and the Advanced Configuration apply to server-rendered pages only.
- The four event types, and the batching defaults and tuning options.
- Session rules: 30-minute inactivity, UTC midnight reset, UTM change.
- The
dotcms-contentletmarkup that makes clicks and impressions trackable — added for you in both models. - The dashboards and every metric.
- The Site Auth is per domain in both cases.
Mixed setups
Some pages server-rendered and some headless is a supported combination. Configure each surface with the matching approach, using the same site's Site Auth so all data is attributed to that domain.