|
| 1 | +--- |
| 2 | +name: cookieless-insights |
| 3 | +description: Instrument any static website (SPA) with cookieless Azure Application Insights Real User Monitoring — no cookie/GDPR banner, free tier only — using the @webmaxru/cookieless-insights package + CLI. Covers Azure setup, code wiring (incl. build step), a Portal dashboard, and a terminal engagement report. WHEN making a static site/SPA observable, "add analytics without a cookie banner", cookieless RUM, privacy-friendly analytics, Application Insights for a frontend/GitHub Pages/Static Web Apps/Netlify/S3, page views + engagement + geo + key events. |
| 4 | +version: 1.0.1 |
| 5 | +author: webmaxru |
| 6 | +license: MIT |
| 7 | +--- |
| 8 | + |
| 9 | +# Instrument a static site with cookieless Azure Application Insights |
| 10 | + |
| 11 | +> **Sample request prompt:** see [`PROMPT.md`](./PROMPT.md) for a ready-to-paste prompt. Once |
| 12 | +> this skill is installed, "Instrument this static site with cookieless-insights" is enough. |
| 13 | +
|
| 14 | + |
| 15 | +Use the **`@webmaxru/cookieless-insights`** package + CLI to give any static front end |
| 16 | +privacy-friendly Real User Monitoring that needs **no cookie/GDPR banner** and stays on |
| 17 | +Azure's **free tier**. Work autonomously; state assumptions instead of asking. |
| 18 | + |
| 19 | +## Why this approach (validated against Microsoft Learn) |
| 20 | +- A static site is **browser-only** — the Azure Monitor **OpenTelemetry Distro is |
| 21 | + server-side only** (ASP.NET Core/Java/Node.js/Python). Browser telemetry uses the |
| 22 | + **Application Insights JavaScript SDK** path (RUM). `@webmaxru/cookieless-insights` |
| 23 | + wraps this: a tiny dependency-free **beacon** by default (~1–2 KB gzipped) or an optional |
| 24 | + SDK adapter. |
| 25 | +- **Cookieless** = no cookies, no local/session storage, no persistent id → no consent |
| 26 | + banner. The beacon is cookieless by construction; the SDK adapter sets |
| 27 | + `disableCookiesUsage` + `enableSessionStorageBuffer:false`. |
| 28 | +- **Free tier** = workspace-based Application Insights, 30-day retention, and a **0.16 GB/day** |
| 29 | + ingestion cap (Microsoft's documented "160 MB/day stays under the 5 GB/month free grant"). |
| 30 | + |
| 31 | +## Steps |
| 32 | + |
| 33 | +1. **Discover** the project: framework, build tool, hosting, deploy workflow, and the single |
| 34 | + **state/store choke point** (Zustand/Redux/Pinia/signals) or top-level event handlers to |
| 35 | + wire events into. Enumerate key events (page view, meaningful controls — debounce |
| 36 | + sliders/typing —, presets, add/remove, outbound clicks, "opened via shared link"). |
| 37 | + |
| 38 | +2. **Provision Azure** (reuse a project resource group if it exists, else create one): |
| 39 | + ``` |
| 40 | + npx cookieless-insights setup --name <project> --location <region> --run |
| 41 | + ``` |
| 42 | + Capture the printed **connection string** (a public client key). |
| 43 | + |
| 44 | +3. **Install + wire** (framework-agnostic): |
| 45 | + ``` |
| 46 | + npm i @webmaxru/cookieless-insights |
| 47 | + ``` |
| 48 | + ```ts |
| 49 | + import { init, trackEvent, trackChangeDebounced } from '@webmaxru/cookieless-insights'; |
| 50 | + init({ connectionString: import.meta.env.VITE_APPINSIGHTS_CONNECTION_STRING }); |
| 51 | + // wire trackEvent(...) at the store choke point + trackChangeDebounced for sliders/typing. |
| 52 | + ``` |
| 53 | + For the heavier official SDK instead of the beacon: |
| 54 | + `import { initAppInsights } from '@webmaxru/cookieless-insights/appinsights'` (install the |
| 55 | + `@microsoft/applicationinsights-web` peer dep). |
| 56 | + **Kill switch:** `init({ ..., enabled: false })` disables all telemetry. |
| 57 | + |
| 58 | +4. **Build step / deploy:** the connection string is a **public client key** — provide it at |
| 59 | + build time. Locally via `.env` (`VITE_APPINSIGHTS_CONNECTION_STRING=...`); in CI as a repo |
| 60 | + **variable** passed to the build step (never a secret, never committed as source). Verify |
| 61 | + the build succeeds and the site initializes analytics. |
| 62 | + |
| 63 | +5. **Dashboard + report:** |
| 64 | + ``` |
| 65 | + npx cookieless-insights dashboard --app-insights-id <appInsightsResourceId> |
| 66 | + npx cookieless-insights report --resource-group <rg> --app-insights <name> --days 30 --open |
| 67 | + ``` |
| 68 | + `report` prints engagement (page views, sessions, per-visit dwell, key events, top pages, |
| 69 | + geo, browser/OS) and `--open` launches the Portal dashboard. A `scripts/report.ps1` |
| 70 | + PowerShell equivalent is scaffolded by `cookieless-insights init`. |
| 71 | + |
| 72 | +6. **Ship:** ensure build + tests pass, commit, and push to the deploy branch. After a real |
| 73 | + visit, `report` shows data within ~1–3 minutes. |
| 74 | + |
| 75 | +## Definition of done |
| 76 | +- [ ] Cookieless (no cookies/storage, no persistent id) — no banner needed. |
| 77 | +- [ ] Free tier: workspace-based, 30-day retention, 0.16 GB/day cap. |
| 78 | +- [ ] Key events wired at the choke point; page view + engagement time collected. |
| 79 | +- [ ] Connection string injected at build time (repo variable in CI); kill switch documented. |
| 80 | +- [ ] Portal dashboard deployed; `report` prints real data and `--open` works. |
| 81 | +- [ ] Built, committed, pushed → deployed. |
0 commit comments