Stability

@10x-media/analytics follows semantic versioning from 1.0.0: within a major release nothing public is removed or renamed, and a change that would break an install waits for the next major. Until 1.0.0 the package is published as betas under the beta dist-tag, and a beta may change what this page calls public; each such change is listed, with what to do about it, on Upgrading.

What is public

Within a major release, these keep their names and their meaning:

• Exports. Every export of every entry point that carries no @beta or @internal tag (Entry points lists them, with their tags). memoryAdapter and settleAnalytics from @10x-media/analytics/testing are among them.
• Options. Every path on Options, with its type and its default, except the @beta ones: view.Component, everything under widgets, and countryFlags, which belong with the dashboard widgets and the view's building blocks.
• Component paths. The paths the plugin registers in your import map.
• Styling. The CSS classes and the --analytics-* tokens Customizing documents.
• Endpoints. Every endpoint: its method, its path under routes.base, its parameters, its success shape (a release may add optional fields) and the error envelope { error: { code, message, param? } }.
• Browser names. The analytics:exclude storage key and the analytics_exclude query parameter.
• Collections you manage. The goals, providers and sync collections: their default slugs and the fields they hold. A minor release may add a field to one, never remove or rename one.

The other collections, analytics-hits, analytics-aggregates, analytics-state and analytics-cache, are the engine's and the cache's own storage. They are hidden, have no REST or GraphQL endpoints, and are not an interface: read them through the plugin's reads, not through payload.find. A minor release may change their fields and indexes.

Whatever collection a release changes, its Upgrading page and its changelog say so. On Postgres and SQLite in migrate mode that takes a migration generated with payload migrate:create, with any edits the page lists; where stored rows have to move or go, the release ships a predefined migration or a helper in @10x-media/analytics/migrations for it.

Release tags

Every export carries one of these in its declaration, and the API reports in the package's repository list them per entry:

Open unions

These union types may gain members in a minor release, so code that switches over one handles a member it does not know, as a generic case of its kind, rather than exhausting it:

MetricKey, DimensionKey, TrafficChannel, AnalyticsErrorCode (and its alias QueryErrorCode), FilterOperator, Granularity, CaptureClientKind, ProviderId, TimeframePreset, GoalSource, BuiltInWidgetSlug, TranslationKey, the read statuses FieldReadStatus, WidgetReadStatus and WidgetRealtimeStatus, and SourceErrorKind.

A translation key is removed only in a major release, even one the plugin no longer reads: pluginName stays, and an override of it is still accepted. A key's text, in any language, may change in any release: a label is wording, not contract.

These change only in a major release: CaptureSlot (global and tenant), the gate states (GateStatus: pending, open, closed), and the shape of every option but the @beta ones above.

Interfaces you implement or receive

• AnalyticsAdapter and its capabilities may gain optional members in a minor release; an adapter of your own keeps compiling and working without them.
• The seams you implement: CacheStore (cache.store), GeoResolver (native({ geoResolver })) and ProvidersResolve (providers.resolve). What the plugin passes them may gain optional fields in a minor release; what they must implement and answer changes only in a major.
• Tracker may gain members in a minor release. Use the tracker initTracker, createTracker, <AnalyticsScripts /> or <AnalyticsProvider> gives you; do not implement Tracker yourself.
• A result shape (an endpoint's answer, a read helper's result, AnalyticsResult.meta) may gain optional fields.

Component paths

The plugin and its field factories register these paths in your Payload config, and payload generate:importmap writes them into your import map. They are frozen for the 1.x line: a component that moves keeps its old path as a re-export.

Five paths 1.0.0-beta.11 registered are kept as re-exports, so an import map generated before the upgrade still renders a working picker, keyed by the scope the page's cookies select rather than the server's: @10x-media/analytics/client#SourceSelectField, #MetricSelectField, #FilterDimensionSelectField, #FilterOperatorSelectField and #GoalSelectField. Each is @deprecated, naming its replacement (@10x-media/analytics/rsc#SourceSelectFieldServer and its siblings above), and stays frozen with the rest of this table. Regenerate the import map to move to the server paths.

Supported versions