Analytics
Quick start
Install the plugin, track pageviews with the native engine, and see numbers in the admin.
This walkthrough uses the native engine so nothing external is required. Swap in a provider adapter at any point; everything else stays the same.
Install
pnpm add @10x-media/analyticsConfigure
import { buildConfig } from 'payload'
import { analytics, analyticsDefaultWidgets, analyticsStatRow } from '@10x-media/analytics'
import { native } from '@10x-media/analytics/adapters/native'
export default buildConfig({
admin: {
// Widgets render on Payload's Modular Dashboard. The app owns the layout;
// spread the plugin's defaults into it (or compose your own).
dashboard: { defaultLayout: [...analyticsDefaultWidgets()] },
},
collections: [
{
slug: 'pages',
fields: [
{ name: 'slug', type: 'text' },
analyticsStatRow(), // pageviews, visitors, sessions, avg duration
],
},
],
plugins: [
analytics({
adapters: [native()],
collections: {
// Bind documents to the URL path their analytics were recorded under.
pages: { path: (doc) => (doc.slug ? `/${doc.slug}` : null) },
},
}),
],
})Then regenerate the import map so the admin resolves the plugin's server components:
payload generate:importmapSend events
The native engine registers a public beacon endpoint at POST /api/analytics/ingest. Call it from your frontend on navigation:
navigator.sendBeacon(
'/api/analytics/ingest',
JSON.stringify({
type: 'pageview',
path: location.pathname,
hostname: location.hostname,
referrer: document.referrer || undefined,
})
)type, path, and hostname are required; see Native engine for the full event shape.
Verify
- Hit a few frontend pages (or POST to the ingest endpoint by hand).
- Open the admin dashboard: the trend, metric, and breakdown widgets show the traffic.
- Open a
pagesdocument whose slug matches a tracked path: the stat row shows that document's numbers.
Where to go next
- Point the plugin at an existing provider instead: Adapters.
- Bind more collections and tune the fields: Display fields.
- Configure the dashboard: Widgets.
- Production concerns: geo resolution, caching and warming, retention, and the Mongo
ensureIndexesnote in Native engine.