From 1.0.0-beta.11

1.0.0-beta.12 rebuilds the native engine's storage, leaves consent to your consent manager, moves the read and capture endpoints under one base, and tightens who may read what. Every install has edits to make, and every Postgres or SQLite install in migrate mode has one reviewed migration to run. This page lists every change against 1.0.0-beta.11, grouped by theme, each with what to do.

Before you start

Work through these in order; each links to its details below. A step that names a kind of install applies to that kind only. The commands use pnpm; with npm run npx payload ..., with yarn yarn payload ....

1. Before anything boots, prepare a development database Payload pushes its schema to. The push cannot follow this release's storage change, and the app does not start. On Postgres run the SQL under Push mode first; a pushed SQLite file cannot follow the change at all, so start it again from a new file. Databases in migrate mode and MongoDB skip this step.
2. Upgrade the packages together. @10x-media/analytics needs Payload ^3.83.0 (payload, @payloadcms/next, @payloadcms/ui) and @10x-media/fields, which is now a required peer, at the range Supported versions lists. react-datepicker is no longer a peer.
3. Load the config, and fix what it refuses. Loading it (the dev server, or any payload command) fails on a removed option, naming each it finds and what replaces it: the native() options in one message, then the plugin's own in another, so it can take two runs. Rename each, but remove access.platformRead and scopes from an install without scope.resolve. The same checks refuse what 1.0.0-beta.11 let through (Options), a translation override of a removed key among them, and a widget's requires.perPageQuery or requires.filterOperators, each named with its replacement.
4. Set capture.gate. It is required whenever a capture slot can fill; ({ kind }) => kind !== 'native' keeps what 1.0.0-beta.11 did by default. Where the gate holds native, server tracking records events as no visitor's by default: server code that knows the visitor's answer passes identity: 'request'.
5. On a scoped install, add scope.member, and resolve the capture call site from the host. tenantMembership() covers @payloadcms/plugin-multi-tenant. scope.resolve is now asked for a visitor's hit without the signed-in user, their cookies or their authorization header, so answer it from the request's host: a beacon whose scope it does not resolve is answered 202 and dropped.
6. Turn money on with revenue: true or revenue: { currency } if the install reports revenue: it is off unless set. Give every goal that has an amount a currency.
7. Move the imports of AnalyticsScripts and getTrackerConfig to @10x-media/analytics/site, and the browser's consent calls to setGate. Where next.config calls captureRewrites or posthogProxyRewrites, which now throw, relay the vendor through a captureRoute route handler instead.
8. Regenerate the import map (pnpm payload generate:importmap): the widget drawer's pickers and the goal field moved to new component paths.
9. Migrate the database: the predefined migration on MongoDB, and a generated and edited one on every Postgres or SQLite install in migrate mode. On a scoped install with the providers collection, the same migration gives every tenant that keeps native analytics its native provider document; in push mode, create them in the admin (Scoped installs).
10. Run the maintenance task on a jobs runner, and let a scheduler that calls Payload's run endpoint in through jobs.access.run.
11. On Vercel or behind Cloudflare, set trustedPlatform in place of trustedProxyHops, which it excludes, or visitor countries stop being read.
12. If pages on another site post beacons, list its origin in capture.allowedOrigins. A page on another registrable domain than the one the endpoints answer on (a separate frontend on a domain of its own) sends them cross-site, and ingest answers each 202 and drops it.
13. Re-issue exclusion links with capture.exclusion: true: the old unsigned ones no longer work.
14. List self-hosted vendor hosts of provider documents in providers.hosts.allow. A host on http://, a vendor beside the app on its own network, also takes providers.hosts.allowPrivateNetwork: true, without which neither the list nor the document accepts it.
15. On SQLite, open the database with sqliteAdapter({ wal: true, busyTimeout: 5000 }), so the native engine counts on worker threads of its own, and leave transactionOptions unset (SQLite). Native runs on a database file: it refuses an in-memory database and an embedded replica.

Removed options

An option this release removed or renamed fails the boot, naming what replaces it and linking to Upgrading. These are the options 1.0.0-beta.11 accepted:

Options

What else changed in what the options take, and what the boot refuses:

Endpoints

Every endpoint moved under one base, routes.base, default /_x, with no alias at the old paths:

The tracker and the admin build these paths themselves, so only code of your own that calls them changes: build them with analyticsRoutes(config) (Where the endpoints answer). A page that boots with initTracker({ endpoint }) passes the new config path. A Next route mounted for the old ingest path, or a CDN rule written for the old paths, moves too.

fetchQuery, buildQueryUrl and refreshCache from @10x-media/analytics/client take the endpoint's URL, the API route followed by analyticsRoutes(config).query or .refresh. The API route alone, which 1.0.0-beta.11 took (fetchQuery('/api', ...)), still works and reads from the default /_x base, so code written for 1.0.0-beta.11 keeps working; an install that sets its own routes.base passes the full URL.

Access and tenancy

Consent

The tracker no longer stores a consent decision: your consent manager opens and closes a gate on every page load. The tracker never reads the analytics:consent key 1.0.0-beta.11 wrote, and deletes it once a slot opens, so a visitor who answered before the upgrade is pending until your manager answers again.

Opening a slot clears that vendor's own opt-out unless the browser is excluded; closing one whose script may have run sets it, and a GA4 tag that already ran is told through consent mode that every storage type is denied. The vendor snippets changed with the gate and the exclusion prelude, so a CSP that allows them by hash needs the new hashes.

Capture

These change what is counted without any option to rename:

Money

Sales and refunds have calls of their own in this release, purchase and refund, with order ids that make a sale count once however many times it is recorded; see Revenue and Added.

The native engine

The engine was rebuilt on raw hits counted into daily totals (Native engine), and its old storage is not converted: the reports count from the first hit stored after the upgrade. Storage and the database has the migration.

Storage and the database

This release replaces the storage of the native engine, and every Postgres or SQLite install in migrate mode needs one migration, native() or not; MongoDB needs one only where it ran native() or warming. Each is described below. Every install gains the analytics-cache collection, where reads are now cached unless cache.store names a store of its own: on Postgres and SQLite that is the analytics_cache table, created by the same generated migration, and MongoDB creates it on first use. An install that runs only vendor adapters stores no hits, so beyond the cache its database changes only where it runs sync or warming, which gain the analytics-state collection for their leases and heartbeats (and sync a visit_duration column); where it keeps goals in the goals collection, which gains a browser column; and where it keeps provider settings in the providers collection, which gains the ga4_currency and posthog_scope_property columns and the native provider. On Postgres and SQLite that takes the same generated migration, with the edits below and the cache table in it; MongoDB needs nothing beyond the queued warm runs of an install that ran warming. Where payload_jobs exists (1.0.0-beta.11 registered sync, warming or native retention), the edits also delete the queued runs of the retired task names.

The engine needs Postgres 12 or later, SQLite 3.35 or later, or MongoDB 5.0 or later.

What changed in storage

The old data is not converted. The new collections start empty, and the reports count from the first hit stored after the upgrade. The migrations below delete the old collections; export them first if you want to keep their numbers.

The new collections are hidden from the admin, have no REST or GraphQL endpoints, and take text ids the engine makes, so no sequence is created for them. Storage describes what each one holds.

MongoDB

MongoDB creates the new collections on first use, so there is no schema to migrate. One migration removes the old storage. Create it from the predefined migration the package ships, then run it:

pnpm payload migrate:create analytics_storage --file @10x-media/analytics/migrations/drop-legacy-mongo
pnpm payload migrate

The created file calls dropLegacyNative from @10x-media/analytics/migrations, which:

• drops analytics-events, analytics-rollups and analytics-seen with their documents and indexes (with the Mongo adapter's default pluralization, the last one is named analytics-seens);
• deletes the old daily salts (analytics:salt:<date>) and the old cached reads (analytics|..., rt:...) from Payload's key-value store;
• deletes the queued runs of the old retention task, analytics-prune-events, and of the warm task under its old name, analytics-warm-cache, from payload-jobs.

It logs what it removed. Run again, it finds nothing and changes nothing.

An install that ran warming without native() has no old storage, but its schedule left a queued run of analytics-warm-cache in payload-jobs that no task answers any more. It runs the same migration: there is no old collection for it to drop, and it still deletes that run and the old cached reads. MongoDB cannot drop a collection inside a transaction, so this works outside the migration's own: what it removed stays removed even if a later step of the same migration fails. Its down restores nothing.

Postgres and SQLite

Push mode

The schema push of development mode, Payload's default outside production, fails on the same statements the migration below needs edited for, and the app does not start. On Postgres, drop the old tables and the queued runs of the old retention and warm tasks first, and the push does the rest on the next start:

DELETE FROM payload_jobs WHERE task_slug::text IN ('analytics-prune-events', 'analytics-warm-cache');
DROP TABLE analytics_events, analytics_rollups, analytics_seen CASCADE;
DROP TYPE enum_analytics_events_type;

Run the DELETE whenever payload_jobs exists, which it does once 1.0.0-beta.11 registered any task (sync, warming or native retention), whether or not a run is queued, and leave it out when the table does not exist yet. The push recreates the task enums without analytics-prune-events and analytics-warm-cache, and a queued run of either would hold that value. The ::text cast keeps the statement valid on an enum that never had one of the two labels, as on an install that ran sync alone.

On SQLite the push fails even then, so a pushed development file cannot follow the change: start it again from a new file, and export first what you want to keep.

Migrate mode

Generate the migration with Payload's own command after upgrading the package:

pnpm payload migrate:create analytics_storage

The command asks, for each new table, whether it is created or renamed from one of the old ones. Answer create table every time, and create enum for each new enum on Postgres: analytics_hits is not a renamed analytics_events, and a rename would carry the old columns and rows into it. Generate it from the config you run in production, since the migration holds what that config adds, the providers collection and the jobs tables included.

What the migration contains

Review the generated file before running it. Upgrading from 1.0.0-beta.11, it holds:

• CREATE TABLE for analytics_hits, analytics_aggregates and analytics_state, with an index on (scope, ts) for the hits, on (scope, dim, dim2, day) and on (scope, dim, value, day) for the aggregates, and on (kind, status, day) and (kind, scope, day) for the state;
• CREATE TABLE for analytics_cache, with a unique index on key and indexes on stale_until and read_at, on every install that does not set cache.store;
• DROP TABLE for analytics_events, analytics_rollups and analytics_seen, and on Postgres DROP TYPE "public"."enum_analytics_events_type";
• the old tables' columns, foreign keys and indexes removed from payload_locked_documents_rels; SQLite does this by rebuilding the table;
• Payload's jobs tables, payload_jobs and payload_jobs_log with their enums on Postgres, and payload_jobs_stats for the tasks' schedules, when the install ran no task before; when it did, the task enums are recreated with analytics-maintain added, analytics-warm in place of analytics-warm-cache when warming is on, and analytics-prune-events gone (with jobs: false, only the removals);
• on an install with sync or warming but no native(), the analytics_state table for their leases and heartbeats;
• with the goals collection, its browser column, for a goal that ignores completions sent from a browser;
• with sync, the sync collection's visit_duration column (analytics_daily unless renamed), for time per visit;
• with the providers collection: the ga4_currency and posthog_scope_property columns on analytics_providers, and the native provider as a value of its enum and as the column's default; SQLite rebuilds the table for this.

The index names come from Payload, which names an index after its columns and adds a number when another table already uses the name.

Edits before you run it

Some of the generated statements fail as Drizzle writes them. Edit the generated file first.

On Postgres:

1. DROP TABLE ... CASCADE already removes the old tables' foreign keys from payload_locked_documents_rels, so the three DROP CONSTRAINT statements after it fail. Add IF EXISTS to each of them:

   ALTER TABLE "payload_locked_documents_rels" DROP CONSTRAINT IF EXISTS "payload_locked_documents_rels_analytics_events_fk";

   and the same for payload_locked_documents_rels_analytics_rollups_fk and payload_locked_documents_rels_analytics_seen_fk.

2. When payload_jobs exists, which it does once 1.0.0-beta.11 registered any task (sync, warming or native retention), whether or not a run is queued, delete the queued runs of the old retention task and of the warm task under its old name: the recreated task enums cannot hold either slug. Make this the first statement of the db.execute block, and leave it out when the table does not exist yet, since the migration creates it:

   DELETE FROM "payload_jobs" WHERE "task_slug"::text IN ('analytics-prune-events', 'analytics-warm-cache');

   The ::text cast keeps it valid on an enum that never had one of the two labels, as on an install that ran sync alone.

3. With the providers collection, Postgres refuses to use an enum value in the transaction that added it, and the migration runs in one. Move the ALTER TYPE "public"."enum_analytics_providers_provider" ADD VALUE ... statement out of db.execute and run it on the adapter's own connection, which commits it at once:

   import { type MigrateUpArgs, type PostgresAdapter, sql } from '@payloadcms/db-postgres'
   
   export async function up({ db, payload }: MigrateUpArgs): Promise<void> {
     await (payload.db as unknown as PostgresAdapter).drizzle.execute(
       sql`ALTER TYPE "public"."enum_analytics_providers_provider" ADD VALUE IF NOT EXISTS 'native' BEFORE 'plausible';`
     )
     await db.execute(sql`
       -- the rest of the generated statements
     `)
   }

On SQLite:

1. Dropping the second old table fails while payload_locked_documents_rels still references the first. Move the three DROP TABLE statements for analytics_events, analytics_rollups and analytics_seen below the statements that rebuild payload_locked_documents_rels, which end with that table's CREATE INDEX statements.

2. With the providers collection, the rebuild of analytics_providers copies two columns the old table does not have. Remove "ga4_currency" and "posthog_scope_property" from both column lists of the INSERT INTO __new_analytics_providers statement. Upgrading straight to a later release, remove the columns it added there too: "is_default" (1.0.0-beta.13, scoped installs) and "without_consent" (1.0.0-beta.15).

3. When payload_jobs existed before the upgrade (1.0.0-beta.11 registered sync, warming or native retention), delete the queued runs of the old retention task and of the warm task under its old name, which nothing runs any more, with one more statement at the end of up:

   await db.run(
     sql`DELETE FROM payload_jobs WHERE task_slug IN ('analytics-prune-events', 'analytics-warm-cache');`
   )

At the end of up

The old salts in Payload's key-value store are left behind on Postgres and SQLite: a few rows named analytics:salt:<date> in payload_kv, which hash no visitor once the old tables are gone. deleteLegacySalts from @10x-media/analytics/migrations removes them; end the generated migration's up with it:

import { deleteLegacySalts } from '@10x-media/analytics/migrations'

// at the end of up({ db, payload, req })
await deleteLegacySalts({ payload })

It deletes only keys starting with analytics:salt:, answers how many, and finds nothing the second time. On a scoped install with the providers collection, the tenants' native documents come after it (Scoped installs).

Then run it:

pnpm payload migrate

Scoped installs

On a scoped install running the providers collection, native is now granted per tenant: a tenant stores and reads native visits only while it holds an enabled provider document of type Payload (provider: 'native'), where 1.0.0-beta.11 served every tenant. A tenant without one sees no native source, gets no native beacon in its tracker config, and has its beacons answered 202 and dropped; what it stored before is kept (Native is a provider type). An install without scope.resolve, or without the providers collection, is unaffected.

Create the documents in the upgrade's own migration, so no beacon arrives between the deploy and the documents: at the end of the generated migration's up on Postgres and SQLite, after deleteLegacySalts, and at the end of the drop-legacy-mongo migration's up on MongoDB. On Postgres that works because edit 3 committed the native enum value on the adapter's own connection first. Write through the migration's req and as a user access.crossScope.named admits: the providers collection stamps every write with a scope, and refuses one for another tenant from anyone else, overrideAccess or not.

// At the end of up({ payload, req }): one document per tenant that keeps native analytics, written
// as a user access.crossScope admits (the first user here: pick one that qualifies).
const [platformAdmin] = (await payload.find({ collection: 'users', limit: 1, req })).docs
for (const scope of ['tenant-a', 'tenant-b']) {
  await payload.create({
    collection: 'analytics-providers',
    data: { name: 'Payload', provider: 'native', enabled: true, scope },
    req,
    user: platformAdmin,
  })
}

Passing user sets it on the migration's req. With @payloadcms/plugin-multi-tenant and providers.collection.scopeField: 'tenant', set tenant in data instead of scope. Where there are more than a few tenants, read them from your tenants collection rather than listing them. A development database in push mode runs no migration: create the documents in the admin instead, one provider of type Payload per tenant, or in a seed of your own written the same way.

The documents decide which tenants store; scope.resolve still decides which tenant a beacon is for. It is asked at the capture call site from what the request itself carries, without the signed-in user, their cookies or their authorization header, so resolve it from the host (The call site): a beacon it resolves to no tenant is dropped too.

Old cached reads

Earlier releases cached reads in Payload's key-value store and never deleted them, so an install that ran one for a while holds many rows named analytics|... (reads) and rt:... (live counts) in payload_kv, or the payload-kv collection on MongoDB. Nothing reads them any more. deleteLegacyCache from @10x-media/analytics/migrations removes them, on any database and whether or not the install runs native(), from the up of any migration:

import { deleteLegacyCache } from '@10x-media/analytics/migrations'

// in up({ db, payload, req })
await deleteLegacyCache({ payload })

It deletes only keys in those two shapes, answers how many, and finds nothing the second time. On MongoDB, dropLegacyNative already calls it.

Jobs

native() registers the analytics-maintain task, unless jobs is false. It counts closed days, snapshots today and deletes what retention lets go; without a runner, reads and ingest do that work as they go (Maintenance). The warm task is now analytics-warm, no longer analytics-warm-cache, and it and analytics-sync follow jobs.queue and their own jobs.tasks entries: sync.cron and cache.warm.cron fail the boot, naming jobs.tasks.sync.cron and jobs.tasks.warm.cron (see the jobs option). The old engine's retention task, analytics-prune-events, is gone. Warming no longer reads admin.dashboard.defaultLayout: it repeats the reads readers made (see Warming).

Registering a task turns Payload's jobs on, which adds the payload-jobs collection to an install that had no task before, and the payload-jobs-stats global with it unless every task is unscheduled (cron: false). The task runs through Payload's job runner; running it says how to set one up. A scheduler calling Payload's /api/payload-jobs/run endpoint is refused unless the jobs config's access.run lets it in, so set that before pointing a cron at it.

Once the plugin registers a task, it restricts every job control your Payload config left unset to users of the admin collection: jobs.access.run (the /run and /handle-schedules endpoints), jobs.access.queue and jobs.access.cancel, the payload-jobs collection's create, read, update and delete (composed over your own jobsCollectionOverrides), and the payload-jobs-stats global. Payload otherwise lets any signed-in user use them, a customer of a second auth collection included, and on Payload before 3.89 that covers reading and changing every job of every plugin. A control you set is never changed, and the boot says once which ones it restricted. If a second auth collection queues or cancels your own jobs with overrideAccess: false, set jobs.access to allow it; see who may run jobs.

Each of the plugin's tasks runs at most four minutes per run and leaves the rest to the next one, and one lease per task keeps two runs apart. On Postgres, queued runs of the renamed or retired tasks must be deleted before the task enum changes: Edits before you run it.

Reads and the cache

Custom adapters

An adapter of your own implements the adapter contract, which changed:

Entry points and exports

The package gained @10x-media/analytics/site for a site's server components, and /tracker now exports only what a page boots and calls (Entry points). Removed since 1.0.0-beta.11:

captureRewrites and posthogProxyRewrites stay exported from /next, @deprecated, but throw when called (Capture).

Release tags now mark every export: an untagged one is stable, a @beta one may change in a minor release, and an @internal one is exported only for Payload's import map (Stability). The five picker paths 1.0.0-beta.11 registered stay exported, marked @deprecated with the server path that replaces each, so an import map generated before the upgrade still renders them (Component paths). Of what 1.0.0-beta.11 exported untagged:

Admin styles

The admin surfaces read one stylesheet in Payload's payload CSS layer instead of inline styles and injected <style> tags, so a rule in your admin CSS outside a layer now wins over the plugin's whatever its specificity, and a rule that had to outrank an inline style no longer needs !important. See Styling for the tokens and classes. Every admin module imports the stylesheet, and the package exports it as @10x-media/analytics/styles.css.

Other markup changed under the same classes:

• A BarList is a <table> in which only each row's label is a button; a TrendChart carries a hidden data table and draws in a fixed viewBox.
• The border under the breakdown tabs moved from .analytics-view__tabs to .analytics-view__breakdown-head, and a stat field that has no numbers to show is no longer drawn at 60% opacity: it carries .analytics-stat--muted.
• The breakdown's tab and panel ids are generated, so the fixed analytics-view-tab-* and analytics-view-breakdown-panel ids are gone, and the plugin's selects no longer carry Payload's #field-analytics-* ids.
• A missing value is markup, a dash with a hidden "no value" beside it, rather than a bare - in the text.
• Muted text reads the new --analytics-text-muted token (--theme-elevation-600), and bars fill with the new --analytics-bar-fill rather than --analytics-chart-1; widgets draw soft bars with dark labels.
• The overview shows at most five card columns; a bucket still counting (today, this hour) is drawn dashed and its label says "so far".

The package now declares "sideEffects": ["*.css"] rather than false. A BarList or TrendChart drawn outside the admin imports the stylesheet itself; import @10x-media/analytics/styles.css where your bundler does not follow it.

Admin behavior and wording

A host collection joins the plugin's group with the same labels, one per language, read from the built-in strings:

import { translations } from '@10x-media/analytics/i18n'
import type { CollectionConfig } from 'payload'

const analyticsSettings: Record<string, string> = {}
for (const [language, strings] of Object.entries(translations)) {
  const label = strings.analytics?.adminGroup
  if (label) analyticsSettings[language] = label
}

export const Reports: CollectionConfig = {
  slug: 'reports',
  admin: { group: analyticsSettings },
  fields: [{ name: 'title', type: 'text' }],
}

A translations override of adminGroup renames the plugin's group; set the same text here.

Types and components

Added, for reference: view.Component, countryFlags.Component, widgets.overrides, the /client @beta set (with RequestFailure beside RequestState, and TrendChart's maxTicks), WidgetView and WidgetViewProps from /rsc and /types, pluralKeys and the plural types, BuiltInWidgetSlug, AnalyticsComponent, QueryFetchError.code, TrendPoint.inProgress and TrendPoint.upcoming, FieldReadResult.incomplete and retryAfterMs, capabilities.metricReach, and visitDuration on widgets and in the sync collection.

Time on page and time per visit

avgDuration means time on page, engaged time per pageview, on every source, and visitDuration time per visit. Until now a vendor's avgDuration was its time per visit, so the same label stood for two numbers. See Providers for what each source declares.

Added

For reference, what 1.0.0-beta.12 adds beside the changes above, none of which an install has to adopt: the @10x-media/analytics/site entry; the gate API (setGate, gate, GateState, GateStatus, the gate and snippets props), which capture.gate drives; capture.exclusion, capture.allowedOrigins and capture.skip; captureRoute from /next; routes.base; trustedPlatform; jobs; cache.store, cache.collection and cache.concurrency; hooks.afterRead; providers.hosts, providers.collection.connectionAccess and providers.collection.sourceAccess; sales and refunds: purchase and refund on the server and in the browser, order ids up to 255 characters that native stores only as a digest keyed by the Payload secret, revenue.orderSignature and signOrderId, and a goal's browser: false; identity on server calls; collections.<slug>.scopeField and item; content items; native filters with matches on Postgres and MongoDB, for patterns those databases and JavaScript read alike (Patterns on the native engine); meta.failed and meta.dataTo; view.Component, countryFlags, widgets.overrides and the @beta sections of /client; capabilities.metricReach and the visitDuration metric; ProviderHttpError, parseRetryAfter and refreshProviders; ReadonlyViewGate, AnalyticsWidgetProps, WidgetView and WidgetViewProps; the event names on /attributes; the adapter contract types on every adapter entry, AdapterContext.now, close(payload) and recommendedTtl.today among them; sdks and its types (Ga4Sdk, Ga4Client, Ga4ReportResponse, Ga4ReportRow, MaxmindSdk, MaxmindReader), which the real packages fit, so neither is needed to type-check; pluralKeys and the plural types; BuiltInWidgetSlug, AnalyticsComponent, QueryFetchError.code, TrendPoint.inProgress and TrendPoint.upcoming; settleAnalytics from /testing; and the @10x-media/analytics/migrations helpers.