Adapter contract

Everything in the plugin reads through one interface, AnalyticsAdapter from @10x-media/analytics/types. An adapter answers queries (pageviews for /blog/post-1 over the last 30 days) and declares what it can answer; the plugin never asks it for more. The native engine and the vendor adapters implement the same contract, which is why every surface works with any of them.

The adapter

The capabilities model

Each adapter declares an AnalyticsCapabilities object. The plugin trusts it: a surface offers only what the selected source declares, and the query endpoint refuses the rest before the adapter sees it.

The sources endpoint serializes a subset of these for the browser, SerializedCapabilities: metrics, dimensions, filters, metricReach, realtime, realtimeWindowMinutes, perItemQuery, comparison, minGranularity and maxLookbackDays. Credentials, rate limits and TTLs never leave the server.

Metric reach

metricReach says where a metric is read when a source cannot read it under every dimension it declares. Each entry is { dimensions?, requires? }: dimensions lists the breakdowns the metric is read under (an empty list means whole-site numbers and series only), and requires names a dimension the read must break down or filter by for the metric to have a value at all, where a read of one page (AnalyticsQuery.path) counts as filtering by page. A metric left out is read under every dimension.

import type { AnalyticsCapabilities } from '@10x-media/analytics/types'

export const reach: AnalyticsCapabilities['metricReach'] = {
  bounceRate: { dimensions: ['page', 'country', 'device'] }, // not under `event` or `goal`
  scrollDepth: { requires: 'page' }, // by page, filtered by page, or for one page
}

The query endpoint refuses a read outside a metric's reach with unsupported_metric, and the view, the widget pickers and the display fields leave the metric out there instead of showing an empty column. A saved widget asking for it shows that it is not available for its data source.

Weeks and months

A source answers series by minute, hour or day. A read by week or month is read by day and folded by the engine in the read's reporting timezone: counts add up, and each average is weighted by its row's samples or, without them, by its matching count in the row (pageviews for avgDuration and scrollDepth, visits for bounceRate and visitDuration). Visitors add up too, so such a read carries meta.visitorsAre: 'sumOfDaily'. A source that answers weeks and months itself declares calendarBuckets: true.

What the capabilities gate

• A dashboard widget whose metric or dimension no configured adapter supports is not registered at all. An install with runtime providers registers every widget and degrades per request instead.
• A display field drops unsupported metrics from its request and renders the rest.
• A metric outside its metricReach for a breakdown is left out of that breakdown's columns and pickers.
• A filter whose dimension and operator the source does not list is refused before the read; a widget shows that the source cannot apply the filter.
• A custom range that exceeds maxLookbackDays is narrowed to it, visibly.

Metrics

MetricKey is pageviews, visitors, visits, sessions, bounceRate, avgDuration, visitDuration, scrollDepth, events, conversions, revenue, impressions and interactions. Each means one thing on every source, and a source that cannot measure it does not declare it:

• avgDuration is time on page: engaged time per pageview, an average in milliseconds over the pageviews read.
• visitDuration is time per visit: engaged time per visit, an average in milliseconds over the visits read.
• visits and sessions are one count. A source serving both answers the same number for each, and the admin shows it once, as Visits; an adapter of your own that answers them as two different numbers loses visits there.
• bounceRate is a percentage of visits; scrollDepth a percentage of the page's height.
• conversions and revenue count this install's goals, never whatever the vendor counts install-wide.
• impressions and interactions are a content item's views and clicks.

Concepts says what each one means to a reader.

A row's metrics map each key to a MetricValue, number | null. null is an average or a share with nothing to average over: avgDuration with no pageviews, visitDuration with no visits, scrollDepth that no pageview reported, bounceRate with no sessions. That is no data, which every surface shows as a dash and never compares, where a 0 would read as a measured zero-second visit. The vendor adapters keep a vendor's own null, or a value it left out, apart from 0 the same way: an average stays null, and only a count with no value reads 0. An adapter of your own answers those the same way; a count is never null.

A row may carry samples, how many observations each average was taken over (sessions behind a bounce rate, pageviews behind an average time), which is what folds days into weeks exactly.

Dimensions

DIMENSION_KEYS lists every dimension the contract defines: page, referrer, source, channel, medium, campaign, utmSource, utmMedium, utmCampaign, utmContent, utmTerm, device, browser, os, country, region, city, language, event, goal, currency and item. No adapter serves all of them; the capabilities exist so that never matters. source is the visit's named origin and channel its acquisition channel on every adapter that serves them (source and channel).

A read asking for the goal dimension or the conversions metric also carries query.goalSlugs, the scope's goal slugs, which is 'unresolved' when resolving them failed. A provider adapter restricts its goal rows to them, sets meta.goalsUnresolved when it was given no slugs to restrict by, and answers empty rows unflagged when the scope configured no goals.

Filters

AnalyticsQuery.filters narrows a read to rows matching one or more { dimension, operator, value } entries. List in capabilities.filters only the dimension and operator pairs you apply: the engine refuses a read carrying any other pair before your adapter sees it, rather than letting it answer unfiltered numbers that would read as filtered. Leave filters out for an adapter that applies none. FILTER_OPERATORS lists the three operators; each source's own semantics for them are on Providers.

A source that cannot carry a filter it declared (an API taking one value per parameter) lists what it dropped in meta.unappliedFilters, so a surface can say the rows are wider than it asked for.

Results

query() answers an AnalyticsResult: rows (each with dimensions, metrics, an optional timestamp for a series bucket and optional samples), optional totals, and meta. meta.provider and meta.fetchedAt are required.

meta.fetchedAt is when the source was read, as an ISO instant: stamp it from ctx.now(), the plugin's clock, falling back to new Date() outside the engine. It is never the range's end. The engine replaces a fetchedAt later than the moment it got the answer, or one it cannot read, with that moment, and a cached answer keeps the stamp it was stored with. An adapter sets these when they apply:

The read engine sets stale, asOf and sourceError on a cached answer; the native engine sets partial, capped, failed, timezoneUnresolved and mixedCurrencies, and asOf when a snapshot answered. The query endpoint says what each means. failed counts the days whose counting failed again and again until the engine gave up: each is read from an earlier count when it had one, and left out otherwise. The read engine also sets clamped and dataFrom itself when it narrows a range to the source's maxLookbackDays, and narrows a source with no lookback to 1970. The native engine sets clamped at either end for a day the range cuts partway once retention has deleted its raw hits: a cut day with no hits is left out silently, and one with hits is left out with dataFrom or dataTo (Dates and the reporting timezone).

A breakdown may ignore limit and order: the engine ranks and cuts what an adapter answers before caching it. A breakdown read with a limit and no order reaches the adapter with order set to its first metric, descending, so an adapter that honors limit hands over the top rows the engine ranks by.

Writing your own adapter

Implement AnalyticsAdapter from @10x-media/analytics/types: an id, a label, honest capabilities, isConfigured(), and query(query, ctx) returning rows and totals. Optional extras are realtime(query, ctx) and the lifecycle hooks below. Declare only capabilities you actually serve.

ctx is an AdapterContext:

Lifecycle

The register context

register receives an AdapterRegisterContext, the plugin's own settings for an adapter to follow rather than read twice:

registerSchema receives an AdapterSchemaContext, { jobs, notice? }.

Requests to the vendor

The engine sends each read through the source's lane, which keeps to capabilities.rateLimit, bounds how many requests are out at once, retries outages, and stops asking a source that keeps failing for a while, through a circuit breaker per scope. By default a whole query call counts as one request. An adapter that makes several vendor requests per read declares capabilities.upstreamAware: true and sends each one through ctx.upstream, so each spends its own token and slot and a failed one is retried alone:

import type { AdapterContext, AnalyticsQuery, AnalyticsResult } from '@10x-media/analytics/types'

declare function fetchTotals(query: AnalyticsQuery, signal?: AbortSignal): Promise<AnalyticsResult>
declare function fetchSeries(query: AnalyticsQuery, signal?: AbortSignal): Promise<AnalyticsResult>

export async function query(query: AnalyticsQuery, ctx: AdapterContext): Promise<AnalyticsResult> {
  const send = <T,>(fn: (signal?: AbortSignal) => Promise<T>) =>
    ctx.upstream ? ctx.upstream(fn) : fn(ctx.signal)
  const [totals, series] = await Promise.all([
    send((signal) => fetchTotals(query, signal)),
    send((signal) => fetchSeries(query, signal)),
  ])
  return { rows: series.rows, totals: totals.totals, meta: totals.meta }
}

ctx.upstream is absent when something other than the engine calls the adapter (a test, a script), hence the fallback. Pass the signal it hands you to the request, so a read that gives up stops it. An SDK that takes a deadline instead of a signal reads ctx.remainingMs().

A request that ignores its signal and never settles would hold its lane slot for good, so five seconds after its read gave up its slot goes back, it counts against the breaker as a timeout, and the log says so once per source. Pass the signal to every request you send.

Errors

What an adapter throws decides how the read fails, so throw what the vendor said:

ProviderHttpError and parseRetryAfter, both from @10x-media/analytics, are what the built-in adapters throw with: new ProviderHttpError(status, adapterId, { message, retryAfterMs }) carries a status and the vendor's wait, and parseRetryAfter(response.headers.get('retry-after')) reads a Retry-After in seconds or as an HTTP date into milliseconds, capped at ten minutes.

The error codes say what each one answers.

Capture support

An adapter that can capture declares capture, a CaptureSupport: client (what the browser tracker boots for it, with its kind), snippet(args) (the scripts the page renders or injects), proxy (the routes the first-party proxy forwards), and optionally cookieless and withoutConsent, below. Read credentials are never part of it; only what the browser is allowed to see.

snippet receives SnippetArgs:

A snippet that ignores mode and withoutConsent renders as it did in 1.0.0-beta.14.

cookieless declares how the vendor counts without consent, a CookielessSupport: { kind: 'inherent' } for a vendor that never stores anything on the device, so one snippet serves every phase (native, Plausible, Umami), or { kind: 'switched' } for one whose client the tracker switches between cookieless and full (PostHog, GA4). default is the level capture.withoutConsent: 'cookieless' gives the slot, 'cookieless' unless set; GA4 declares 'off'. An adapter that declares no cookieless sends nothing without consent, whatever the install says, which is how a custom adapter written before 1.0.0-beta.15 keeps behaving. withoutConsent carries the adapter's own setting ('off', 'cookieless' or 'anonymous'), from its factory option or provider document, and beats capture.withoutConsent for its slot in both phases; it is ignored without cookieless. How a slot's level is resolved is on Consent.

The tracker switches a vendor's client through the sink for its client.kind, one of the five built-in kinds, on every grant, refusal and exclusion change: off, cookieless or full, as The vendor slots lists per vendor. The sinks are the tracker's own, so an adapter declares what its snippet starts and leaves the switching to them.

proxy.routes lists each forwarded route as { source, upstream, kind }. kind is required and decides how the runtime proxy serves the answer: 'script' for anything the browser runs, always served as JavaScript, and 'data' for everything else, kept as JSON or plain text, sandboxed and never cached. proxy.forwardHeaders names extra request headers to pass on (never cookies or authorization), proxy.trailingSlashes keeps a request's trailing slash upstream, and proxy.fetch is what the proxy reaches the vendor with.

Declare capture only when the public capture config it needs is present: an adapter configured for reads alone declares none, fills no capture slot and contributes no proxy route.

Testing: memoryAdapter

import { memoryAdapter } from '@10x-media/analytics/testing'

const adapter = memoryAdapter()
adapter.record({ path: '/a', timestamp: new Date(), visitor: 'v1' })
// ...assert against widgets and fields; adapter.reset() between tests

A deterministic in-memory adapter for tests and local development. It serves pageviews, visitors, visits, sessions, bounceRate and avgDuration by page, referrer, country and device, realtime over five minutes, and filters page with eq. @10x-media/analytics/testing also exports the contract types, so a test of your own adapter imports everything from one entry.

Waiting for background work

The plugin does some of its work after a call has answered: it stores cached reads, runs the native engine's upkeep, and buffers hits when write batching is on. A test that reads back what it just tracked, or destroys Payload, waits for that first with settleAnalytics, which flushes the write buffer too:

import { trackServerEvent } from '@10x-media/analytics'
import { settleAnalytics } from '@10x-media/analytics/testing'
import type { Payload } from 'payload'

export const trackThenRead = async (payload: Payload) => {
  await trackServerEvent(payload, { type: 'pageview', path: '/pricing', hostname: 'example.com' })
  await settleAnalytics(payload)
  return payload.count({ collection: 'analytics-hits' })
}