Options

analytics() takes one object, AnalyticsPluginOptions (also exported as PluginOptions). Every path below is checked when the plugin builds the Payload config: a value of the wrong shape, a key no table lists at any level, an id that names no adapter, or a combination the plugin cannot honor fails the boot with a message naming the path. An option an earlier release took and this one no longer does fails the boot too, naming its replacement (Removed options).

The native engine and each provider take options of their own, as arguments of native(), plausible() and the rest. Each of them takes label, the source's name in the admin: a string, a map by admin language, or a function per reader (A source's name); and withoutConsent, which beats capture.withoutConsent for its own slot (Without consent).

import { analytics } from '@10x-media/analytics'
import { native } from '@10x-media/analytics/adapters/native'

export const plugin = analytics({
  adapters: [native()],
  capture: { gate: 'all' },
  collections: { pages: { path: (doc) => (typeof doc.slug === 'string' ? `/${doc.slug}` : null) } },
  revenue: { currency: 'EUR' },
  trustedPlatform: 'vercel',
})

Top level

scope

Tenancy: how a request maps to its scope. Unset, the install is one scope. Multi-tenancy has the recipe.

Each may also return a promise. These options only mean something on a scoped install, so each fails the boot without scope.resolve: scope.list, scope.label, scope.member, sources, defaultSource, access.crossScope, an adapter id in capture.slots.tenant, capture.paths.tenant, a collections.<slug>.scopeField other than false, and goals.collection.scopeField or providers.collection.scopeField when set at all.

access

CrossScopeAccess is ({ req, scope?, adapterId? }) => boolean, told what is asked where the read knows it: named the scope it names, aggregate '*' (or null for a scoped request that resolves no tenant), unscopedSource the tenant and the adapter. A gate may run once per scope and adapter in a request (What a gate is told). Each function may also return a promise.

capture

What the browser tracker captures and where it sends it (Capture).

goals

The goals an install counts conversions against: a list, which is goals.defaults with the collection off, or the object below.

revenue

Money as a capability (Revenue). false or unset measures none; true turns it on with the defaults; an object turns it on.

collections

Bindings, keyed by collection slug: how a document's display fields find its numbers. A binding needs path, pathField or item: true.

providers

Provider documents: vendor sources configured from the admin, per scope. collection and resolve cannot both be set, and hosts needs one of them.

view

The analytics view. false registers neither the view nor its nav link; the read endpoints stay.

widgets

The dashboard widgets (@beta, since Payload's Modular Dashboard is experimental). false registers none.

countryFlags

cache

How reads are cached and how much they ask of their sources (Caching).

sync

The opt-in sync tier: the analytics-sync task copies each vendor source's daily metrics into a collection. An object turns it on.

jobs

The plugin's tasks on Payload's jobs queue: analytics-maintain with native(), analytics-sync with sync, analytics-warm with cache.warm (The jobs option).

Switching it off

disabled: true switches the plugin off and keeps its database schema:

analytics({
  disabled: process.env.ANALYTICS_OFF === '1',
  adapters: [native()],
  capture: { gate: 'off' },
})

A switched-off install registers the same collections with the same fields and indexes (providers, goals, sync, cache, the native engine's three when native() is listed, and analytics-state for sync or warming) and the same task names in Payload's jobs, so a development push or a generated migration drops nothing, and every row is still there when the plugin comes back. An adapter's own collections are kept by its registerSchema, which every built-in adapter has; a custom adapter that adds collections in register without one loses them while the plugin is off, and a push or a migration then drops them.

Nothing that runs is registered: no endpoint, view or widget. Each task does nothing, and its schedule, kept so Payload keeps the payload-jobs-stats global it adds for scheduled tasks, has a hook that never queues a run. What belongs to the collections stays as it is: the providers and goals collections keep their access and their hooks, so editors still manage them in the admin. Payload's job controls stay restricted to the admin collection as when the plugin runs, which is the one onInit a switched-off install adds, and only when it keeps a task. Translations are registered only for the labels of the collections the admin lists. The options are checked as when the plugin runs, except that adapters may be empty, which keeps no adapter's collections. The collection checks run too, and only their warnings go unsaid; their second pass over the assembled config runs only while the plugin is on.

Renaming the plugin's collections

Every collection the plugin registers takes a slug and an overrides function, under the option of the feature it belongs to:

The default slugs are exported for code that queries these collections: CACHE_SLUG, GOALS_SLUG, PROVIDERS_SLUG, STATE_SLUG and SYNC_SLUG from @10x-media/analytics, and HITS_SLUG and AGGREGATES_SLUG from @10x-media/analytics/adapters/native. On an install that renames a collection, use the slug it set.

analytics({
  adapters: [
    native({
      collections: {
        hits: { slug: 'site-hits', overrides: (collection) => ({ ...collection, dbName: 'raw_hits' }) },
        aggregates: { slug: 'site-totals' },
        state: { slug: 'site-state' },
      },
    }),
  ],
  capture: { gate: 'all' },
  cache: { collection: { slug: 'site-cache' } },
  sync: { collection: { slug: 'site-daily' } },
})

analytics-state belongs to the native engine wherever native() is listed; jobs.state names it only on an install without it, where sync or warming registers it for their leases, and the boot refuses jobs.state anywhere else. It takes the key native() gives the same collection rather than collection, which under jobs would read as Payload's own payload-jobs.

slug is the only way to rename a collection, since every part of the plugin reads it under that slug: an overrides that returns another slug fails the boot, naming the option to set instead. overrides must be a function. It receives the collection as the plugin built it and returns the one to register, so spread what it keeps.

What an override may change: labels and admin settings, a dbName for the collection (its table on Postgres and SQLite, its collection on MongoDB), fields and indexes of your own, hooks, and access. Hooks never run on the rows the plugin writes, which go through payload.db or the engine's own SQL rather than the Local API.

What fails the boot, with a message naming the collection and the field:

• on the hits, daily totals, state, cache and sync collections, which the plugin writes itself: removing a field the plugin defines, renaming it, changing its type, or moving it into a named group or a named tab (a row or collapsible around it is fine), and making one localized or hasMany;
• on the same collections, dropping an index or a unique constraint the plugin declares;
• on the same collections, making one of the plugin's optional fields required, or adding a required field without a fixed defaultValue: the plugin writes rows without it, and only a value becomes the column's default, while a function runs in Payload's hooks, which the plugin's writes skip;
• on the hits, daily totals and state collections, a dbName on any of the plugin's fields: the engine's SQL names each column after its field;
• on the providers and goals collections, timestamps: false: every instance notices a saved document by its updatedAt, so an edit on one server would never reach the others. Their fields are the editors' to shape, so the boot holds these two to their slug, their timestamps and the name limit below, and nothing else;
• on Postgres, a table name, or an index name Payload builds from it (<table>_<column>_idx), over 63 characters, Postgres' limit. Choose a shorter slug, or a shorter dbName.

The same checks run again at init, and when a worker booted without onInit builds what it needs, against the config every plugin has assembled. A plugin that runs after analytics and changes one of these collections the way an override may not fails there, naming the collection; so does one that removes or renames one, or that replaces the custom the plugin marks its collections in (custom['@10x-media/analytics']) rather than spreading it, since the plugin finds its collections by that mark.

What the boot warns about, once at init: on the hits, daily totals, state, cache and sync collections, an override that replaces one of the plugin's access functions, or that turns on REST endpoints or GraphQL where the plugin keeps them off. The plugin reads and writes these rows below access control, so the warning is about who else can now reach them.

A new slug or dbName names a new table (on MongoDB, a new collection) and moves no rows: on an install that already has data, write a migration that moves them, or keep the names it has.