Activation and Setup

Analytics is enabled for your environment by dotCMS Customer Success — there is no self-service path during the Early Adopter Program. The steps below describe what that provisioning sets up, and the one step that is yours.

Step 1: Configure Per Site#

dotCMS Analytics is configured through the Content Analytics app under Settings → Apps.

Configuration is per site

Analytics settings — including the Site Auth — are stored per host. Every site you want to track needs its own Content Analytics configuration. Settings on one site do not apply to another.

Step 2: Site Auth Per Domain#

One is created for you

When your environment is provisioned, the dotCMS team auto-generates a Site Auth for each domain, so you can start tracking without doing anything here. You can still change it later — the field is yours to edit.

The Site Auth identifies and authorizes the analytics events coming from a given site. It is required in every event request. To replace it, paste your own value, or click Auto Generate Site Auth to have dotCMS generate a new secure one.

How Site Auth Is Used#

On every incoming batch, dotCMS resolves which site the events belong to from the request's Origin or Referer header, matching it against a dotCMS site name or alias. It then checks the site_auth in the payload against the Site Auth configured on that site. If they do not match, the events are rejected.

Attribution comes from the resolved site, not from the Site Auth — so the Site Auth acts as an access check at ingest time, not as the identifier your data is stored under.

Never reuse a Site Auth across domains

Each domain has its own Site Auth. A Site Auth from one site sent from another domain does not match that domain's configuration, so every event is rejected — you do not get misattributed data, you get no data at all.

If you change it, update everywhere it is used

Your historical data is safe: events are stored against the site, so changing the Site Auth does not orphan or split anything you have already collected.

But every event sent with the old value is rejected from that moment on. After changing it, update the value in your headless app configuration and redeploy, or — on Traditional sites — flush the Velocity cache so the injected script carries the new value. Until you do, tracking stops silently: the failures happen in the visitor's browser and nothing surfaces in the admin.

Headless: your app's domain must be known to dotCMS

Because the site is resolved from Origin or Referer, the domain your app runs on must exist in dotCMS as a site name or alias. If it does not, the events cannot be matched to a site and are rejected.

You will use this value automatically in Traditional mode (dotCMS injects it into the script), or by copying it into your application config in Headless mode.

Step 3: Connect Event Manager#

You do not perform this step

The Event Manager connection is set up by the dotCMS team when your environment is provisioned. It is described here so you know what the app is doing — the credentials it uses are dotCMS infrastructure credentials, not yours.

The Content Analytics app needs a bearer token to talk to the dotCMS Analytics service. dotCMS performs this as a one-time exchange:

The Admin Username and Admin Password for the event manager are entered in the app.
On Save, dotCMS uses those credentials to mint a bearer token scoped to your tenant.
On success, both fields are cleared automatically. Neither the username nor the password is stored — only the encrypted bearer token is retained.

Your tenant is determined by your dotCMS infrastructure; there is nothing to enter for it. If the token ever needs to be rotated, contact dotCMS Support — rotation repeats this same exchange.

Step 4: Add the Analytics Tool#

The dashboard does not appear on its own

Analytics is a standard dotCMS portlet. Configuring the Content Analytics app sets up tracking, but the dashboard stays hidden until an administrator adds the Analytics portlet to the navigation menu and assigns it to the appropriate roles — the same procedure used for any other portlet.