diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f750944..759ee35 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,10 +1,10 @@ # Contributing to Web Analytics -Thanks for your interest in improving Web Analytics for Umbraco. This guide covers the repository layout, how to set up a local development environment, and how to get a change merged. For how released package versions reach NuGet, see [docs/releasing.md](docs/releasing.md). +Thanks for helping improve Web Analytics for Umbraco. This guide covers the repository layout, how to set up a local development environment, and how to get a change merged. [docs/releasing.md](docs/releasing.md) covers how a released version reaches NuGet. ## Repository layout -This repository is a pnpm and .NET workspace. The most relevant folders: +The repository is a pnpm and .NET workspace. The folders you are most likely to touch: | Path | What it is | | --- | --- | @@ -17,9 +17,9 @@ This repository is a pnpm and .NET workspace. The most relevant folders: ## Prerequisites -- [.NET SDK 10.0](https://dotnet.microsoft.com/download): builds the package, sample, and tests. -- [Node.js 24](https://nodejs.org/): builds the backoffice client and the docs site. -- [pnpm](https://pnpm.io/) via [Corepack](https://nodejs.org/api/corepack.html). Run `corepack enable` once; the pinned pnpm version is resolved automatically from `package.json`. +- [.NET SDK 10.0](https://dotnet.microsoft.com/download) builds the package, sample, and tests. +- [Node.js 24](https://nodejs.org/) builds the backoffice client and the docs site. +- [pnpm](https://pnpm.io/) via [Corepack](https://nodejs.org/api/corepack.html). Run `corepack enable` once. The pinned pnpm version comes from `package.json`. Install the JavaScript dependencies from the repository root: @@ -29,7 +29,7 @@ pnpm install ## Build the backoffice client -The backoffice UI is a separate frontend build. A plain `dotnet build` of the sample does **not** rebuild it; the client is only built automatically when the NuGet package is packed. During development, build (or watch) the client yourself so its assets land in `wwwroot/App_Plugins/`: +The backoffice UI is a separate frontend build. A plain `dotnet build` of the sample does **not** rebuild it. Only packing the NuGet package triggers the client build, so during development you run it yourself. The assets land in `wwwroot/App_Plugins/`: ```sh pnpm client:build # one-off build @@ -44,9 +44,9 @@ The example project references the package directly, so it always uses your loca dotnet run --project samples/TheBuilder.WebAnalytics.Example ``` -On first launch Umbraco installs unattended and creates a local SQLite database. In `Development` the sample enables mock connections (`WebAnalytics:EnableMockConnections`), so the Analytics section shows deterministic sample data without any Vercel or Plausible credential. For live data, configure a real provider credential and connection exactly as a consumer would (see the [Quickstart](https://web-analytics.thebuilder.dk/quickstart)). +On first launch Umbraco installs unattended and creates a local SQLite database. In `Development` the sample turns on mock connections (`WebAnalytics:EnableMockConnections`), so the Analytics section shows deterministic sample data without any Vercel or Plausible credential. For live data, set up a real provider credential and connection the way a consumer would. See the [Quickstart](https://web-analytics.thebuilder.dk/quickstart). -For an efficient loop, run `pnpm client:watch` in one terminal and `dotnet run` in another. +Run `pnpm client:watch` in one terminal and `dotnet run` in another for the fastest loop. ## Run the tests and checks @@ -56,7 +56,7 @@ pnpm client:check # frontend type-chec dotnet test tests/TheBuilder.WebAnalytics.Tests/TheBuilder.WebAnalytics.Tests.csproj # .NET tests ``` -The .NET suite runs against Umbraco 17.1, the latest 17.x, and the latest 18.x in CI. Target a specific line locally by passing the version, for example `-p:UmbracoVersion=18.*`. +CI runs the .NET suite against Umbraco 17.1, the latest 17.x, and the latest 18.x. Target one line locally by passing the version, for example `-p:UmbracoVersion=18.*`. ## Work on the documentation site @@ -66,15 +66,15 @@ pnpm docs:build # production build pnpm docs:check # validate content and links ``` -The `apps/docs/` content is Markdown/MDX; see the files under `apps/docs/docs/` for structure. +The content in `apps/docs/` is Markdown and MDX. The files under `apps/docs/docs/` show the structure. ## Submitting a change 1. Create a branch for your change. -2. Keep pull requests focused, and update the relevant docs under `apps/docs/` when behaviour changes. -3. Run the frontend and .NET tests above so CI passes on the first try. The `Validate` workflow builds the client, runs both test suites across the supported Umbraco versions, and validates the NuGet package. -4. Open a pull request against `main` with a clear description of the change and its motivation. +2. Keep pull requests focused, and update the docs under `apps/docs/` when behaviour changes. +3. Run the frontend and .NET tests above so CI passes first time. The `Validate` workflow builds the client, runs both test suites across the supported Umbraco versions, and validates the NuGet package. +4. Open a pull request against `main` explaining what changed and why. ## Releasing -Publishing packages to NuGet is release-driven and documented separately in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are surfaced in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/). +Publishing to NuGet is release-driven and documented separately in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are mirrored in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/). diff --git a/PRODUCT.md b/PRODUCT.md index 20666d0..6f71f8b 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -38,7 +38,7 @@ Avoid the density, configuration burden, and specialist terminology of enterpris 2. **Native before novel.** Use Umbraco's interaction patterns, components, language, and visual hierarchy so the extension feels built in. 3. **Simple by default.** Present the common path first and progressively reveal configuration or reporting depth only when it becomes relevant. 4. **Trust through clarity.** Explain scope, limitations, credentials, errors, and data availability in plain language close to the affected control. -5. **Delight through fluency.** Earn delight through fast feedback, thoughtful defaults, and polished transitions—not decoration or added complexity. +5. **Delight through fluency.** Earn delight through fast feedback, thoughtful defaults, and polished transitions, not decoration or added complexity. ## Accessibility & Inclusion diff --git a/README.md b/README.md index 38dda18..a139b62 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ [![NuGet downloads](https://img.shields.io/nuget/dt/TheBuilder.WebAnalytics)](https://www.nuget.org/packages/TheBuilder.WebAnalytics) [![License](https://img.shields.io/github/license/thebuilder/web-analytics)](https://github.com/thebuilder/web-analytics/blob/main/LICENSE) -Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice. Editors can understand site-wide traffic and the performance of the page they are working on without leaving Umbraco. +Read the traffic your site already sends to Vercel Web Analytics or Plausible, and report it inside the Umbraco backoffice. Editors get the site-wide numbers and the numbers for the page they are editing, without leaving Umbraco. ![Web Analytics overview in the Umbraco backoffice](https://raw.githubusercontent.com/thebuilder/web-analytics/refs/heads/main/apps/docs/docs/screenshots/analytics-overview.png) -Web Analytics reads analytics already collected by the configured provider. It does **not** install, replace, or configure tracking on your public website. +Web Analytics is read-only. It does **not** install, replace, or configure tracking on your public website. ## Install @@ -18,7 +18,7 @@ Web Analytics supports Umbraco CMS 17.1 through 18.x. Add it to the Umbraco web dotnet add package TheBuilder.WebAnalytics ``` -Your public site must already collect analytics with Vercel or Plausible; this package reads that data and does not add tracking of its own. +Your public site must already collect analytics with Vercel or Plausible. This package reads that data and adds no tracking of its own. The package registers its services and backoffice extensions automatically. Then: @@ -40,15 +40,15 @@ Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is s ## Configure a credential -Provider credentials are always read from **server-side configuration** and are never stored in Umbraco or exposed to the browser. Keep them out of `appsettings.json` and source control. Use environment variables, [.NET user secrets](https://learn.microsoft.com/aspnet/core/security/app-secrets), or your hosting platform's secret store. Restart every application instance after adding or rotating a credential. +Provider credentials are always read from **server-side configuration**. They are never stored in Umbraco and never sent to the browser. Keep them out of `appsettings.json` and source control: use environment variables, [.NET user secrets](https://learn.microsoft.com/aspnet/core/security/app-secrets), or your hosting platform's secret store. Restart every application instance after adding or rotating a credential. -The configuration keys use the standard .NET double-underscore (`__`) delimiter for environment variables, or `:` for user secrets and JSON. +Configuration keys use the standard .NET double-underscore (`__`) delimiter in environment variables, or `:` in user secrets and JSON. ### Vercel 1. Create a [Vercel access token](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token) scoped to the account or team that owns the project. -2. Provide it as `WebAnalytics__Providers__Vercel__AccessToken`. -3. Note the project ID (`prj_...`), and the team ID (`team_...`) or slug for a team-owned project, to enter in Settings. +2. Set it as `WebAnalytics__Providers__Vercel__AccessToken`. +3. Note the project ID (`prj_...`), plus the team ID (`team_...`) or slug for a team-owned project. You enter those in Settings. ```sh dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" --project path/to/Your.Umbraco.Web.csproj @@ -57,9 +57,9 @@ dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" ### Plausible 1. Create a [Plausible Stats API key](https://plausible.io/docs/stats-api) for the site you want to connect. -2. Provide it as `WebAnalytics__Providers__Plausible__AccessToken`. -3. Note the Site ID (normally the registered domain) to enter in Settings. -4. For a self-hosted instance, set `WebAnalytics__Providers__Plausible__BaseUrl` to its public base URL (it must expose `/api/v2/query`). Cloud users keep the default `https://plausible.io/`. +2. Set it as `WebAnalytics__Providers__Plausible__AccessToken`. +3. Note the Site ID, normally the registered domain. You enter it in Settings. +4. On a self-hosted instance, set `WebAnalytics__Providers__Plausible__BaseUrl` to its public base URL, which must expose `/api/v2/query`. Cloud users keep the default `https://plausible.io/`. ```sh dotnet user-secrets set "WebAnalytics:Providers:Plausible:AccessToken" "your_stats_api_key" --project path/to/Your.Umbraco.Web.csproj @@ -68,7 +68,7 @@ dotnet user-secrets set "WebAnalytics:Providers:Plausible:BaseUrl" "https://anal ### Per-connection credential override (optional) -When one connection needs a different credential from the shared provider token, set a connection-specific override keyed by the connection GUID. The Settings screen shows the exact key. An override takes precedence over the shared provider credential. +When one connection needs a different credential from the shared provider token, set an override keyed by that connection's GUID. The Settings screen shows the exact key. An override wins over the shared provider credential. ```text WebAnalytics__ConnectionAccessTokens__{connection-guid} @@ -76,7 +76,7 @@ WebAnalytics__ConnectionAccessTokens__{connection-guid} ## Configuration -The Settings screen (**Settings → Web Analytics**) is the normal way to manage connections. Configuration precedence works as follows: +The Settings screen (**Settings → Web Analytics**) is the normal way to manage connections. Precedence works like this: - At startup the package reads the `WebAnalytics` section from server configuration. - Until an administrator first saves Settings, those non-secret values are the active configuration. @@ -85,7 +85,7 @@ The Settings screen (**Settings → Web Analytics**) is the normal way to manage Each application instance keeps its own in-memory report cache, so restart every instance after changing saved settings or credentials. -Besides the provider credentials above, these tunables live under the `WebAnalytics` section: +Besides the provider credentials above, the `WebAnalytics` section takes these options: | Key | Default | Description | | --- | --- | --- | @@ -93,13 +93,13 @@ Besides the provider credentials above, these tunables live under the `WebAnalyt | `DefaultRangeDays` | `30` | Initial reporting range, in days. Valid values are 1 to 730. | | `CacheDuration` | `00:05:00` | Per-instance in-memory cache duration. Valid from zero to one hour. | | `Connections` | `[]` | Provider connection definitions. The first becomes the initial default. | -| `EnableMockConnections` | `false` | Development-only deterministic connection presets. Never enable in production. | +| `EnableMockConnections` | `false` | Deterministic development-only connection presets. Never enable in production. | -Connections are normally created through the Settings screen, but they can also be bootstrapped from configuration for deployment automation. The [configuration reference](https://web-analytics.thebuilder.dk/reference/configuration) documents every connection key and the full precedence rules. +Connections are normally created through the Settings screen, but deployment automation can bootstrap them from configuration instead. The [configuration reference](https://web-analytics.thebuilder.dk/reference/configuration) documents every connection key and the full precedence rules. ## Documentation -The full documentation site covers everything above in more depth, plus the reporting UI and per-provider capabilities: +The documentation site covers everything above in more depth, plus the reporting UI and per-provider capabilities: - [Quickstart](https://web-analytics.thebuilder.dk/quickstart): install, connect a provider, and verify the dashboard. - [Understanding your reports](https://web-analytics.thebuilder.dk/guides/reports): what each metric, breakdown, and control means. @@ -108,4 +108,4 @@ The full documentation site covers everything above in more depth, plus the repo ## Contributing -Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository layout, local development setup (building the backoffice client, running the sample site, and running the tests), and how to submit a pull request. NuGet publishing guidance is in [docs/releasing.md](docs/releasing.md). GitHub Releases are the authoritative changelog and are surfaced in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/). +Contributions are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) covers the repository layout, local development setup, and how to open a pull request. [docs/releasing.md](docs/releasing.md) covers NuGet publishing. GitHub Releases are the authoritative changelog and are mirrored in the [documentation changelog](https://web-analytics.thebuilder.dk/changelog/). diff --git a/apps/docs/docs/guides/document-analytics.mdx b/apps/docs/docs/guides/document-analytics.mdx index 4439ca2..ca411ef 100644 --- a/apps/docs/docs/guides/document-analytics.mdx +++ b/apps/docs/docs/guides/document-analytics.mdx @@ -1,42 +1,42 @@ --- title: Document analytics -description: Map document roots and types to show reports automatically filtered to the selected published route. Document reports do not require global Analytics-section access. +description: Map document roots and types to show reports filtered to the selected published route. Document reports do not require global Analytics-section access. seo: image: /og/guides/document-analytics.png --- -Document mappings are optional. A connection without a mapping remains available in the global Analytics section but does not add a document workspace report. Document reports do not require global Analytics-section access. +Document mappings are optional. An unmapped connection still appears in the global Analytics section; it just does not add a report to any document. Document reports do not require access to the global Analytics section. ## Map an Umbraco site root -For each site that needs page-level reports, choose the root document in the connection's **Page analytics** settings. A document uses the connections from its nearest mapped ancestor; it does not use connections from merely any ancestor root. A mapped document report is automatically filtered to its selected published route. +For each site that needs page-level reports, pick the root document in the connection's **Page analytics** settings. A document uses the connections mapped to its *nearest* mapped ancestor, not every mapped ancestor above it. Its report covers that document's published route. -Then either enable all document types below that root or choose the specific document types that should show the Analytics workspace view. +Then either enable every document type below that root, or pick the specific types that should show the Analytics workspace view. ![A Vercel connection mapped to the Home document root](../screenshots/page-analytics-setup.png) -You can map more than one connection to the same root, for example when the site reports to both Vercel and Plausible. When more than one mapped connection supports the document type, the workspace shows a provider selector. Its selection is remembered in that browser for the mapped root, so choosing a provider for one site does not change another site's report. +More than one connection can map to the same root, which is what you want when a site reports to both Vercel and Plausible. The workspace then shows a provider selector. The browser remembers that choice per mapped root, so picking a provider for one site leaves the other sites alone. ## Choose the path scope -Document analytics initially reports only the selected document's published path. Enable **Include child paths** in the workspace header to report on that path and every path below it. This is useful for section or landing pages; leave it disabled to inspect only the selected page. +A document report starts at that document's own path. Enable **Include child paths** in the workspace header to take in everything below it too, which is what a section or landing page usually needs. Leave it off to look at the single page. ## When the workspace appears -A document shows its Analytics workspace view only when all of these conditions are met: +A document shows its Analytics workspace view only when all of this is true: - It is published and has a published route. -- Its nearest configured document root must specifically resolve to one or more connections, not merely any ancestor root. +- Its nearest mapped ancestor resolves to at least one connection. A mapped root further up the tree does not count. - Its document type is enabled for at least one of those connections. -- The current user can access the Content section and browse that document. +- The current user can reach the Content section and browse that document. -This lets an editor inspect the page they are working on without first finding it in a global report. +An editor can then inspect the page they are working on without hunting for it in a global report. ![The Analytics workspace on a mapped Home document](../screenshots/document-analytics-workspace.png) ## Multi-site example -Imagine one Umbraco installation with two site roots: +Take one Umbraco installation with two site roots: | Root document | Connection | Result | | --- | --- | --- | @@ -45,11 +45,11 @@ Imagine one Umbraco installation with two site roots: If a nested root is mapped too, it wins for documents below it because it is the nearest mapped ancestor. -You can also map both a Vercel project and a Plausible site to `Brand A`. Editors then choose the provider they need from the document workspace header. +You can also map both a Vercel project and a Plausible site to `Brand A`. Editors then pick the provider they want from the document workspace header. ## Permissions -Global and document analytics are intentionally separate: +Global and document access are separate on purpose: | User | Global Analytics | Document Analytics | Settings | | --- | --- | --- | --- | @@ -57,8 +57,8 @@ Global and document analytics are intentionally separate: | Analytics-section user | Yes | Only with Content access and document browse permission | No | | Editor with Content access and document browse permission | No | Yes, where mapped and published | No | -This means an editor can see analytics for a document they can browse without gaining access to global site reporting. +So an editor can read analytics for a document they can browse without being granted global site reporting. ## Troubleshoot a missing workspace -Check publication and route state first, then the nearest root mapping and document-type setting. If the workspace still does not appear, verify Content-section access and document browse permission. See [troubleshooting](/reference/troubleshooting) for the full symptom checklist. +Check publication and route state first, then the nearest root mapping and the document-type setting. If the workspace still does not appear, check Content-section access and browse permission for that document. [Troubleshooting](/reference/troubleshooting) has the full symptom checklist. diff --git a/apps/docs/docs/guides/reports.mdx b/apps/docs/docs/guides/reports.mdx index f9900cd..191551e 100644 --- a/apps/docs/docs/guides/reports.mdx +++ b/apps/docs/docs/guides/reports.mdx @@ -5,35 +5,32 @@ seo: image: /og/guides/reports.png --- -The Analytics section presents one dashboard per connection. This page explains what every part of it shows so you can move from a headline number to the context behind it. It describes the reading experience; for setup see the [quickstart](/quickstart), and for page-level reports see [document analytics](/guides/document-analytics). +The Analytics section shows one dashboard per connection. This page explains what every part of it means. For setup, see the [quickstart](/quickstart). For page-level reports, see [document analytics](/guides/document-analytics). ![The global Analytics dashboard in the Umbraco backoffice](../screenshots/analytics-overview.png) ## Dashboard controls -The header holds the two controls that shape every report below it. +Two controls in the header shape every report below them. | Control | What it does | | --- | --- | | **Analytics connection** | Switches between configured connections when more than one exists. Every metric, breakdown, and filter is scoped to the selected connection. | -| **Date range** | Choose a preset (Last 24 hours, Last 7 days, Last 30 days, Last 90 days, or Last 12 months) or set a custom range. The default range is 30 days and is configurable with `DefaultRangeDays`. | +| **Date range** | Pick a preset (Last 24 hours, Last 7 days, Last 30 days, Last 90 days, or Last 12 months) or set a custom range. The default is 30 days, changed with `DefaultRangeDays`. | -The range you pick also sets how history is grouped: hourly for a single day, daily up to a month, weekly up to a quarter, and monthly beyond that. +The range also decides how history is grouped. A single day is grouped hourly, up to a month daily, up to a quarter weekly, and anything longer monthly. ## Metrics and history -Two headline metrics sit at the top of the dashboard: +Two metrics sit at the top of the dashboard. **Visitors** counts the distinct people who arrived in the selected range. **Page views** counts the pages they loaded. -- **Visitors**: the number of distinct people who visited in the selected range. -- **Page views**: the total number of pages those visitors loaded. +Each metric is always compared against the preceding period of the same length. There is no toggle for it. The badge shows a signed percentage such as `+12%`, and reads in full as "12% more visitors than the previous 30 days". When the previous period has no data, the badge disappears instead of inventing a change. -Each metric shows its total and, automatically, a comparison against the immediately preceding period of the same length. There is no separate toggle. The badge reads as a signed percentage such as `+12%`, with a fuller description like "12% more visitors than the previous 30 days". When the previous period has no data to compare against, the badge is omitted rather than shown as a misleading change. - -Select a metric to plot it over time. The history chart uses the interval implied by the range, and the final segment is drawn as in-progress when the current period is not yet complete. +Select a metric to plot it over time. The chart uses the interval implied by the range, and draws the final segment as in-progress while the current period is still running. ## Breakdowns -Breakdowns rank the dimensions that make up your traffic. Each card lists the top contributors with a proportional bar and the metric value; **View all** opens a searchable dialog with the complete, filterable list. +Breakdowns rank the pages, sources, places, and devices behind those totals. Each card lists the top entries with a proportional bar and the metric value. **View all** opens a searchable dialog with the complete list. | Card | Shows | | --- | --- | @@ -43,36 +40,36 @@ Breakdowns rank the dimensions that make up your traffic. Each card lists the to | **Audience** | A tabbed card covering **Devices** and **Browsers**. | | **Operating systems** | Visitors grouped by operating system. | -UTM reporting is capability- and plan-dependent, so the **UTM** tab appears only when the selected connection can report those dimensions. On a plan-limited connection, the card explains that "UTM reporting availability depends on your analytics plan and reporting window." +The **UTM** tab appears only when the selected connection can report those dimensions, which depends on the provider and its plan. On a plan-limited connection the card says so, rather than showing an empty tab. ![The full operating-system breakdown opened from its card](../screenshots/operating-system-details.png) ## Events -When the provider records custom events, the dashboard adds an **Events** panel listing each event and its total. Select an event and choose **View all events** to open the full, searchable list, then open an event to drill into its properties. +When the provider records custom events, the dashboard adds an **Events** panel listing each event and its total. **View all events** opens the full searchable list, and opening an event drills into its properties. ![Custom event details with a property drill-down](../screenshots/custom-event-details.png) -Event-property drill-downs let you break a single event down by a recorded property, for example which URLs an outbound-link event pointed to. For Plausible, configure the property names you want to explore under the connection's event-property settings; see the [Plausible reference](/providers/plausible#event-properties). +A property drill-down splits one event by a recorded property, for example which URLs an outbound-link event pointed at. On Plausible, name the properties you want to explore in the connection's event-property settings. See the [Plausible reference](/providers/plausible#event-properties). ## Feature flags -For Vercel connections that report feature flags, a **Flags** panel lists each flag with its totals, and **View all flags** opens the complete list. Plausible does not expose feature flags, so the panel is hidden for Plausible connections rather than shown as an error. +On a Vercel connection that reports feature flags, a **Flags** panel lists each flag with its totals, and **View all flags** opens the complete list. Plausible has no feature flags, so the panel does not appear on a Plausible connection. ![Audience, events, and feature-flag panels](../screenshots/audience-events-and-flags.png) ## Filtering and drill-downs -Any breakdown row can become a filter. Hover or keyboard-focus a row to reveal **Filter by this value**; applying it narrows every report on the dashboard to that value, for example only visitors from one country, or only one referrer. +Any breakdown row can become a filter. Hover or keyboard-focus a row to reveal **Filter by this value**. Applying it narrows every report on the dashboard, for example to visitors from one country, or traffic from one referrer. -Active filters appear as a **Filters** group beneath the header. Remove an individual filter from its chip, or choose **Clear all** to return to the unfiltered view. Filters, the selected date range, and the chosen breakdown tabs are reflected in the dashboard URL, so a filtered view can be bookmarked or shared. +Active filters appear as a **Filters** group beneath the header. Remove one from its chip, or choose **Clear all** to go back to the unfiltered view. The URL carries the filters, the date range, and the selected breakdown tabs, so you can bookmark or share a filtered view. ![Active filters applied to the dashboard](../screenshots/analytics-filters.png) :::note[Provider differences are expected] -The interface adapts to what each provider supports instead of showing errors. Vercel does not support applying an event or event-property filter to a global report or choosing the ordering metric for a breakdown; Plausible supports both but has no feature flags. A hidden panel means the provider does not offer that capability, not a failed connection. See the [Vercel](/providers/vercel#capabilities) and [Plausible](/providers/plausible#capabilities) references for the exact per-provider capabilities. +The interface adapts to what each provider supports instead of showing errors. Vercel cannot apply an event or event-property filter to a global report, and cannot change a breakdown's ordering metric. Plausible does both, but has no feature flags. A hidden panel means the provider does not offer that capability, not that the connection failed. The [Vercel](/providers/vercel#capabilities) and [Plausible](/providers/plausible#capabilities) references list the exact per-provider capabilities. ::: ## Reports on a document -The same metrics, history, and breakdowns appear in the Analytics workspace on a mapped document, automatically scoped to that document's published route. The document view adds an **Include child paths** toggle to report on either the single page or the whole section beneath it. See [document analytics](/guides/document-analytics) for mapping and permissions. +The same metrics, history, and breakdowns appear in the Analytics workspace on a mapped document, scoped to that document's published route. The document view adds an **Include child paths** toggle, switching between the single page and the whole section beneath it. See [document analytics](/guides/document-analytics) for mapping and permissions. diff --git a/apps/docs/docs/overview.mdx b/apps/docs/docs/overview.mdx index f733baf..de8b4db 100644 --- a/apps/docs/docs/overview.mdx +++ b/apps/docs/docs/overview.mdx @@ -1,6 +1,6 @@ --- title: Overview -description: Bring the analytics your site already collects into Umbraco, giving editors useful traffic reports in the backoffice and on mapped documents. +description: Bring the analytics your site already collects into Umbraco, giving editors traffic reports in the backoffice and on mapped documents. seo: image: /og/overview.png sidebar: @@ -9,36 +9,36 @@ sidebar: ## Supported providers -Choose the reference for the analytics provider your site already has. +Pick the reference for your provider. - Reference connection fields, team projects, feature flags, and Vercel-specific errors. + Connection fields, team projects, feature flags, and Vercel-specific errors. - Reference Cloud and self-hosted connections, event properties, and Plausible-specific errors. + Cloud and self-hosted connections, event properties, and Plausible-specific errors. -:::tip[Ready to connect your analytics?] -[Follow the Quickstart](/quickstart) to install the package, connect the provider your site already uses, and verify the dashboard. +:::tip[Setting up for the first time] +[Follow the Quickstart](/quickstart) to install the package, connect your provider, and verify the dashboard. ::: ![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png) ## What you get -- **Traffic reports.** Explore visitors, page views, trends, referrers, campaigns, countries, devices, and pages. [Understand what each report means](/guides/reports). -- **Document context.** Show analytics in mapped published document workspaces, scoped to the document's route. -- **Useful detail.** Use date comparisons, filters, and drill-downs to move from a headline number to useful context. -- **Multi-site support.** Add more than one connection to an Umbraco installation. -- **Private credentials.** Keep provider access in server-side application configuration, never in the browser or Umbraco content. -- **No tracking changes.** Read provider-collected data without installing, replacing, or configuring public-site tracking. +- **Traffic reports.** Visitors, page views, history, pages, referrers, campaigns, countries, devices, browsers, and operating systems. [What each report means](/guides/reports). +- **Document context.** Mapped published documents get their own Analytics view, filtered to that document's route. +- **Comparison and filtering.** Each metric shows how it moved against the period before it. Any breakdown row can become a filter across the whole dashboard. +- **Multi-site support.** One Umbraco installation can hold several Vercel projects and Plausible sites at once. +- **Private credentials.** Provider tokens stay in server-side configuration. They never reach the browser or Umbraco content. +- **No tracking changes.** The package reads what your provider already collects. It never installs, replaces, or configures tracking on the public site. ## Compatibility -Web Analytics supports Umbraco CMS 17.1 through 18.x. [Vercel Web Analytics](/providers/vercel) and [Plausible](/providers/plausible) both provide core reports, event lists and details, and event-property drill-downs. The interface hides provider capabilities that are not available instead of presenting them as errors. +Web Analytics supports Umbraco CMS 17.1 through 18.x. [Vercel](/providers/vercel) and [Plausible](/providers/plausible) both report core traffic, event lists and details, and event-property drill-downs. They diverge past that point, and each provider page lists exactly what its connection can do. -## Need the details? +## Reference -The [configuration reference](/reference/configuration) explains configuration precedence, credentials, cache behaviour, and every supported option. Use [troubleshooting](/reference/troubleshooting) for missing access, connection errors, empty reports, and multi-instance deployment issues. +The [configuration reference](/reference/configuration) lists every supported option, plus how precedence, credentials, and caching work. [Troubleshooting](/reference/troubleshooting) starts from the symptom: missing access, a connection error, an empty report, or settings that differ between instances. diff --git a/apps/docs/docs/providers/plausible.mdx b/apps/docs/docs/providers/plausible.mdx index 676cd2e..4088638 100644 --- a/apps/docs/docs/providers/plausible.mdx +++ b/apps/docs/docs/providers/plausible.mdx @@ -1,21 +1,21 @@ --- title: Plausible -description: Reference for Plausible Cloud and self-hosted connections, including fields, endpoint requirements, event properties, reports, and common errors. +description: Plausible Cloud and self-hosted connection fields, endpoint requirements, event properties, capabilities, and common errors. seo: image: /og/providers/plausible.png --- -The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Plausible-specific requirements, connection fields, and capabilities. +The [quickstart](/quickstart) covers first-time setup. This page is for looking up Plausible-specific requirements, fields, and capabilities. ## About Plausible -[Plausible](https://plausible.io/) is a privacy-friendly, open-source web analytics platform available as a hosted service or self-hosted instance. This package reads the reports Plausible already collects and makes them available in Umbraco; it does not add tracking to the public site. +[Plausible](https://plausible.io/) is an open-source analytics platform, run either as a hosted service or on your own instance. This package reads what Plausible has already collected and shows it in Umbraco. It does not add tracking to the public site. ## Cloud and self-hosted requirements -The connection needs a [Plausible Stats API key](https://plausible.io/docs/stats-api) in server-side configuration. Plausible Cloud's Stats API requires a Business plan. +The connection needs a [Plausible Stats API key](https://plausible.io/docs/stats-api) in server-side configuration. On Plausible Cloud, the Stats API requires a Business plan. -Self-hosted Plausible is supported when the instance exposes the v2 Stats API query endpoint. Its public base URL must use HTTP or HTTPS and cannot include user information, a query, or a fragment. The Umbraco application must be able to reach its `/api/v2/query` endpoint. +A self-hosted instance works as long as it exposes the v2 Stats API query endpoint. Its public base URL must use HTTP or HTTPS and cannot carry user information, a query, or a fragment. The Umbraco application must be able to reach `/api/v2/query` there. ## Connection fields @@ -29,7 +29,7 @@ Add these values in **Settings → Web Analytics**. For connection errors such a ## Event properties -Add custom event-property names when the site records properties beyond Plausible's built-in fields. You can configure up to 20 names, each with at most 100 characters. +Add custom event-property names when the site records properties beyond Plausible's built-in fields. Up to 20 names, each at most 100 characters. | Property | Built in for | | --- | --- | @@ -38,6 +38,6 @@ Add custom event-property names when the site records properties beyond Plausibl ## Capabilities -Plausible connections provide core totals, history, traffic breakdowns, UTM dimensions, event lists, event-property drill-downs, global event and event-property filtering, and selectable breakdown ordering. +Plausible connections report core totals, history, traffic breakdowns, UTM dimensions, event lists, event-property drill-downs, global event and event-property filtering, and selectable breakdown ordering. -Plausible does not expose Vercel feature flags, so the flags panel is hidden for this provider. +Plausible has no feature flags, so the backoffice hides that panel on a Plausible connection. diff --git a/apps/docs/docs/providers/vercel.mdx b/apps/docs/docs/providers/vercel.mdx index 5dfd299..7eb9cf8 100644 --- a/apps/docs/docs/providers/vercel.mdx +++ b/apps/docs/docs/providers/vercel.mdx @@ -1,19 +1,19 @@ --- title: Vercel Web Analytics -description: Reference for Vercel Web Analytics connection fields, reports, team projects, credential overrides, and common connection errors. +description: Vercel Web Analytics connection fields, team projects, credential overrides, capabilities, and common connection errors. seo: image: /og/providers/vercel.png --- -The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Vercel-specific requirements, connection fields, and capabilities. +The [quickstart](/quickstart) covers first-time setup. This page is for looking up Vercel-specific requirements, fields, and capabilities. ## About Vercel Web Analytics -[Vercel Web Analytics](https://vercel.com/docs/analytics) is Vercel's analytics product for understanding traffic to a Vercel project. This package reads the reports Vercel already collects and makes them available in Umbraco; it does not add tracking to the public site. +[Vercel Web Analytics](https://vercel.com/docs/analytics) reports traffic to a Vercel project. This package reads what Vercel has already collected and shows it in Umbraco. It does not add tracking to the public site. ## Requirements -The connection needs a [Vercel access token](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token) scoped to the account or team that owns the project. Configure the token server-side; it is never stored in Umbraco. +The connection needs a [Vercel access token](https://vercel.com/kb/guide/how-do-i-use-a-vercel-api-access-token) scoped to the account or team that owns the project. The token lives in server-side configuration and is never stored in Umbraco. ## Connection fields @@ -27,16 +27,16 @@ Add these values in **Settings → Web Analytics**. For connection errors such a ## Capabilities -Vercel connections provide core totals, history, traffic breakdowns, UTM dimensions, event lists, event-property drill-downs, and feature flags. +Vercel connections report core totals, history, traffic breakdowns, UTM dimensions, event lists, event-property drill-downs, and feature flags. -Vercel does not support applying an event or event-property filter to a global report, and does not support selecting the ordering metric for a breakdown. The backoffice adapts to those capabilities. +Vercel cannot apply an event or event-property filter to a global report, and cannot change the metric a breakdown is ordered by. The backoffice hides both controls on a Vercel connection. ## Connection-specific credential -Use a connection override only when this connection needs a different credential from the shared Vercel token. The Settings UI shows the exact secret key, in the form: +Use a connection override only when one connection needs a different credential from the shared Vercel token. The Settings screen shows the exact secret key: ```text WebAnalytics__ConnectionAccessTokens__{connection-guid} ``` -The override remains server-side and takes precedence over the shared provider credential. +The override stays server-side and wins over the shared provider credential. diff --git a/apps/docs/docs/quickstart.mdx b/apps/docs/docs/quickstart.mdx index 44ab5d9..c20a107 100644 --- a/apps/docs/docs/quickstart.mdx +++ b/apps/docs/docs/quickstart.mdx @@ -5,13 +5,13 @@ seo: image: /og/quickstart.png --- -This is the complete first-time setup path for Web Analytics. Stay on this page from package installation to a working 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. +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 access the Vercel project or Plausible site you want to connect. +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 @@ -21,16 +21,16 @@ 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; NuGet static web assets include the package's `App_Plugins` files. +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 application secret configuration, not `appsettings.json` and never source control. Restart every Umbraco application instance after adding or rotating a 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. Configure it as `WebAnalytics__Providers__Vercel__AccessToken` in your hosting platform's secret or app-setting facility. +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: @@ -43,9 +43,9 @@ dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" ### 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. Configure it as `WebAnalytics__Providers__Plausible__AccessToken` in your hosting platform's secret or app-setting facility. +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. If you use a self-hosted instance, configure its public base URL as `WebAnalytics__Providers__Plausible__BaseUrl`. It must expose `/api/v2/query` to the Umbraco application. +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: @@ -61,22 +61,22 @@ 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: a Vercel project ID and optional team, or a Plausible Site ID. +3. Enter the provider identifier. That is a Vercel project ID and optional team, or a Plausible Site ID. 4. Select **Save settings**. ![A Plausible connection in the Web Analytics settings screen](./screenshots/settings.png) ## 5. Test the connection -Select **Test connection** and review the credential status. The settings screen reports whether it detected a shared credential or a connection override; it does not display or store a token. +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, use [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection. +If the test fails, see [troubleshooting](/reference/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 global **Analytics** section. Check that totals and history load, then use a known date range with recorded production traffic. +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 -- [Understand your reports](/guides/reports) to learn what each metric, breakdown, and control on the dashboard means. -- Configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document. +- [Understanding your reports](/guides/reports) explains what each metric, breakdown, and control on the dashboard means. +- [Document analytics](/guides/document-analytics) puts a report in the workspace of a mapped document, so editors see it while editing. diff --git a/apps/docs/docs/reference/configuration.mdx b/apps/docs/docs/reference/configuration.mdx index 915c86b..b94b2b7 100644 --- a/apps/docs/docs/reference/configuration.mdx +++ b/apps/docs/docs/reference/configuration.mdx @@ -1,24 +1,24 @@ --- title: Configuration reference -description: Before the first Settings save, server configuration supplies non-secret values; afterward, Umbraco settings take precedence. +description: Every WebAnalytics option, plus how server configuration and Umbraco-stored settings take precedence over each other. seo: image: /og/reference/configuration.png --- ## Configuration lifecycle and precedence -Before an administrator first saves Settings → Web Analytics, server configuration supplies the active non-secret values. After that first save, Umbraco-stored non-secret connection settings become the source of truth. +Server configuration supplies the non-secret values until an administrator first saves Settings → Web Analytics. After that save, the settings stored in Umbraco take over. 1. At startup, the package reads `WebAnalytics` server configuration. 2. Until an administrator saves **Settings → Web Analytics**, those non-secret values are the active configuration. 3. After the first settings save, non-secret connection settings are stored in Umbraco and become the source of truth. 4. Provider credentials always remain in server-side configuration. A connection-specific credential overrides the shared provider credential. -Each Umbraco application instance keeps its own in-memory report cache. Restart every instance after changing saved settings or credentials so every process uses the same configuration. +Each Umbraco application instance keeps its own in-memory report cache. Restart every instance after changing saved settings or credentials, otherwise processes disagree about the configuration. -## Safe configuration-only example +## Configuration-only example -Use configuration-only setup when deployment automation must bootstrap connections. Do not put access tokens in this file. +Bootstrap connections this way when deployment automation has to create them. Keep access tokens out of this file. ```json { @@ -52,8 +52,8 @@ For Plausible, use `"Provider": "Plausible"` and set `SiteId` instead of `Projec | Key | Default | Description | | --- | --- | --- | | `Enabled` | `true` | Enables the Analytics section and configured document workspace views. | -| `EnableMockConnections` | `false` | Enables deterministic development-only connection presets. Never enable in production. | -| `DefaultRangeDays` | `30` | Initial reporting range. Valid values are 1–730. | +| `EnableMockConnections` | `false` | Turns on deterministic development-only connection presets. Never enable in production. | +| `DefaultRangeDays` | `30` | Initial reporting range, in days. Valid values are 1 to 730. | | `CacheDuration` | `00:05:00` | Per-instance in-memory cache duration. Valid from zero to one hour. | | `Connections` | `[]` | Provider connection definitions. The first becomes the initial default. | | `ConnectionAccessTokens` | Empty | Optional connection-specific credential overrides, keyed by connection GUID. An override takes precedence over the shared provider credential. Set one with `WebAnalytics__ConnectionAccessTokens__{connection-guid}`. | @@ -74,12 +74,12 @@ For Plausible, use `"Provider": "Plausible"` and set `SiteId` instead of `Projec | `EventPropertyNames` | Plausible | Custom properties to discover and drill into. | | `EnableEvents` | All | Whether to show provider-supported custom events. | | `EnableFlags` | Vercel | Whether to show provider-supported feature flags. | -| `MockScenario` | Development only | Selects deterministic mock report data when mock connections are enabled: `Complete`, `Utm`, `Flags`, or `Events`. | +| `MockScenario` | Development only | Picks which mock report data to serve when mock connections are enabled. One of `Complete`, `Utm`, `Flags`, or `Events`. | | `DocumentRootKeys` | All | Root document GUIDs mapped to this connection. More than one connection may map the same root; editors select the provider in the document workspace. | | `EnableAllDocumentTypes` | All | Enables document analytics for every type below a mapped root. | | `EnabledDocumentTypeKeys` | All | Restricts document analytics to specific document-type GUIDs. | | `EnabledDocumentTypes` | All | Document-type aliases for configuration-only bootstrapping. | :::warning -Keep provider credentials out of `appsettings.json` and source control. Use environment variables, user secrets, or the secret facility supplied by the hosting platform. +Keep provider credentials out of `appsettings.json` and source control. Use environment variables, .NET user secrets, or your hosting platform's secret store. ::: diff --git a/apps/docs/pages/index.astro b/apps/docs/pages/index.astro index 6f57966..c8bcc1d 100644 --- a/apps/docs/pages/index.astro +++ b/apps/docs/pages/index.astro @@ -33,40 +33,40 @@ const providers = [ name: "Vercel Web Analytics", href: "/providers/vercel", detail: - "Connect a Vercel project with a scoped access token. Read visitors, page views, routes, and campaigns without ever storing the token in Umbraco.", + "Connect a Vercel project with a scoped access token. Visitors, page views, pages, campaigns, custom events, and feature flags, with the token never stored in Umbraco.", }, { name: "Plausible", href: "/providers/plausible", detail: - "Point at Plausible Cloud or a self-hosted instance with a Stats API key. Explore events, properties, and privacy-friendly traffic from the backoffice.", + "Point at Plausible Cloud or a self-hosted instance with a Stats API key. Adds global event filtering and custom event properties on top of the core reports.", }, ]; const features = [ { title: "Traffic reports", - body: "Visitors, page views, trends, acquisition, audience, pages, routes, and campaigns: the headline numbers, one click away.", + body: "Visitors and page views over time, plus pages, referrers, campaigns, countries, devices, browsers, and operating systems.", icon: "chart", }, { title: "Document context", - body: "See analytics inside a published document's workspace, automatically scoped to that document's route.", + body: "An Analytics view inside a published document's workspace, filtered to that document's route. Toggle child paths to cover the whole section.", icon: "doc", }, { - title: "Drill into detail", - body: "Compare date ranges, apply filters, and follow a headline number down to the context behind it.", + title: "Compare and filter", + body: "Each metric shows how it moved against the period before it. Turn any breakdown row into a filter across the whole dashboard.", icon: "filter", }, { title: "Multi-site support", - body: "Add more than one connection to a single Umbraco installation and switch between them.", + body: "Connect several Vercel projects and Plausible sites to one Umbraco installation and switch between them.", icon: "layers", }, { title: "Private credentials", - body: "Provider access lives in server-side configuration, never in the browser, never in Umbraco content.", + body: "Tokens live in server-side configuration. They are never written to Umbraco and never sent to the browser.", icon: "lock", }, { @@ -108,7 +108,7 @@ const steps = [ page={{ title: "Web Analytics for Umbraco", description: - "Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice: site-wide and page-level traffic where editors already work.", + "Vercel Web Analytics and Plausible reports inside the Umbraco backoffice, site-wide and per page, with no new tracking on your public site.", route: "/", }} > @@ -131,10 +131,10 @@ const steps = [ right inside Umbraco.

- Web Analytics brings Vercel Web Analytics and Plausible reports into the - backoffice. Editors understand site-wide traffic and the performance of - the page they're working on, without leaving Umbraco or learning another - dashboard. + Web Analytics reads the traffic your site already sends to Vercel or + Plausible and reports it in the backoffice. Editors see the site-wide + numbers and how the page they're editing is doing, without leaving + Umbraco.

Get started @@ -183,9 +183,9 @@ const steps = [ {/* Trust line */}

- Reads the analytics you already collect.{" "} - No new tracking added to your public site, no credentials in the browser, - no separate platform to learn. + Nothing new on your public site.{" "} + Web Analytics only reads. Tracking on your site stays exactly as you set + it up, and the token never leaves server-side configuration.

@@ -193,8 +193,8 @@ const steps = [
-

Works with the analytics you already run

-

Bring your existing provider. Reporting depth adapts to what each one exposes; the editorial experience stays the same.

+

Bring your own provider

+

Point it at a Vercel project or a Plausible site. Where a provider can't report something, the backoffice hides that panel instead of showing an error.

{providers.map((provider, index) => ( @@ -216,8 +216,8 @@ const steps = [
-

Insight where editors already work

-

The traffic signals that matter for the current editorial task, within immediate reach, with nothing more to configure.

+

What's in the dashboard

+

One dashboard per connection, and the same reports again on any document you map.

{features.map((feature, index) => ( @@ -256,10 +256,10 @@ const steps = [

Page performance, next to the content

- Map a document root and Web Analytics adds an Analytics workspace to - published documents, automatically filtered to that page's route. - Editors see how the page they're editing actually performs, without - hunting for it in a separate report. + Map a document root and every published document below it gains an + Analytics workspace, filtered to its own route. It follows Umbraco's + Content permissions, so an editor who can browse a page can read its + numbers without access to the global Analytics section.

Read the guide @@ -285,7 +285,7 @@ const steps = [

Connected in three steps

-

From package install to a working dashboard, the whole path lives on one quickstart page.

+

All three steps, and what to check afterwards, are on the quickstart page.

    @@ -317,8 +317,8 @@ const steps = [
    -

    Bring analytics into the editorial workflow

    -

    Install the package, connect the provider your site already uses, and give editors traffic context where they manage content.

    +

    Put the numbers where the content is

    +

    Install the package, point it at your Vercel project or Plausible site, and editors get their traffic reports without a second login.

    Get started Umbraco Marketplace diff --git a/apps/docs/umbraco-package.ts b/apps/docs/umbraco-package.ts index 89b2b9c..9730287 100644 --- a/apps/docs/umbraco-package.ts +++ b/apps/docs/umbraco-package.ts @@ -3,7 +3,7 @@ import { defineUmbracoPackage } from "@thebuilder/umbraco-docs"; export const webAnalyticsPackage = defineUmbracoPackage({ id: "thebuilder.webanalytics", name: "Web Analytics", - summary: "Connect analytics providers and bring site-wide and page-level insights into the Umbraco backoffice.", + summary: "Report the traffic your site already sends to Vercel Web Analytics or Plausible inside the Umbraco backoffice, site-wide and per page.", links: { docs: "https://web-analytics.thebuilder.dk/", nuget: "https://www.nuget.org/packages/TheBuilder.WebAnalytics", diff --git a/docs/releasing.md b/docs/releasing.md index 8c02630..c400c59 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -20,7 +20,7 @@ GitHub Releases are the authoritative changelog and the release tag is the singl 3. Select **Set as a pre-release**. 4. Publish the release. -The workflow publishes the prerelease package to nuget.org. NuGet package versions are immutable, so increment the prerelease number for every publish. +The workflow publishes the prerelease package to nuget.org. NuGet versions are immutable, so bump the prerelease number for every publish. ## Publish a stable release @@ -29,6 +29,6 @@ The workflow publishes the prerelease package to nuget.org. NuGet package versio 3. Ensure **Set as a pre-release** is not selected. 4. Publish the release. -Publishing the release triggers the workflow. It removes the optional leading `v`, verifies the client, .NET projects, sample, docs, generated Umbraco manifest, NuGet metadata, and release-notes URL, then publishes that exact verified artifact to nuget.org with a short-lived OIDC credential. For example, `v0.1.0-preview.1` produces version `0.1.0-preview.1` everywhere and links its NuGet release notes to that GitHub Release. +Publishing the release triggers the workflow. It strips the optional leading `v`, verifies the client, .NET projects, sample, docs, generated Umbraco manifest, NuGet metadata, and release-notes URL, then pushes that exact verified artifact to nuget.org with a short-lived OIDC credential. Tag `v0.1.0-preview.1` produces version `0.1.0-preview.1` everywhere, with its NuGet release notes pointing at that GitHub Release. The GitHub Release type and version must agree: prereleases require a prerelease version, and stable releases require a stable version. diff --git a/umbraco-marketplace-readme.md b/umbraco-marketplace-readme.md index 5b94d88..2e70648 100644 --- a/umbraco-marketplace-readme.md +++ b/umbraco-marketplace-readme.md @@ -1,15 +1,37 @@ ![Web Analytics overview in the Umbraco backoffice](https://raw.githubusercontent.com/thebuilder/web-analytics/refs/heads/main/apps/docs/docs/screenshots/analytics-overview.png) -Web Analytics brings analytics from [**Vercel Web Analytics**](https://vercel.com/docs/analytics) and [**Plausible**](https://plausible.io/docs/stats-api) into the Umbraco backoffice, giving editors useful traffic and content insights without sending them to another tool. +Web Analytics reads the traffic your site already sends to [Vercel Web Analytics](https://vercel.com/docs/analytics) or [Plausible](https://plausible.io/docs/stats-api) and reports it inside the Umbraco backoffice. It adds no tracking to your public site. -## Key features +## What it does -- **Site-wide analytics:** Follow visitors, page views, traffic trends, audience, referrers, campaigns, and provider-supported activity. -- **Page-level insight:** Open analytics on a published document to see data automatically filtered to that page's route. -- **Useful comparisons:** Compare date ranges and drill into the audience, content, and activity behind the headline numbers. -- **Multi-provider and multi-site support:** Connect Umbraco sites to Vercel or Plausible and bring them together in one Analytics section. -- **Capability-aware interface:** Panels and drill-downs adapt to the data available from each provider. +- The Analytics section reports visitors, page views, and traffic history, broken down by page, referrer, campaign, country, device, browser, and operating system. +- Every metric shows how it moved against the period before it. Click any breakdown row to filter the whole dashboard by it. +- Published documents get their own Analytics view, filtered to that document's route, so an editor can check one page without opening another tool. +- One Umbraco installation can hold several Vercel projects and Plausible sites at once. +- The backoffice hides panels a provider cannot fill, so a missing capability never looks like a broken connection. +- Provider tokens stay in server-side configuration. They are never stored in Umbraco and never sent to the browser. -Web Analytics fits into the Umbraco permissions and editorial workflows teams already know, making analytics available where content decisions happen. +Document reports follow Umbraco's existing Content permissions, so an editor who can browse a page can read its analytics without being granted the global Analytics section. -Ready to bring your analytics into the backoffice? See the [installation and configuration guide](https://web-analytics.thebuilder.dk/). +## Install + +Needs Umbraco CMS 17.1 through 18.x, and a public site already collecting analytics with Vercel or Plausible. Plausible Cloud serves the Stats API on Business plans only. + +```sh +dotnet add package TheBuilder.WebAnalytics +``` + +Services and backoffice extensions register themselves, so there is nothing else to wire up. + +## Set up a connection + +1. Put a read-only provider credential in server-side configuration, as either `WebAnalytics__Providers__Vercel__AccessToken` or `WebAnalytics__Providers__Plausible__AccessToken`. Use environment variables, .NET user secrets, or your host's secret store. Never `appsettings.json`. +2. Restart the application so it picks up the credential. +3. As an administrator, open **Settings → Web Analytics** and add a connection. Enter your Vercel project ID (`prj_...`) or your Plausible site ID. +4. Select **Test connection**, then open the **Analytics** section. + +To give editors page-level reports as well, map a document root in the connection's **Page analytics** settings. + +## Documentation + +[web-analytics.thebuilder.dk](https://web-analytics.thebuilder.dk/) has the full quickstart, a guide to reading the reports, the configuration reference, and troubleshooting. diff --git a/umbraco-marketplace.json b/umbraco-marketplace.json index 228d2da..a6c81c5 100644 --- a/umbraco-marketplace.json +++ b/umbraco-marketplace.json @@ -9,7 +9,7 @@ }, "Category": "Analytics & Insights", "Title": "Web Analytics", - "Description": "Connect web analytics providers and bring site-wide and page-level insights into the Umbraco backoffice.", + "Description": "Report the traffic your site already sends to Vercel Web Analytics or Plausible inside the Umbraco backoffice, site-wide and per page.", "DocumentationUrl": "https://web-analytics.thebuilder.dk/", "IssueTrackerUrl": "https://github.com/thebuilder/web-analytics/issues", "LicenseTypes": [ @@ -23,15 +23,15 @@ }, { "ImageUrl": "https://raw.githubusercontent.com/thebuilder/web-analytics/refs/heads/main/apps/docs/docs/screenshots/settings.png", - "Caption": "Set up Vercel and Plausible connections, confirm shared credentials, and configure reporting from the Settings section." + "Caption": "Add Vercel and Plausible connections, confirm the credential was found, and map document roots from the Settings section." }, { "ImageUrl": "https://raw.githubusercontent.com/thebuilder/web-analytics/refs/heads/main/apps/docs/docs/screenshots/audience-events-and-flags.png", - "Caption": "Understand audience devices and locations alongside provider-supported events and features." + "Caption": "Break traffic down by device and browser, next to custom events and Vercel feature flags." }, { "ImageUrl": "https://raw.githubusercontent.com/thebuilder/web-analytics/refs/heads/main/apps/docs/docs/screenshots/custom-event-details.png", - "Caption": "Drill into event activity and compare visitors with total events when supported by the provider." + "Caption": "Drill into a custom event and its recorded properties, comparing visitors against total events." } ], "Tags": [