Skip to content

Commit 1cf0ddf

Browse files
thebuilderthebuilder
committed
Add Web Analytics documentation site
1 parent 8b659f8 commit 1cf0ddf

32 files changed

Lines changed: 12421 additions & 3836 deletions

‎.github/workflows/docs.yml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
name: Documentation
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- apps/docs/**
7+
- .github/workflows/docs.yml
8+
- pnpm-lock.yaml
9+
- pnpm-workspace.yaml
10+
- package.json
11+
push:
12+
branches:
13+
- main
14+
paths:
15+
- apps/docs/**
16+
- .github/workflows/docs.yml
17+
- pnpm-lock.yaml
18+
- pnpm-workspace.yaml
19+
- package.json
20+
release:
21+
types:
22+
- published
23+
workflow_dispatch:
24+
25+
permissions:
26+
contents: read
27+
28+
concurrency:
29+
group: docs-${{ github.workflow }}-${{ github.ref }}
30+
cancel-in-progress: true
31+
32+
jobs:
33+
build:
34+
name: Build documentation
35+
runs-on: ubuntu-latest
36+
env:
37+
GITHUB_TOKEN: ${{ github.token }}
38+
ASTRO_TELEMETRY_DISABLED: "1"
39+
steps:
40+
- name: Check out repository
41+
uses: actions/checkout@v7
42+
43+
- name: Set up Node.js
44+
uses: actions/setup-node@v6
45+
with:
46+
node-version: 24
47+
48+
- name: Enable Corepack
49+
run: corepack enable
50+
51+
- name: Install documentation dependencies
52+
run: corepack pnpm install --frozen-lockfile
53+
54+
- name: Check documentation
55+
run: corepack pnpm docs:check
56+
57+
- name: Validate documentation links
58+
run: corepack pnpm docs:validate
59+
60+
- name: Build documentation
61+
run: corepack pnpm docs:build
62+
63+
deploy:
64+
name: Refresh Vercel documentation
65+
if: >
66+
github.event_name == 'workflow_dispatch' ||
67+
github.event_name == 'release'
68+
needs: build
69+
runs-on: ubuntu-latest
70+
steps:
71+
- name: Trigger Vercel deployment
72+
env:
73+
VERCEL_DEPLOY_HOOK: ${{ secrets.VERCEL_DEPLOY_HOOK }}
74+
run: curl --fail-with-body --request POST --retry 3 --retry-all-errors "$VERCEL_DEPLOY_HOOK"

‎.github/workflows/publish-nuget.yml‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,6 @@ jobs:
5555
node-version: 24
5656

5757
- name: Install backoffice dependencies
58-
working-directory: src/TheBuilder.WebAnalytics/Client
5958
run: |
6059
corepack enable
6160
pnpm install --frozen-lockfile

‎.github/workflows/validate.yml‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,6 @@ jobs:
1313
client:
1414
name: Client
1515
runs-on: ubuntu-latest
16-
defaults:
17-
run:
18-
working-directory: src/TheBuilder.WebAnalytics/Client
1916
steps:
2017
- name: Check out repository
2118
uses: actions/checkout@v7
@@ -35,13 +32,13 @@ jobs:
3532

3633
- name: Audit changed client code
3734
if: github.event_name == 'pull_request'
38-
run: pnpm run audit --base '${{ github.event.pull_request.base.sha }}' --format github-annotations
35+
run: pnpm --filter thebuilder-web-analytics audit --base '${{ github.event.pull_request.base.sha }}' --format github-annotations
3936

4037
- name: Test client
41-
run: pnpm test
38+
run: pnpm --filter thebuilder-web-analytics test
4239

4340
- name: Build client
44-
run: pnpm build
41+
run: pnpm --filter thebuilder-web-analytics build
4542

4643
dotnet:
4744
name: .NET (Umbraco ${{ matrix.umbraco-version }})
@@ -89,7 +86,6 @@ jobs:
8986
run: corepack enable
9087

9188
- name: Install backoffice dependencies
92-
working-directory: src/TheBuilder.WebAnalytics/Client
9389
run: pnpm install --frozen-lockfile
9490

9591
- name: Pack NuGet package

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44
.pnpm-store/
55
**/coverage/
66
**/.vite/
7+
apps/docs/.blume/
8+
apps/docs/.blume-verify/
9+
apps/docs/dist/
710
artifacts/
811
src/TheBuilder.WebAnalytics/wwwroot/App_Plugins/
912
**/umbraco/Data/
@@ -21,3 +24,4 @@ samples/TheBuilder.WebAnalytics.Example/appsettings-schema.json
2124
*.key
2225
.idea/
2326
.vs/
27+
.blume-verify/

‎README.md‎

Lines changed: 15 additions & 242 deletions
Large diffs are not rendered by default.

‎apps/docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.blume-verify/

‎apps/docs/blume.config.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import { defineConfig } from "blume";
2+
3+
import { githubReleaseChangelogSource } from "./sources/github-releases";
4+
5+
export default defineConfig({
6+
title: "Web Analytics",
7+
description:
8+
"Bring Vercel Web Analytics and Plausible reports into the Umbraco backoffice.",
9+
github: {
10+
owner: "thebuilder",
11+
repo: "web-analytics",
12+
dir: "apps/docs",
13+
},
14+
content: {
15+
sources: [
16+
{ type: "filesystem", root: "docs" },
17+
{
18+
type: "custom",
19+
source: githubReleaseChangelogSource({
20+
owner: "thebuilder",
21+
repo: "web-analytics",
22+
}),
23+
},
24+
],
25+
},
26+
navigation: {
27+
tabs: [
28+
{ label: "Docs", path: "/" },
29+
{ label: "Changelog", path: "/changelog", href: "/changelog" },
30+
],
31+
},
32+
deployment: {
33+
output: "static",
34+
site: "https://umbraco-web-analytics.vercel.app",
35+
},
36+
ai: {
37+
llmsTxt: true,
38+
},
39+
});

‎apps/docs/docs/getting-started.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
title: Getting started
3+
description: Install Web Analytics, configure a provider credential, and verify the first connection.
4+
---
5+
6+
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.
7+
8+
## 1. Install the package
9+
10+
Add Web Analytics to the Umbraco web project:
11+
12+
```sh
13+
dotnet add package TheBuilder.WebAnalytics
14+
```
15+
16+
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.
17+
18+
## 2. Choose a provider and configure its secret
19+
20+
Create a read-only credential that can access the provider account you will connect. Add it to the application's secret configuration—not `appsettings.json` and never source control.
21+
22+
<Tabs inline param="provider">
23+
<Tab title="Vercel">
24+
Create a Vercel access token with read access to the project. Configure it as `WebAnalytics__Providers__Vercel__AccessToken`, then use the project's ID as the connection identifier in Umbraco. Add the team ID only when the project belongs to a Vercel team.
25+
26+
For local development, use either a shell environment variable or .NET user secrets:
27+
28+
```sh
29+
dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
30+
dotnet user-secrets set "WebAnalytics:Providers:Vercel:AccessToken" "your_token" --project path/to/Your.Umbraco.Web.csproj
31+
```
32+
</Tab>
33+
<Tab title="Plausible">
34+
Create a Plausible Stats API key with access to the site. Configure it as `WebAnalytics__Providers__Plausible__AccessToken`, then use the site's exact domain as the connection identifier in Umbraco. For a self-hosted instance, also configure `WebAnalytics__Providers__Plausible__BaseUrl` with its public base URL. The instance must expose `/api/v2/query`.
35+
36+
For local development, use either a shell environment variable or .NET user secrets:
37+
38+
```sh
39+
dotnet user-secrets init --project path/to/Your.Umbraco.Web.csproj
40+
dotnet user-secrets set "WebAnalytics:Providers:Plausible:AccessToken" "your_stats_api_key" --project path/to/Your.Umbraco.Web.csproj
41+
dotnet user-secrets set "WebAnalytics:Providers:Plausible:BaseUrl" "https://analytics.example.com/" --project path/to/Your.Umbraco.Web.csproj
42+
```
43+
</Tab>
44+
</Tabs>
45+
46+
Use the equivalent secret or app-setting facility in your hosting platform. Restart every Umbraco application instance after adding or rotating a credential.
47+
48+
## 3. Add and test the connection
49+
50+
As an administrator, open **Settings → Web Analytics**.
51+
52+
1. Select **Add connection**.
53+
2. Choose Vercel or Plausible. The provider cannot be changed after creation.
54+
3. Enter the provider identifier.
55+
4. Select **Save settings**, then **Test connection**.
56+
57+
The settings screen reports whether the shared provider credential or a connection override was detected. It does not display or store a token.
58+
59+
![A Plausible connection in the Web Analytics settings screen](./screenshots/settings.png)
60+
61+
## 4. Verify the dashboard
62+
63+
Open the global **Analytics** section. Check that totals and history load, then use a known date range with recorded production traffic.
64+
65+
If reports do not load, start with [troubleshooting](/reference/troubleshooting). A provider may hide an unsupported panel; that is different from a failed connection.
66+
67+
## Next step
68+
69+
Configure [document analytics](/guides/document-analytics) when editors should see a report while editing a mapped document.

‎apps/docs/docs/guides/document-analytics.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Document analytics
3+
description: Show page-level reports in the Umbraco document workspace without exposing data outside an editor's access.
4+
---
5+
6+
Document mappings are optional. A connection without a mapping remains available in the global Analytics section but does not add a document workspace report.
7+
8+
## Map an Umbraco site root
9+
10+
For each site that needs page-level reports, choose the root document in the connection's **Page analytics** settings. The nearest mapped ancestor determines which analytics connection a document uses.
11+
12+
Then either enable all document types below that root or choose the specific document types that should show the Analytics workspace view.
13+
14+
## When the workspace appears
15+
16+
A document shows its Analytics workspace view only when all of these conditions are met:
17+
18+
- It is published and has a published route.
19+
- Its nearest configured document root resolves to a connection.
20+
- Its document type is enabled for that connection.
21+
- The current user can access the Content section and browse that document.
22+
23+
The report is automatically filtered to the selected published route. This lets an editor inspect the page they are working on without first finding it in a global report.
24+
25+
![The Analytics workspace on a mapped Home document](../screenshots/document-analytics-workspace.png)
26+
27+
## Multi-site example
28+
29+
Imagine one Umbraco installation with two site roots:
30+
31+
| Root document | Connection | Result |
32+
| --- | --- | --- |
33+
| `Brand A` | Vercel project A | Documents below Brand A report against project A. |
34+
| `Brand B` | Plausible site B | Documents below Brand B report against site B. |
35+
36+
If a nested root is mapped too, it wins for documents below it because it is the nearest mapped ancestor.
37+
38+
## Permissions
39+
40+
Global and document analytics are intentionally separate:
41+
42+
| User | Global Analytics | Document Analytics | Settings |
43+
| --- | --- | --- | --- |
44+
| Administrator | Yes | Yes, where mapped | Yes |
45+
| Analytics-section user | Yes | Only with Content access and document browse permission | No |
46+
| Editor with Content access and document browse permission | No | Yes, where mapped and published | No |
47+
48+
This means an editor can see analytics for a document they can browse without gaining access to global site reporting.
49+
50+
## Troubleshoot a missing workspace
51+
52+
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.

‎apps/docs/docs/guides/meta.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
import { defineMeta } from "blume";
2+
3+
export default defineMeta({
4+
title: "Guides",
5+
icon: "book-open",
6+
order: 2,
7+
pages: ["document-analytics"],
8+
});

0 commit comments

Comments
 (0)