phuryn/product-engineering / app-stack/skills/product-analytics
product-analytics
VerifiedAdding analytics, session recordings, heatmaps, 'what did users do', Clarity or PostHog: behaviour analytics without analytics cookies, read back by the agent.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.5 KB |
| receipts.md | markdown | 808 B |
| references/posthog.md | markdown | 3.6 KB |
| references/shared-app-router.md | markdown | 5.4 KB |
references/shared-app-router.md
View on GitHub# Analytics in a shared App Router
**Use this procedure only when the owner chooses a landing page in the shared App Router.** Keep the tag confined to the landing page as its own browser document. Follow `SKILL.md` § Consent decision and analytics proof and the browser checks below.
Clarity records the address and referrer of the page it runs on, and of every page the visitor reaches without a full page load, because it follows the browser's history (Microsoft's `clarity` repository, `packages/clarity-js/src/core/history.ts`); its masking covers neither referrers nor query parameters it was not asked to mask (Clarity's FAQ; both read on `2026-10-29`). In one root layout, a document that moved without a full page load can hold pricing (checkout for members), sign-up (which carries the identity provider's invitation ticket in its query), the member home, or a page whose unguessable id is its only lock (`saas-authorization`), in its history or ahead of it. So:
- **Add the script only to a document holding solely the landing page.** The tag's component checks: `const n = window.navigation; if (n && location.pathname === '/' && n.entries().filter((e) => e.sameDocument).length === 1) addTag()`. Add nothing where the Navigation API is missing. Links to a landing page can carry ad click ids (`gclid`, `fbclid`) and an email platform's subscriber id (Klaviyo's `_kx`), which PostHog's own code lists as personal data (posthog-js, read on `2026-10-29`). PostHog masks its own list and, through `custom_personal_data_properties`, the rest the agent names (`posthog.md`). Clarity records the page address as it is unless its support masks named parameters for the project (page addresses only, not referrers or clicked links; Clarity's FAQ, read on `2026-10-30`), so before the tag goes on the agent names to the owner every click id in posthog-js's `PERSONAL_DATA_CAMPAIGN_PARAMS` (`gclid`, `fbclid`, `msclkid`, `ttclid`, `li_fat_id` …) and the subscriber id of the owner's email platform, whether or not today's links carry them, and the owner has Clarity's support mask them in both projects or decides with counsel to record them. Never strip them in the browser: called from the tag's mount effect, `history.replaceState` runs before Next's router patches the History API, and the router writes the original address back at its next refresh or server action (Next 16 `app-router.tsx`, read on `2026-10-30`). A load at `/` is not enough: after a client-side arrival (a `<Link>`, `router.push`, the identity provider's redirect after sign-out), a reload, a Back that reloads the page, or a link to `/` followed while on it keeps the entries reached before, and Back reaches them inside the same document (observed in Chrome 156, `2026-10-29`);
- **Make every way out of the landing page a full load.** Use a plain `<a href>`, never `<Link>`, `next/form`'s `<Form>`, `router.push` or a server action that redirects, and nothing from the identity provider's client library on the page (its sign-in and user buttons, its sign-up form, its pricing table, its hooks); the provider in the root layout stays (`clerk-production`), and any plan cards the landing shows are its own, read from the billing file (`app-lifecycle`, default choices, pricing); a landing that names no price shows none;
- **Send `Referrer-Policy: strict-origin` across the whole site.** Set it (`clerk-production`, the CSP), so no page hands its address to the next, and the raw-response check there reads it on the landing page and on a page reached by an id;
- **Keep the tag off when the URL or referrer carries sensitive data.** Referrers must be empty or origin-only HTTP(S). For the landing URL, refuse fragments and parameters outside those masked or explicitly approved by the owner with counsel. Keep sensitive values out of links, which Clarity's parameter masking does not cover. Prove the refusals in the browser.
- **Test every departure and history path for full loads and no analytics.** A browser test opens the landing page and follows each of its same-origin links that leave `/` (not `mailto:` or `tel:`, a link that opens a new tab, a link to another origin, or a link to `/` itself or a fragment on it) and submits each of its forms with valid test values, failing when a link or a submission changes the address or adds a history entry without a new `load` event, or when the page it reaches adds a `*.clarity.ms` script or sends a request there after its own `load` event. Then, from the member home, it signs out onto the landing page and walks each path from there, signing in and out again before the next: Back; a reload of `/`, then Back; the landing page's link to `/`, then Back; a public page, Back to `/`, then Back again. Each fails on any request to `*.clarity.ms` from the sign-out on.
- **Hold the client-library ban with the front door's source guard.** Once any file imports the tag's component, wherever it is mounted and whatever its project id, it fails on any import from the identity provider's client library in every layout, template, loading, error, global-error and not-found file around the landing page, the landing page and every component they import, the root layout's provider excepted (`clerk-production`, the front door). On this stack that means `src/app/` and `src/app/(public)/`, imports of `@clerk/nextjs`, and the `ClerkProvider` exception in `src/app/layout.tsx`.
Keep the instructions in `SKILL.md` § What binds for any expansion past the landing page.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |