# Custom Analytics Provider

> Implement a custom analytics provider for this repo's analytics abstraction.

*Canonical: https://makerkit.dev/docs/nextjs-prisma/analytics/custom-analytics-provider*

---

The analytics package in this repo is an abstraction layer. It does not ship provider implementations for GA4, PostHog, Umami, or other vendors.

## What Exists

- `@kit/analytics`
- `@kit/analytics/server`
- `AnalyticsService`
- `createAnalyticsManager()`
- `NullAnalyticsService`

The default client and server exports both register only the null provider:

- `packages/analytics/src/index.ts`
- `packages/analytics/src/server.ts`

## Provider Contract

Implement `AnalyticsService` from `packages/analytics/src/types.ts`:

```ts
export interface AnalyticsService {
  initialize(): Promise<unknown>;
  trackEvent(
    eventName: string,
    eventProperties?: Record<string, string | string[]>,
  ): Promise<unknown>;
  trackPageView(path: string): Promise<unknown>;
  identify(
    userId: string,
    traits?: Record<string, string>,
  ): Promise<unknown>;
}
```

## Registration Pattern

Register your provider with `createAnalyticsManager()`:

```ts
import { createAnalyticsManager } from '@kit/analytics';

import { MyAnalyticsService } from './my-analytics-service';

export const analytics = createAnalyticsManager({
  providers: {
    myAnalytics: () => new MyAnalyticsService(),
  },
});
```

Use the same approach for `@kit/analytics/server` if your provider has a separate server SDK.

## App Wiring

The app publishes events from `apps/web/components/analytics-provider.tsx`. That component maps app events into:

- `analytics.trackEvent(...)`
- `analytics.trackPageView(...)`
- `analytics.identify(...)`

If you replace the default analytics export with your own manager, that app wiring can stay unchanged.