diff --git a/apps/docs/blume.config.ts b/apps/docs/blume.config.ts index cdb9507..df440a1 100644 --- a/apps/docs/blume.config.ts +++ b/apps/docs/blume.config.ts @@ -29,6 +29,7 @@ export default defineConfig({ { label: "Changelog", path: "/changelog", href: "/changelog" }, ], }, + redirects: [{ from: "/getting-started", to: "/quickstart", status: 301 }], deployment: { output: "static", site: "https://umbraco-web-analytics.vercel.app", diff --git a/apps/docs/docs/getting-started.mdx b/apps/docs/docs/getting-started.mdx deleted file mode 100644 index df264be..0000000 --- a/apps/docs/docs/getting-started.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Getting started -description: Create a read-only credential with account or site access, store it in application or hosting-platform secret settings, restart every instance, and verify the connection. ---- - -This guide covers the shared path for both providers. Provider-specific identifiers and capabilities are covered in the [Vercel](/providers/vercel) and [Plausible](/providers/plausible) guides. - -## 1. Install the package - -Add Web Analytics to the Umbraco web project: - -```sh -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. - -## 2. Choose a provider, configure its secret, and restart - -Create a read-only credential with access to the provider account or site being connected. Add it to the application's secret configuration—not `appsettings.json` and never source control. Restart every Umbraco application instance after adding or rotating the credential. - -Choose the provider that already collects your site analytics. Use the [Vercel](/providers/vercel) or [Plausible](/providers/plausible) guide for its credential, connection identifier, and any provider-specific setup. - -For local development, use either a shell environment variable or .NET user secrets: - - - -```sh Vercel -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 -``` - -```sh Plausible -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 -``` - - - -Use the equivalent secret or app-setting facility in your hosting platform. - -## 3. Add and test 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. -4. Select **Save settings**, then **Test connection**. -5. 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. - -![A Plausible connection in the Web Analytics settings screen](./screenshots/settings.png) - -## 4. Verify the dashboard - -Open the global **Analytics** section. Check that totals and history load, then use a known date range with recorded production traffic. - -If reports do not load, start with [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection. - -## Next step - -Configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document. diff --git a/apps/docs/docs/index.mdx b/apps/docs/docs/index.mdx index f28796d..64fb9ed 100644 --- a/apps/docs/docs/index.mdx +++ b/apps/docs/docs/index.mdx @@ -1,52 +1,39 @@ --- -title: Web Analytics for Umbraco -description: Web Analytics provides a dedicated Analytics section with reports for visitors, page views, trends, acquisition, audience, pages, routes, and campaigns, plus mapped published document workspaces. +title: Overview +description: Bring the analytics your site already collects into Umbraco, giving editors useful traffic reports in the backoffice and on mapped documents. --- -Web Analytics connects [Vercel Web Analytics](https://vercel.com/docs/analytics) and [Plausible](https://plausible.io/docs/stats-api) to Umbraco's dedicated Analytics section, so editors can understand traffic where they manage content. +## Supported providers -It provides a dedicated Analytics section with reports covering visitors, page views, trends, acquisition, audience, pages, routes, and campaigns. Document-workspace analytics are scoped to the mapped published document's route. +Choose the reference for the analytics provider your site already has. -It reads analytics your provider already collects. It does **not** install, replace, or configure tracking on your public website. + + + Reference connection fields, team projects, feature flags, and Vercel-specific errors. + + + Reference Cloud and self-hosted connections, event properties, and Plausible-specific errors. + + -![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png) - -## Start here +:::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. +::: - - - [Add Web Analytics to your Umbraco project](/getting-started), then build and deploy it as usual. - - - Create a provider credential, add it to server-side configuration, then add and test the connection in **Settings → Web Analytics**. Follow the provider-specific guide for [Vercel](/providers/vercel) or [Plausible](/providers/plausible) when you need its identifiers and capabilities. - - - Verify the global **Analytics** section, then set up [document analytics](/guides/document-analytics) when editors need page-level reports. - - +![The global Analytics dashboard in the Umbraco backoffice](./screenshots/analytics-overview.png) ## What you get -- Analytics is displayed in mapped published document workspaces and scoped to the document route. -- Provider-supported activity reports appear when available. -- Date comparisons, filters, and drill-downs that help editors move from a headline number to useful context. -- More than one connection for multi-site Umbraco installations. -- Server-side provider access: credentials remain in the application configuration, never in the browser or Umbraco content. +- **Traffic reports.** Explore visitors, page views, trends, acquisition, audience, pages, routes, and campaigns. +- **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. -## Supported versions and providers +## Compatibility -Web Analytics supports Umbraco CMS 17.1 through 18.x. - -| Provider | Identifier | Credential | Provider-specific capabilities | -| --- | --- | --- | --- | -| Vercel Web Analytics | Project ID (`prj_...`) and optional team | Scoped access token | Feature flags | -| Plausible | Site ID, usually the registered domain | Stats API key | Global event filtering and configurable event-property names | - -Both providers support core reports, event lists and details, and event-property drill-downs. The interface hides unsupported reports instead of presenting them as errors. - -:::note -Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is supported when its instance exposes the v2 Stats API query endpoint. -::: +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. ## Need the details? diff --git a/apps/docs/docs/providers/plausible.mdx b/apps/docs/docs/providers/plausible.mdx index 2155c14..d95e510 100644 --- a/apps/docs/docs/providers/plausible.mdx +++ b/apps/docs/docs/providers/plausible.mdx @@ -1,46 +1,38 @@ --- title: Plausible -description: Connect Plausible Cloud or a self-hosted Plausible site and configure event properties. +description: Reference for Plausible Cloud and self-hosted connections, including fields, endpoint requirements, event properties, reports, and common errors. --- -Use this guide after following the shared [getting-started flow](/getting-started). +The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Plausible-specific requirements, connection 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. -## Create the credential +## Cloud and self-hosted requirements -Create a Stats API key in Plausible and store it in the application's secret configuration: +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. -```text -WebAnalytics__Providers__Plausible__AccessToken -``` +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. -Plausible Cloud's Stats API requires a Business plan. Self-hosted Plausible is supported when the instance exposes the v2 Stats API query endpoint. +## Connection fields -## Configure a self-hosted instance +| Field | Value | +| --- | --- | +| Credential setting | `WebAnalytics__Providers__Plausible__AccessToken` | +| Site ID | The registered site ID, normally the domain, matching Plausible exactly | +| Self-hosted base URL | `WebAnalytics__Providers__Plausible__BaseUrl=https://analytics.example.com/`; Cloud users keep the default `https://plausible.io/` | -Set the public base URL of a self-hosted instance in server-side configuration. The URL must use HTTP or HTTPS and cannot include user information, a query, or a fragment. Its `/api/v2/query` endpoint must be reachable from the Umbraco application. - -```text -WebAnalytics__Providers__Plausible__BaseUrl=https://analytics.example.com/ -``` - -The default is `https://plausible.io/`, so Cloud users do not need to set this value. - -## Add the connection - -In **Settings → Web Analytics**, choose **Plausible** and enter the **Site ID**. This normally is the domain registered in Plausible and must match it exactly. - -Save, then select **Test connection**. A `401` or `403` usually means the Stats API key cannot read that site; a rejected query commonly means the Site ID does not match the registered domain. +Add these values in **Settings → Web Analytics**. A `401` or `403` usually means the Stats API key cannot read that site; a rejected query commonly means the Site ID does not match the registered domain. ## 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. -- `url` is built in for outbound-link and file-download goals. -- `path` is built in for 404 goals. +| Property | Built in for | +| --- | --- | +| `url` | Outbound-link and file-download goals | +| `path` | 404 goals | ## Capabilities diff --git a/apps/docs/docs/providers/vercel.mdx b/apps/docs/docs/providers/vercel.mdx index b343496..83fc9c7 100644 --- a/apps/docs/docs/providers/vercel.mdx +++ b/apps/docs/docs/providers/vercel.mdx @@ -1,32 +1,27 @@ --- title: Vercel Web Analytics -description: Connect a Vercel project and understand its available analytics reports. +description: Reference for Vercel Web Analytics connection fields, reports, team projects, credential overrides, and common connection errors. --- -Use this guide after following the shared [getting-started flow](/getting-started). +The [quickstart](/quickstart) owns the first-time setup flow. Use this page to look up Vercel-specific requirements, connection 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. -## Create the credential +## Requirements -Create a Vercel token in account settings and scope it to the account or team that owns the project. The access token must be configured server-side. +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. -```text -WebAnalytics__Providers__Vercel__AccessToken -``` - -For a team-owned project, copy either the team ID (`team_...`) or team slug as well. - -## Add the connection - -In **Settings → Web Analytics**, choose **Vercel** and enter: +## Connection fields -- **Project ID** — the Vercel project identifier beginning with `prj_...`. -- **Team** — optional. Leave it blank for a personal project. +| Field | Value | +| --- | --- | +| Credential setting | `WebAnalytics__Providers__Vercel__AccessToken` | +| Project ID | Vercel project identifier beginning with `prj_...` | +| Team | Optional for a personal project; for a team-owned project, use its `team_...` ID or slug | -Save, then select **Test connection**. A `401` or `403` generally means the token cannot access the project; a `400` usually means the project ID or optional team value is invalid. +Add these values in **Settings → Web Analytics**. A `401` or `403` generally means the token cannot access the project; a `400` usually means the project ID or optional team value is invalid. ## Capabilities diff --git a/apps/docs/docs/quickstart.mdx b/apps/docs/docs/quickstart.mdx new file mode 100644 index 0000000..210ac4c --- /dev/null +++ b/apps/docs/docs/quickstart.mdx @@ -0,0 +1,79 @@ +--- +title: Quickstart +description: Install Web Analytics, configure a Vercel or Plausible credential, create and test a connection, then verify the Umbraco Analytics dashboard. +--- + +This is the complete first-time setup path for Web Analytics. Stay on this page from package installation to a working dashboard. + +## 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 access the Vercel project or Plausible site you want to connect. + +## 2. Install the package + +Add Web Analytics to the Umbraco web project: + +```sh +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. + +## 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. + +### 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. +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: + +```sh +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. Configure it as `WebAnalytics__Providers__Plausible__AccessToken` in your hosting platform's secret or app-setting facility. +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. + +For local development, set the values with .NET user secrets: + +```sh +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: 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. + +If the test fails, use [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection. + +## 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. + +## Next step: document analytics + +Optionally configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document. diff --git a/apps/docs/evals.yaml b/apps/docs/evals.yaml index aa19a75..e5fc136 100644 --- a/apps/docs/evals.yaml +++ b/apps/docs/evals.yaml @@ -6,7 +6,7 @@ questions: - The package registers its services and backoffice extensions automatically. - Build and deploy the Umbraco application as usual; NuGet static web assets include the App_Plugins files. routes: - - /getting-started + - /quickstart - id: configure-provider-secret question: How should I securely create, configure, deploy, and rotate an analytics provider credential? @@ -16,7 +16,7 @@ questions: - Use the hosting platform's equivalent secret or app-setting facility in deployed environments. - Restart every Umbraco application instance after adding or rotating a credential. routes: - - /getting-started + - /quickstart - id: add-first-connection question: How do I add and test my first analytics connection, and how can I confirm whether it uses a shared credential or a connection override? @@ -26,7 +26,7 @@ questions: - Enter the provider identifier, save settings, and select Test connection. - The settings screen reports whether it detected a shared credential or connection override without displaying or storing a token. routes: - - /getting-started + - /quickstart - id: settings-precedence question: How does Web Analytics configuration precedence work before and after the first Settings → Web Analytics save?