Add funnel telemetry for documentation journeys

[David Pine (IEvangelist)]

Summary

• add a versioned, consent-gated funnel event contract for CLI installation, getting started, search, integrations, deployment, troubleshooting, 404 recovery, and existing-app adoption
• instrument shared components plus relevant English and Japanese guides with bounded stage and dimension metadata
• correlate short-lived same-origin continuation outcomes
• prevent raw search queries, referrers, and arbitrary 404 paths from entering automatic or manual analytics payloads
• keep the CLI installation funnel limited to reliable browser-side stages through command_copied; server-side request measurement is deferred until StaticHost has a compatible telemetry exporter

Fixes #1582

Third-party links and affiliations

None.

Validation

• pnpm --dir ./src/frontend exec vitest run --config vitest.config.ts tests/unit/analytics-script-contracts.vitest.test.ts tests/unit/redirects.vitest.test.ts tests/unit/custom-components.vitest.test.ts (78 passed)
• targeted ESLint for changed analytics scripts and tests
• pnpm --dir ./src/frontend exec playwright test tests/e2e/analytics-scripts.spec.ts (51 passed across desktop, tablet, and mobile Chromium)
• targeted install-funnel Playwright coverage after removing the nonfunctional server stage (15 passed across desktop, tablet, and mobile Chromium)

[Copilot]

Pull request overview

Adds a consent-gated, versioned funnel telemetry contract across aspire.dev documentation journeys, instruments key UI surfaces and guides (EN/JA), and hardens analytics payloads to avoid leaking raw queries/referrers/arbitrary 404 paths.

Changes:

• Introduces a stable funnel step contract + bounded dimensions, and instruments docs/components to emit funnel milestones.
• Adds continuation correlation via short-lived same-origin sessionStorage markers (search destination + 404 recovery outcomes).
• Sanitizes OneDS automatic telemetry (query-free canonical URLs, 404 sentinel path) and updates StaticHost install-script telemetry to be aggregate and referrer-free.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/StaticHost.Tests/OneDSTelemetryServiceTests.cs	Adds coverage for aggregate install-script download funnel tags and non-prod skipping.
src/statichost/StaticHost/Telemetry/TelemetryConstants.cs	Adds funnel schema/tag constants; removes referer tag constant.
src/statichost/StaticHost/Telemetry/OneDSTelemetryService.cs	Emits aggregate funnel tags for install-script downloads; stops sending request referer.
src/frontend/tests/unit/custom-components.vitest.test.ts	Updates component render assertions to include funnel attributes.
src/frontend/tests/unit/analytics-script-contracts.vitest.test.ts	Adds contract tests for query-free OneDS config and funnel metadata behavior.
src/frontend/tests/e2e/analytics-scripts.spec.ts	Adds end-to-end coverage for funnel events across key journeys and privacy guarantees.
src/frontend/src/expressive-code-plugins/funnel-metadata.mjs	New plugin to copy data-funnel* metadata from code fences onto rendered figures.
src/frontend/src/content/docs/ja/get-started/troubleshooting.mdx	Instruments troubleshooting milestones (view/copy) with funnel metadata (JA).
src/frontend/src/content/docs/ja/get-started/install-cli.mdx	Reworks OS-aware snippets and adds funnel metadata for CLI install steps (JA).
src/frontend/src/content/docs/ja/get-started/first-app.mdx	Adds funnel metadata to getting-started steps and next-step link (JA).
src/frontend/src/content/docs/ja/get-started/deploy-first-app.mdx	Adds funnel metadata for deployment intent stages + verification markers (JA).
src/frontend/src/content/docs/get-started/troubleshooting.mdx	Instruments troubleshooting milestones (view/copy) with funnel metadata (EN).
src/frontend/src/content/docs/get-started/install-cli.mdx	Adds funnel metadata to CLI install command blocks and OS-aware script blocks (EN).
src/frontend/src/content/docs/get-started/first-app.mdx	Adds funnel metadata to getting-started steps and next-step links (EN).
src/frontend/src/content/docs/get-started/deploy-first-app.mdx	Adds funnel metadata for deployment intent stages + verification markers (EN).
src/frontend/src/content/docs/get-started/add-aspire-existing-app.mdx	Adds funnel metadata for existing-app adoption approach/setup/run stages (EN).
src/frontend/src/content/docs/404.mdx	Adds no-referrer policy and 404 recovery funnel markers/actions.
src/frontend/src/components/starlight/SocialIcons.astro	Adds CLI install entry funnel metadata to install modal trigger.
src/frontend/src/components/starlight/Search.astro	Adds search-success funnel tracking + DNT flags for API search links.
src/frontend/src/components/starlight/Header.astro	Adds CLI install entry funnel metadata to header install button(s).
src/frontend/src/components/Integrations.astro	Emits funnel events for integration gallery filtering actions with bounded dimensions.
src/frontend/src/components/IntegrationCard.astro	Adds integration context + selection/copy funnel metadata to cards and actions.
src/frontend/src/components/InstallPackage.astro	Adds integration-context wrapper + install copy funnel metadata for hosting packages.
src/frontend/src/components/InstallDotNetPackage.astro	Adds integration-context wrapper + install copy funnel metadata for client packages.
src/frontend/src/components/InstallCliModal.astro	Adds CLI install funnel metadata for modal options + emits options_viewed stage.
src/frontend/src/components/home/HomePage.astro	Adds CLI install entry funnel metadata to homepage CTA.
src/frontend/public/scripts/analytics/track.js	Implements funnel contract enforcement, continuation correlation, and event emission plumbing.
src/frontend/public/scripts/analytics/1ds.js	Disables query collection and sanitizes OneDS automatic telemetry URLs/page names.
src/frontend/ec.config.mjs	Registers the new funnel metadata expressive-code plugin.

Suppressed comments (1)

src/frontend/public/scripts/analytics/track.js:772

• Continuation markers should be matched against canonical, normalized routes. Using location.pathname here can prevent valid_destination_loaded from firing when the destination has locale prefixes or inconsistent trailing slashes. Compare with normalizePath() instead.

  function trackNotFoundRecovery() {
    var marker = readContinuationMarker(NOT_FOUND_DESTINATION_MARKER_KEY, false);
    if (!marker || marker.destinationPath !== location.pathname) return;

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Adam Ratzman (adamint)]

I found analytics correctness and privacy issues that can leak 404 paths or corrupt funnel and page-view data. Details inline.

Addressed all seven findings in 606f20a with focused contract, StaticHost, and responsive browser coverage. This change-request review is now superseded by the updated branch.