Quickstart

Install Web Analytics, configure a Vercel or Plausible credential, create and test a connection, then verify the Umbraco Analytics dashboard.

Everything a first-time setup needs is on this page, from installing the package to a dashboard with numbers in it.

1. Check the prerequisites

Web Analytics supports Umbraco CMS 17.1 through 18.x. Your public site must already collect analytics with Vercel Web Analytics or Plausible. This package reads that data and does not add tracking to the public website.

You also need a read-only provider credential that can reach the Vercel project or Plausible site you want to connect.

2. Install the package

Add Web Analytics to the Umbraco web project:

dotnet add package TheBuilder.WebAnalytics

The package registers its services and backoffice extensions automatically. Build and deploy the Umbraco application as usual. The App_Plugins files ship as NuGet static web assets, so there is nothing to copy by hand.

3. Choose a provider and configure its credential

Choose the provider that already collects analytics for your site. Store its credential in secret configuration. Not appsettings.json, and never source control. Restart every Umbraco application instance after adding or rotating a credential.

Vercel Web Analytics

1. Create a Vercel token scoped to the account or team that owns the project.
2. Set it as WebAnalytics__Providers__Vercel__AccessToken in your hosting platform’s secret or app-setting store.
3. Copy the project ID, beginning with prj_.... For a team-owned project, also copy the team ID (team_...) or team slug.

For local development, set the token with .NET user secrets:

dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" --project path/to/Your.Umbraco.Web.csproj

Plausible

1. Create a Plausible Stats API key for the site you want to connect. Plausible Cloud requires a Business plan for Stats API access.
2. Set it as WebAnalytics__Providers__Plausible__AccessToken in your hosting platform’s secret or app-setting store.
3. Copy the Site ID, normally the registered domain, exactly as it appears in Plausible.
4. On a self-hosted instance, set its public base URL as WebAnalytics__Providers__Plausible__BaseUrl. The Umbraco application must be able to reach /api/v2/query there.

For local development, set the values with .NET user secrets:

dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
dotnet user-secrets set "WebAnalytics:Providers:Plausible:AccessToken" "your_stats_api_key" --project path/to/Your.Umbraco.Web.csproj
dotnet user-secrets set "WebAnalytics:Providers:Plausible:BaseUrl" "https://analytics.example.com/" --project path/to/Your.Umbraco.Web.csproj

4. Add the connection

As an administrator, open Settings → Web Analytics.

1. Select Add connection.
2. Choose Vercel or Plausible. The provider cannot be changed after creation.
3. Enter the provider identifier. That is a Vercel project ID and optional team, or a Plausible Site ID.
4. Select Save settings.

5. Test the connection

Select Test connection. The settings screen reports whether it found a shared credential or a connection override. It never displays or stores the token itself.

If the test fails, see troubleshooting. A panel missing from the dashboard later is a separate thing. It means the provider does not report that dimension, not that the connection broke.

6. Verify the Analytics dashboard

Open the Analytics section and check that totals and history load. Pick a date range you know had production traffic, otherwise an empty chart tells you nothing.

Next steps

• Understanding your reports explains what each metric, breakdown, and control on the dashboard means.
• Document analytics puts a report in the workspace of a mapped document, so editors see it while editing.