> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibestrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics & Webmaster Tools

> Fan out to Vercel, GA4, PostHog, Plausible, Umami, and Clarity — plus one-line site verification for Google Search Console, Bing Webmaster, and Yandex Webmaster. Every provider self-gates on its env var, mix and match freely.

Analytics is one of those "I'll add it later" decisions that quietly snowballs
into hours of integration work — and for AI products you usually want product
analytics (PostHog) and traffic analytics (Plausible / GA) from day one, not
day 60.

vibestrap mounts an `<Analytics />` block in the root layout that fans out to
**six** providers (Vercel, GA4, PostHog, Plausible, Umami, Clarity) plus a
`metadata.verification` block for Google / Bing / Yandex webmaster tools.
Every loader self-gates on its env var, so you only pay for what you've
configured — set the env var, restart, done.

## Analytics providers

### Prerequisites

* An account with at least one of: Vercel, Google Analytics 4, PostHog,
  Plausible, Umami, or Microsoft Clarity.
* The site / property / website ID from that provider's dashboard.
* A production domain (some providers reject events from `localhost` or sample
  them out).

### Step-by-step

1. **Pick which providers you want** in `src/config/site.ts`. All six are
   `true` by default; flip to `false` to disable even if the env var is set.

   ```ts theme={null}
   analytics: {
     vercel: true,
     googleAnalytics: true,
     posthog: true,
     plausible: true,
     umami: true,
     clarity: true,
   },
   ```

2. **Add the matching env vars** to `.env.local`. All are `NEXT_PUBLIC_*` —
   the loader runs in the browser so they must ship to the client bundle.

   ```bash theme={null}
   # GA4 — Measurement ID
   NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

   # PostHog — project key + host (host defaults to us.i.posthog.com)
   NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
   NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

   # Plausible — your domain + host (host defaults to plausible.io)
   NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
   NEXT_PUBLIC_PLAUSIBLE_HOST=https://plausible.io

   # Umami — website ID + host (host defaults to cloud.umami.is)
   NEXT_PUBLIC_UMAMI_WEBSITE_ID=00000000-0000-0000-0000-000000000000
   NEXT_PUBLIC_UMAMI_HOST=https://cloud.umami.is

   # Microsoft Clarity — project ID from clarity.microsoft.com
   NEXT_PUBLIC_CLARITY_PROJECT_ID=xxxxxxxxxx
   ```

3. **Vercel Analytics is zero-config** when deployed on Vercel — the
   `@vercel/analytics/next` component auto-injects the script. Locally it's a
   no-op. Disable by setting `analytics.vercel = false`.

4. **Restart `pnpm dev`** — `NEXT_PUBLIC_*` env vars are baked at build time.

### Pick the right provider

| Provider          | When to pick                                                                           |
| ----------------- | -------------------------------------------------------------------------------------- |
| Vercel Analytics  | You're on Vercel and want a zero-config baseline. Free tier is plenty.                 |
| GA4               | You need attribution into Google Ads / a marketing team that already uses it.          |
| PostHog           | Product analytics, feature flags, session replays — all in one. Generous free tier.    |
| Plausible         | Privacy-first, GDPR-friendly, no cookie banner needed. Lightweight script.             |
| Umami             | Open-source, self-hostable. Same privacy story as Plausible but free if you self-host. |
| Microsoft Clarity | Heatmaps + session recordings, free with no traffic cap. Pairs well with GA4.          |

### Verify it works

1. Open the site in an incognito window.
2. Open devtools → Network and filter by the provider's hostname (e.g.
   `posthog.com`, `plausible.io`, `clarity.ms`). You should see at least one
   request fire on page load.
3. Click around — each provider's dashboard should show a real-time visitor
   within 30 seconds.
4. View the page source: you should see one `<script>` tag per enabled
   provider, none for disabled ones.

### Common pitfalls

1. **Missing `NEXT_PUBLIC_` prefix.** Anything the browser reads needs the
   prefix. Without it, Next.js strips the variable from the client bundle and
   the loader silently mounts as `null`.
2. **Ad-blockers eating your scripts.** uBlock Origin and Brave block GA4,
   PostHog, Clarity, and Umami by default. To recover, use a proxy domain —
   Plausible supports a `/js/script.outbound-links.js` self-host route, and
   PostHog has a reverse-proxy guide.
3. **GA4 needs an EU consent banner.** GDPR requires explicit opt-in for GA4
   tracking. Same for Clarity (session replay = personal data). Either gate
   the script behind a consent prompt or use Plausible / Umami which are
   cookie-free by design.
4. **Dashboard pollution from localhost.** Dev traffic shows up in production
   dashboards if you don't filter it. Either set `analytics.posthog = false`
   in dev, or use the providers' "exclude IP" / "disable on localhost"
   filters.
5. **Plausible domain mismatch.** `NEXT_PUBLIC_PLAUSIBLE_DOMAIN` must exactly
   match the site you registered in Plausible — including or excluding `www`.
   Mismatched events are dropped silently.

## Search-engine site verification

To prove ownership in **Google Search Console**, **Bing Webmaster Tools**, or
**Yandex Webmaster**, each console asks you to add a meta tag to your site's
`<head>`. Vibestrap renders these via Next.js `metadata.verification` in
`src/app/layout.tsx`, so you just paste the value into an env var.

### Step-by-step

1. **Add your domain** in each console:
   * Google Search Console → [search.google.com/search-console](https://search.google.com/search-console)
   * Bing Webmaster Tools → [bing.com/webmasters](https://www.bing.com/webmasters)
   * Yandex Webmaster → [webmaster.yandex.com](https://webmaster.yandex.com/)

2. **Pick the "HTML tag" verification method** in each console. You'll see a
   meta tag like:

   ```html theme={null}
   <!-- Google -->
   <meta name="google-site-verification" content="ABC123..." />
   <!-- Bing -->
   <meta name="msvalidate.01" content="DEF456..." />
   <!-- Yandex -->
   <meta name="yandex-verification" content="GHI789..." />
   ```

3. **Copy ONLY the `content` value** (not the whole tag) into `.env.local`:

   ```bash theme={null}
   GOOGLE_SITE_VERIFICATION="ABC123..."
   BING_SITE_VERIFICATION="DEF456..."
   YANDEX_SITE_VERIFICATION="GHI789..."
   ```

   These are **server-side** env vars (no `NEXT_PUBLIC_` prefix) — Next.js
   reads them when generating the root metadata at build time.

4. **Toggle individual tags** in `src/config/site.ts` if you want to suppress
   one even though the env var is set:

   ```ts theme={null}
   verification: {
     google: true,
     bing: true,
     yandex: true,
   },
   ```

5. **Deploy**, then click **Verify** in each console.

### Verify it works

```bash theme={null}
curl -s https://yourdomain.com | grep -E 'google-site-verification|msvalidate|yandex-verification'
```

You should see one `<meta>` tag per env var that's set. Empty env vars produce
no tag (no empty `content=""` pollution).

### Common pitfalls

1. **Don't paste the whole `<meta>` tag** — only the `content` value. Pasting
   the tag itself produces broken HTML in the rendered head.
2. **Verification is one-time.** Once the console confirms, you can leave the
   env var set; it doesn't cost anything to keep the meta tag rendered.
3. **CDN cache.** If you deploy and the console says "tag not found", purge
   your CDN cache (Cloudflare, Vercel) — the verifier hits the live HTML.
4. **DNS is an alternative.** All three consoles also support DNS TXT-record
   verification, which doesn't touch your HTML. If you prefer that route,
   leave the env vars empty and add the TXT records in your DNS provider.

## Official docs

* Vercel Analytics: [vercel.com/docs/analytics](https://vercel.com/docs/analytics)
* Google Analytics 4: [support.google.com/analytics](https://support.google.com/analytics)
* PostHog: [posthog.com/docs](https://posthog.com/docs)
* Plausible: [plausible.io/docs](https://plausible.io/docs)
* Umami: [umami.is/docs](https://umami.is/docs)
* Microsoft Clarity: [learn.microsoft.com/clarity](https://learn.microsoft.com/en-us/clarity/)
* Google Search Console: [support.google.com/webmasters](https://support.google.com/webmasters)
* Bing Webmaster Tools: [bing.com/webmasters/help](https://www.bing.com/webmasters/help)
* Yandex Webmaster: [yandex.com/support/webmaster](https://yandex.com/support/webmaster/)