# Analytics

> Register your own analytics provider in one file and get pageviews: no vendor in the kit, no data sent until you add one.

*Canonical: https://makerkit.dev/docs/void-cloudflare/operations/analytics*

---

The kit ships an analytics registry and no provider. Until you add one, nothing is sent anywhere, and every call does nothing.

## Add a Provider

A provider is a plain object. Every method is optional; add what your tool needs.

```ts
// apps/web/config/analytics.config.ts
export const analyticsProviders: AnalyticsProvider[] = [
  {
    name: 'acme',
    trackPageView: (path) => window.acme?.page(path),
    trackEvent: (name, properties) => window.acme?.track(name, properties),
    identify: (userId) => window.acme?.identify(userId),
  },
];
```

The root layout reports every page load and client navigation to `analytics.trackPageView`. Track your own events anywhere in the browser:

```ts
import { analytics } from '#/config/analytics.config.ts';

analytics.trackEvent('invited_member', { plan: 'pro' });
```

- Calls return nothing and never wait. A provider that throws or rejects is logged once, by its name, and never reaches your code or the other providers.
- Property values are strings or lists of strings.
- Provider names must be unique: a failure is logged once per provider.
- A provider that sends from the server makes its own instance with `createAnalytics` from `@kit/analytics` in a `*.server.ts` file, and keeps the request alive itself (`waitUntil`). `config/analytics.config.ts` is for the browser.

## Load the Vendor's Script

Render the vendor's `<script src>` from your own page code, for example through `defineHead`: it gets the page's nonce automatically, so it runs under the policy. The provider then calls the vendor's global (`window.acme`). Declare its type with `declare global`.

Then add the vendor's request and image origins (`connect-src`, `img-src`) to `csp` in `apps/web/config/security.config.ts`: [Content Security Policy](../security/content-security-policy) has the rules.

## What You Must Not Send

- **Paths only, never queries.** The kit sends the path with token segments removed. If you add a page whose path holds a token, add its pattern to `TOKEN_SEGMENTS` in `apps/web/lib/redact-path.ts` first: a provider is a third party.
- **Never an email, a name or a secret.** Identify people by user id.
- **Consent is yours.** Whether you need a cookie banner or a consent check depends on your vendor and your visitors. The kit has none, and it reports every page load: check consent inside your provider's methods, and load the vendor's script only after the visitor agrees.
