@10x-media/analytics 1.0.0-beta.7 → 1.0.0-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +118 -0
- package/LICENSE +21 -21
- package/README.md +10 -4
- package/dist/adapters/ga4/eventName.d.ts +15 -0
- package/dist/adapters/ga4/eventName.js +19 -0
- package/dist/adapters/ga4/eventName.js.map +1 -0
- package/dist/adapters/ga4/ga4.d.ts +5 -0
- package/dist/adapters/ga4/ga4.js +179 -70
- package/dist/adapters/ga4/ga4.js.map +1 -1
- package/dist/adapters/ga4/measurementId.js +15 -0
- package/dist/adapters/ga4/measurementId.js.map +1 -0
- package/dist/adapters/goalRead.js +126 -0
- package/dist/adapters/goalRead.js.map +1 -0
- package/dist/adapters/plausible/plausible.d.ts +15 -0
- package/dist/adapters/plausible/plausible.js +112 -43
- package/dist/adapters/plausible/plausible.js.map +1 -1
- package/dist/adapters/posthog/posthog.js +47 -25
- package/dist/adapters/posthog/posthog.js.map +1 -1
- package/dist/adapters/umami/umami.d.ts +8 -0
- package/dist/adapters/umami/umami.js +237 -28
- package/dist/adapters/umami/umami.js.map +1 -1
- package/dist/capture/slots.js +16 -5
- package/dist/capture/slots.js.map +1 -1
- package/dist/capture/trackerConfig.d.ts +1 -0
- package/dist/capture/trackerConfig.js +28 -3
- package/dist/capture/trackerConfig.js.map +1 -1
- package/dist/charts/BarList.d.ts +15 -1
- package/dist/charts/BarList.js +41 -19
- package/dist/charts/BarList.js.map +1 -1
- package/dist/charts/TrendChart.d.ts +16 -3
- package/dist/charts/TrendChart.js +172 -106
- package/dist/charts/TrendChart.js.map +1 -1
- package/dist/charts/bars.d.ts +2 -0
- package/dist/charts/bars.js +2 -1
- package/dist/charts/bars.js.map +1 -1
- package/dist/charts/bucket.js +10 -1
- package/dist/charts/bucket.js.map +1 -1
- package/dist/charts/spline.js +2 -2
- package/dist/charts/spline.js.map +1 -1
- package/dist/charts/styles.js +18 -1
- package/dist/charts/styles.js.map +1 -1
- package/dist/core/cacheKey.js +24 -2
- package/dist/core/cacheKey.js.map +1 -1
- package/dist/core/capabilities.js +7 -2
- package/dist/core/capabilities.js.map +1 -1
- package/dist/core/capture.d.ts +1 -1
- package/dist/core/contract.d.ts +46 -9
- package/dist/core/contract.js +29 -1
- package/dist/core/contract.js.map +1 -1
- package/dist/core/granularity.js +1 -1
- package/dist/core/options.d.ts +62 -7
- package/dist/core/options.js +63 -4
- package/dist/core/options.js.map +1 -1
- package/dist/core/scopedRead.js +33 -23
- package/dist/core/scopedRead.js.map +1 -1
- package/dist/core/serverEvent.d.ts +44 -0
- package/dist/core/serverEvent.js +12 -0
- package/dist/core/serverEvent.js.map +1 -0
- package/dist/exports/adapters/ga4.d.ts +2 -1
- package/dist/exports/adapters/ga4.js +2 -1
- package/dist/exports/client.d.ts +12 -3
- package/dist/exports/client.js +9 -1
- package/dist/exports/rsc.d.ts +7 -2
- package/dist/exports/rsc.js +6 -3
- package/dist/exports/tracker.d.ts +3 -2
- package/dist/exports/tracker.js +2 -1
- package/dist/exports/types.d.ts +13 -4
- package/dist/exports/types.js +3 -2
- package/dist/fields/AnalyticsPanelClient.js +1 -1
- package/dist/fields/AnalyticsPanelField.js +1 -1
- package/dist/fields/AnalyticsStatField.js +2 -2
- package/dist/fields/config/FilterDimensionSelectField.d.ts +14 -0
- package/dist/fields/config/FilterDimensionSelectField.js +77 -0
- package/dist/fields/config/FilterDimensionSelectField.js.map +1 -0
- package/dist/fields/config/FilterOperatorSelectField.d.ts +14 -0
- package/dist/fields/config/FilterOperatorSelectField.js +75 -0
- package/dist/fields/config/FilterOperatorSelectField.js.map +1 -0
- package/dist/fields/config/MetricSelectField.js +3 -3
- package/dist/fields/config/MetricSelectField.js.map +1 -1
- package/dist/fields/config/SourceSelectField.js +3 -3
- package/dist/fields/config/SourceSelectField.js.map +1 -1
- package/dist/fields/config/fetchSources.d.ts +5 -1
- package/dist/fields/config/sourcesState.js +19 -3
- package/dist/fields/config/sourcesState.js.map +1 -1
- package/dist/fields/config/useAnalyticsSources.d.ts +8 -3
- package/dist/fields/config/useAnalyticsSources.js +9 -6
- package/dist/fields/config/useAnalyticsSources.js.map +1 -1
- package/dist/fields/config/useFilterCapabilities.d.ts +28 -0
- package/dist/fields/config/useFilterCapabilities.js +52 -0
- package/dist/fields/config/useFilterCapabilities.js.map +1 -0
- package/dist/fields/readForDocument.d.ts +5 -0
- package/dist/fields/readForDocument.js +21 -9
- package/dist/fields/readForDocument.js.map +1 -1
- package/dist/goals/GoalSelectField.d.ts +7 -0
- package/dist/goals/GoalSelectField.js +77 -0
- package/dist/goals/GoalSelectField.js.map +1 -0
- package/dist/goals/collection.js +250 -0
- package/dist/goals/collection.js.map +1 -0
- package/dist/goals/currency.js +14 -0
- package/dist/goals/currency.js.map +1 -0
- package/dist/goals/fetchGoals.d.ts +18 -0
- package/dist/goals/fetchGoals.js +29 -0
- package/dist/goals/fetchGoals.js.map +1 -0
- package/dist/goals/goalField.d.ts +31 -0
- package/dist/goals/goalField.js +56 -0
- package/dist/goals/goalField.js.map +1 -0
- package/dist/goals/goalsEndpoint.d.ts +1 -0
- package/dist/goals/goalsEndpoint.js +55 -0
- package/dist/goals/goalsEndpoint.js.map +1 -0
- package/dist/goals/resolver.d.ts +8 -0
- package/dist/goals/resolver.js +147 -0
- package/dist/goals/resolver.js.map +1 -0
- package/dist/goals/trackGoalAction.d.ts +74 -0
- package/dist/goals/trackGoalAction.js +139 -0
- package/dist/goals/trackGoalAction.js.map +1 -0
- package/dist/goals/useAnalyticsGoals.d.ts +20 -0
- package/dist/goals/useAnalyticsGoals.js +67 -0
- package/dist/goals/useAnalyticsGoals.js.map +1 -0
- package/dist/index.d.ts +12 -3
- package/dist/index.js +75 -11
- package/dist/index.js.map +1 -1
- package/dist/native/collections/events.js +36 -0
- package/dist/native/collections/events.js.map +1 -1
- package/dist/native/eventScan.js +25 -0
- package/dist/native/eventScan.js.map +1 -0
- package/dist/native/ingest/browser.js +47 -0
- package/dist/native/ingest/browser.js.map +1 -0
- package/dist/native/ingest/device.js +11 -3
- package/dist/native/ingest/device.js.map +1 -1
- package/dist/native/ingest/endpoint.d.ts +1 -0
- package/dist/native/ingest/endpoint.js +2 -17
- package/dist/native/ingest/endpoint.js.map +1 -1
- package/dist/native/ingest/flushBatch.js +26 -26
- package/dist/native/ingest/flushBatch.js.map +1 -1
- package/dist/native/ingest/language.js +14 -0
- package/dist/native/ingest/language.js.map +1 -0
- package/dist/native/ingest/normalizeEvent.d.ts +26 -0
- package/dist/native/ingest/normalizeEvent.js +35 -7
- package/dist/native/ingest/normalizeEvent.js.map +1 -1
- package/dist/native/ingest/referrer.js +48 -0
- package/dist/native/ingest/referrer.js.map +1 -0
- package/dist/native/ingest/serverTrack.d.ts +20 -0
- package/dist/native/ingest/serverTrack.js +100 -0
- package/dist/native/ingest/serverTrack.js.map +1 -0
- package/dist/native/ingest/source.d.ts +7 -0
- package/dist/native/ingest/source.js +139 -14
- package/dist/native/ingest/source.js.map +1 -1
- package/dist/native/ingest/utm.js +33 -0
- package/dist/native/ingest/utm.js.map +1 -0
- package/dist/native/ingest/validate.js +27 -0
- package/dist/native/ingest/validate.js.map +1 -0
- package/dist/native/nativeAdapter.d.ts +1 -1
- package/dist/native/nativeAdapter.js +53 -36
- package/dist/native/nativeAdapter.js.map +1 -1
- package/dist/native/query/eventAgg.js +14 -1
- package/dist/native/query/eventAgg.js.map +1 -1
- package/dist/native/retention/pruneTask.js +1 -1
- package/dist/native/rollups/bucketKey.js +15 -0
- package/dist/native/rollups/bucketKey.js.map +1 -0
- package/dist/native/rollups/bumpRollups.js +116 -0
- package/dist/native/rollups/bumpRollups.js.map +1 -0
- package/dist/native/rollups/deltas.js +30 -15
- package/dist/native/rollups/deltas.js.map +1 -1
- package/dist/native/rollups/insertManyIfNew.js +93 -0
- package/dist/native/rollups/insertManyIfNew.js.map +1 -0
- package/dist/next/captureRewrites.d.ts +3 -2
- package/dist/next/captureRewrites.js +3 -2
- package/dist/next/captureRewrites.js.map +1 -1
- package/dist/plugin/documentEndpoint.js +52 -15
- package/dist/plugin/documentEndpoint.js.map +1 -1
- package/dist/plugin/goalHint.d.ts +1 -0
- package/dist/plugin/goalHint.js +24 -0
- package/dist/plugin/goalHint.js.map +1 -0
- package/dist/plugin/paths.js +5 -1
- package/dist/plugin/paths.js.map +1 -1
- package/dist/plugin/queryEndpoint.js +120 -0
- package/dist/plugin/queryEndpoint.js.map +1 -0
- package/dist/plugin/readContextForRequest.js +71 -0
- package/dist/plugin/readContextForRequest.js.map +1 -0
- package/dist/plugin/realtimeEndpoint.js +43 -15
- package/dist/plugin/realtimeEndpoint.js.map +1 -1
- package/dist/plugin/responses.js +17 -0
- package/dist/plugin/responses.js.map +1 -0
- package/dist/plugin/runtime.js +31 -1
- package/dist/plugin/runtime.js.map +1 -1
- package/dist/plugin/scopeFieldBoot.js +22 -0
- package/dist/plugin/scopeFieldBoot.js.map +1 -0
- package/dist/plugin/sourcesEndpoint.js +21 -52
- package/dist/plugin/sourcesEndpoint.js.map +1 -1
- package/dist/plugin/warmTask.js +0 -0
- package/dist/plugin/warmTask.js.map +1 -1
- package/dist/providers/collection.js +29 -13
- package/dist/providers/collection.js.map +1 -1
- package/dist/providers/factory.js +4 -2
- package/dist/providers/factory.js.map +1 -1
- package/dist/providers/resolver.js.map +1 -1
- package/dist/query/dates.js +64 -0
- package/dist/query/dates.js.map +1 -0
- package/dist/query/errors.d.ts +17 -0
- package/dist/query/errors.js +10 -0
- package/dist/query/errors.js.map +1 -0
- package/dist/query/fetchQuery.d.ts +59 -0
- package/dist/query/fetchQuery.js +110 -0
- package/dist/query/fetchQuery.js.map +1 -0
- package/dist/query/parse.d.ts +22 -0
- package/dist/query/parse.js +168 -0
- package/dist/query/parse.js.map +1 -0
- package/dist/query/response.d.ts +39 -0
- package/dist/query/response.js +11 -0
- package/dist/query/response.js.map +1 -0
- package/dist/surfacing/engine.js +1 -1
- package/dist/surfacing/engine.js.map +1 -1
- package/dist/testing/memoryAdapter.js +0 -1
- package/dist/testing/memoryAdapter.js.map +1 -1
- package/dist/timeframe/tz.js +17 -6
- package/dist/timeframe/tz.js.map +1 -1
- package/dist/tracker/createTracker.js +13 -1
- package/dist/tracker/createTracker.js.map +1 -1
- package/dist/tracker/sinks/ga4.d.ts +21 -0
- package/dist/tracker/sinks/ga4.js +26 -0
- package/dist/tracker/sinks/ga4.js.map +1 -0
- package/dist/tracker/types.d.ts +5 -0
- package/dist/translations/ar.js +127 -1
- package/dist/translations/ar.js.map +1 -1
- package/dist/translations/de.js +127 -1
- package/dist/translations/de.js.map +1 -1
- package/dist/translations/en.js +127 -1
- package/dist/translations/en.js.map +1 -1
- package/dist/translations/es.js +127 -1
- package/dist/translations/es.js.map +1 -1
- package/dist/translations/fr.js +127 -1
- package/dist/translations/fr.js.map +1 -1
- package/dist/translations/id.js +127 -1
- package/dist/translations/id.js.map +1 -1
- package/dist/translations/keys.d.ts +126 -0
- package/dist/translations/keys.js +127 -1
- package/dist/translations/keys.js.map +1 -1
- package/dist/translations/ko.js +127 -1
- package/dist/translations/ko.js.map +1 -1
- package/dist/translations/metricKeys.js +8 -2
- package/dist/translations/metricKeys.js.map +1 -1
- package/dist/translations/pt.js +127 -1
- package/dist/translations/pt.js.map +1 -1
- package/dist/translations/ru.js +127 -1
- package/dist/translations/ru.js.map +1 -1
- package/dist/translations/server.js.map +1 -1
- package/dist/translations/uk.js +127 -1
- package/dist/translations/uk.js.map +1 -1
- package/dist/translations/zh.js +127 -1
- package/dist/translations/zh.js.map +1 -1
- package/dist/view/AnalyticsNavLink.d.ts +19 -0
- package/dist/view/AnalyticsNavLink.js +40 -0
- package/dist/view/AnalyticsNavLink.js.map +1 -0
- package/dist/view/AnalyticsView.d.ts +23 -0
- package/dist/view/AnalyticsView.js +45 -0
- package/dist/view/AnalyticsView.js.map +1 -0
- package/dist/view/AnalyticsViewClient.d.ts +15 -0
- package/dist/view/AnalyticsViewClient.js +200 -0
- package/dist/view/AnalyticsViewClient.js.map +1 -0
- package/dist/view/authRedirect.js +32 -0
- package/dist/view/authRedirect.js.map +1 -0
- package/dist/view/conversionRate.js +18 -0
- package/dist/view/conversionRate.js.map +1 -0
- package/dist/view/dayRange.js +68 -0
- package/dist/view/dayRange.js.map +1 -0
- package/dist/view/gating.d.ts +1 -0
- package/dist/view/gating.js +142 -0
- package/dist/view/gating.js.map +1 -0
- package/dist/view/labels.js +64 -0
- package/dist/view/labels.js.map +1 -0
- package/dist/view/registerView.js +48 -0
- package/dist/view/registerView.js.map +1 -0
- package/dist/view/sections/Breakdowns.js +197 -0
- package/dist/view/sections/Breakdowns.js.map +1 -0
- package/dist/view/sections/EmptyStates.js +92 -0
- package/dist/view/sections/EmptyStates.js.map +1 -0
- package/dist/view/sections/FilterChips.js +46 -0
- package/dist/view/sections/FilterChips.js.map +1 -0
- package/dist/view/sections/GoalsPanel.js +82 -0
- package/dist/view/sections/GoalsPanel.js.map +1 -0
- package/dist/view/sections/OverviewCards.js +65 -0
- package/dist/view/sections/OverviewCards.js.map +1 -0
- package/dist/view/sections/RealtimeStrip.js +80 -0
- package/dist/view/sections/RealtimeStrip.js.map +1 -0
- package/dist/view/sections/Toolbar.js +186 -0
- package/dist/view/sections/Toolbar.js.map +1 -0
- package/dist/view/sections/Trend.js +125 -0
- package/dist/view/sections/Trend.js.map +1 -0
- package/dist/view/sections/styles.js +74 -0
- package/dist/view/sections/styles.js.map +1 -0
- package/dist/view/state.js +211 -0
- package/dist/view/state.js.map +1 -0
- package/dist/view/useViewQueries.js +153 -0
- package/dist/view/useViewQueries.js.map +1 -0
- package/dist/view/viewProps.d.ts +40 -0
- package/dist/view/viewProps.js +90 -0
- package/dist/view/viewProps.js.map +1 -0
- package/dist/widgets/AnalyticsBreakdownWidget.d.ts +2 -1
- package/dist/widgets/AnalyticsBreakdownWidget.js +78 -11
- package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
- package/dist/widgets/AnalyticsGoalsWidget.d.ts +14 -0
- package/dist/widgets/AnalyticsGoalsWidget.js +196 -0
- package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -0
- package/dist/widgets/AnalyticsMetricWidget.d.ts +2 -1
- package/dist/widgets/AnalyticsMetricWidget.js +63 -13
- package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
- package/dist/widgets/AnalyticsRealtimeWidget.d.ts +2 -1
- package/dist/widgets/AnalyticsRealtimeWidget.js +44 -22
- package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
- package/dist/widgets/AnalyticsTrendWidget.d.ts +2 -1
- package/dist/widgets/AnalyticsTrendWidget.js +79 -16
- package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
- package/dist/widgets/RealtimeCounter.d.ts +4 -0
- package/dist/widgets/RealtimeCounter.js +10 -1
- package/dist/widgets/RealtimeCounter.js.map +1 -1
- package/dist/widgets/WidgetViewLink.js +17 -0
- package/dist/widgets/WidgetViewLink.js.map +1 -0
- package/dist/widgets/breakdownTypes.js +28 -1
- package/dist/widgets/breakdownTypes.js.map +1 -1
- package/dist/widgets/cardChrome.js +31 -7
- package/dist/widgets/cardChrome.js.map +1 -1
- package/dist/widgets/comparison.js +15 -1
- package/dist/widgets/comparison.js.map +1 -1
- package/dist/widgets/defaults.d.ts +6 -2
- package/dist/widgets/defaults.js +72 -25
- package/dist/widgets/defaults.js.map +1 -1
- package/dist/widgets/filterCaption.js +27 -0
- package/dist/widgets/filterCaption.js.map +1 -0
- package/dist/widgets/filterField.d.ts +19 -0
- package/dist/widgets/filterField.js +75 -0
- package/dist/widgets/filterField.js.map +1 -0
- package/dist/widgets/prepareWidgetRead.d.ts +7 -0
- package/dist/widgets/prepareWidgetRead.js +74 -0
- package/dist/widgets/prepareWidgetRead.js.map +1 -0
- package/dist/widgets/range.js +43 -12
- package/dist/widgets/range.js.map +1 -1
- package/dist/widgets/readForWidget.d.ts +24 -2
- package/dist/widgets/readForWidget.js +34 -48
- package/dist/widgets/readForWidget.js.map +1 -1
- package/dist/widgets/readForWidgetBreakdown.d.ts +32 -1
- package/dist/widgets/readForWidgetBreakdown.js +32 -42
- package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
- package/dist/widgets/readForWidgetGoals.d.ts +67 -0
- package/dist/widgets/readForWidgetGoals.js +140 -0
- package/dist/widgets/readForWidgetGoals.js.map +1 -0
- package/dist/widgets/readForWidgetRealtime.d.ts +8 -0
- package/dist/widgets/readForWidgetRealtime.js +21 -20
- package/dist/widgets/readForWidgetRealtime.js.map +1 -1
- package/dist/widgets/readForWidgetSeries.d.ts +24 -1
- package/dist/widgets/readForWidgetSeries.js +63 -56
- package/dist/widgets/readForWidgetSeries.js.map +1 -1
- package/dist/widgets/readMeta.js +18 -0
- package/dist/widgets/readMeta.js.map +1 -0
- package/dist/widgets/registerWidgets.js +53 -7
- package/dist/widgets/registerWidgets.js.map +1 -1
- package/dist/widgets/types.d.ts +15 -0
- package/dist/widgets/types.js +12 -1
- package/dist/widgets/types.js.map +1 -1
- package/dist/widgets/viewLink.d.ts +22 -0
- package/dist/widgets/viewLink.js +86 -0
- package/dist/widgets/viewLink.js.map +1 -0
- package/package.json +9 -4
- package/dist/native/rollups/applyDistinctDeltas.js +0 -9
- package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
- package/dist/native/rollups/bumpRollup.js +0 -73
- package/dist/native/rollups/bumpRollup.js.map +0 -1
- package/dist/native/rollups/insertIfNew.js +0 -19
- package/dist/native/rollups/insertIfNew.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,123 @@
|
|
|
1
1
|
# @10x-media/analytics
|
|
2
2
|
|
|
3
|
+
## 1.0.0-beta.9
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- **Fixed: a failed goal resolver no longer poisons the healthy cache entry.** When the goals resolver threw, the read carried an empty goal hint, the provider answered `meta.goalsUnresolved`, and the engine cached that answer at the aggregate TTL under the same key a healthy read with no goals uses. The hint is now three-way: the scope's slugs (an empty list when no goals are configured, which is an empty result rather than a failure), `'unresolved'` when the resolver failed (its own `goals:!unresolved` cache segment, which no list of slugs can produce, and the short realtime TTL), or absent when the read does not ask about goals.
|
|
8
|
+
|
|
9
|
+
**Behavioral for adapter authors: `AnalyticsQuery.goalSlugs` is typed `string[] | 'unresolved'`.** An adapter that reads the hint must handle the sentinel: the slugs to filter goal rows by, an empty list to filter by none, or a failure to report as `meta.goalsUnresolved` rather than as an empty table. The built-in provider adapters answer all three through one shared helper. `GET /api/analytics/query` echoes the hint it used under `query.goalSlugs`, so a client can tell a scope with no goals from a resolver that failed.
|
|
10
|
+
|
|
11
|
+
**Fixed: a scope with no goals says so instead of reading as nobody converting.** The goals panel, the goals widget and both goal breakdowns fell through to the plain "No data yet" whenever the scope configured no goals. They now render `stateNoGoals` ("No goals are configured for this scope", in all 11 locales) for that case, keeping the unresolved-goals state for a source that could not answer at all.
|
|
12
|
+
|
|
13
|
+
**Fixed: a sampled native read says so everywhere.** A filtered or hourly native read that hits the event scan limit sets `meta.sampled`; `realtime()` now sets it too (both paths build their meta through one `eventScanMeta`), and the view and the widgets show a notice for it beside the clamped and stale ones instead of presenting truncated numbers as exact. **Additive:** the realtime strip and the realtime widget carry the notice through their polls, and `RealtimeCounter` gained two optional props for it, `initialSampled` and `sampledLabel`, with no notice rendered when the label is left off.
|
|
14
|
+
|
|
15
|
+
**Behavioral: every widget carries the same read flags.** The five widget read helpers share one prologue and one meta mapping, so the metric widget now shows the unresolved-goals notice for `conversions` and the trend widget shows the stale notice, both of which they used to omit while their siblings showed them.
|
|
16
|
+
|
|
17
|
+
**Fixed: the realtime endpoint answers 503 with `Retry-After` when its source fails**, matching the query endpoint, instead of an unhandled 500. A gate that throws is not retryable and answers 500 instead, since polling again cannot fix a configuration bug. The realtime, sources and document endpoints send `cache-control: private, no-store` like the query endpoint, since all of them answer per reader.
|
|
18
|
+
|
|
19
|
+
**Behavioral: `analyticsDefaultWidgets()` lists every built-in widget.** The default dashboard layout stopped at the seven widgets of Phase 3a and omitted goals, realtime, referrers, browsers, operating systems, campaigns and events; it now places all of them. Installs that passed their own layout are unaffected.
|
|
20
|
+
|
|
21
|
+
- **Additive: native dimensions.** The native engine now serves `referrer`, `region`, `city`, `browser`, `os`, `language`, `utmSource`, `utmMedium`, `utmCampaign`, `utmContent` and `utmTerm` as breakdown dimensions, from the rollup and the filtered read paths alike, and all eleven are filterable with `eq` and `contains`. Browser and OS are classified from the user agent at ingest with a small built-in table, language from the request's first accepted language, and the campaign keys (case preserved, capped at 128) from a new `query` field the tracker sends with pageviews. The referrers, browsers, operating systems and campaigns widgets therefore rank rows on a native-only install instead of being skipped for lack of a serving adapter. Native's `filters` set is now every dimension it serves except `goal`, whose completions live in a json column rather than a field a `where` can compare.
|
|
22
|
+
|
|
23
|
+
**Additive: `capture.autoCapture.query`** (default true). The tracker sends each pageview's query string, without its leading `?` and capped at 512 characters, so ingest can extract the five `utm_*` keys. The raw query is never stored, only those five values; set the option false to stop sending it at all, at the cost of the campaign breakdowns.
|
|
24
|
+
|
|
25
|
+
**Breaking (native installs):** the events collection gains nine text columns (`browser`, `os`, `language`, the five `utm*`, and `referrerHost`, the bare host the `referrer` dimension groups and filters on). Postgres migrate-mode installs must run the migration in the native docs before upgrading; it is idempotent and deliberately not reversible, since dropping the columns would discard already-attributed events. Mongo needs nothing, and push-mode installs pick the columns up on the next boot. Events ingested before the migration keep their old attribution: nothing is backfilled.
|
|
26
|
+
|
|
27
|
+
**Additive: a group-by picker per breakdown tab.** Each breakdown tab in the analytics view read one dimension, so the eleven new ones were unreachable in the view, and most had no widget either. A tab that groups by more than one dimension the source serves now carries a **Group by** select beside the row limit: technology switches between devices, browsers and operating systems, geography between countries, regions, cities and languages, sources between the source dimension, the referrer and every campaign key. The pick is URL state (`dim`), omitted when it is the tab's default, and dropped when the selected source cannot serve it. Breakdown widgets pass their own dimension into their view link, so the browsers, operating systems, referrers and campaigns widgets now open the view on the grouping they were showing.
|
|
28
|
+
|
|
29
|
+
**Behavioral (the Sources tab's default):** the tab now opens on `source` rather than `referrer`. That is no change on native, which did not serve `referrer` before this release, but a provider serving both (Plausible, GA4) opens the Sources tab on the derived source instead of the referring host it used to rank. The referring host is one pick away in the new **Group by** select, and an existing link naming `tab=sources` opens on the new default unless it also carries `dim=referrer`.
|
|
30
|
+
|
|
31
|
+
**Behavioral (the breakdown panel while it refetches):** a read kept on screen through a refetch answers the grouping asked for when it was issued, so switching tab or dimension used to rank the previous grouping's rows under the new column header with no labels at all. The panel now shows its skeleton until the read for the grouping on screen lands.
|
|
32
|
+
|
|
33
|
+
**Fixed:** bar-list rows are keyed by rank rather than by label. Two rows sharing a label (a provider answering an unattributed bucket as an empty string) collided, and React stranded the duplicates in the DOM across a rerender, leaving rows on screen that belonged to no read.
|
|
34
|
+
|
|
35
|
+
**Behavioral:** the `referrer` dimension groups by the referring host (lowercased, `www.` stripped) and excludes same-site referrals, so a site's own domain can never top its own referrers breakdown; the `source` dimension calls those visits `Direct`. `source` now compares the event's own hostname case-insensitively, so a `Referer` differing from the site's host only in case counts as the one self-referral rule rather than as its own bucket. Stored referrers lose their query string and fragment and are capped at 512 characters (a same-origin referrer carries the previous page's whole URL, tokens included). Geo values (`country`, `region`, `city`) are capped at 128 characters. An ingest body whose `referrer` is not a string answers `202` and drops the field instead of failing with a `500`.
|
|
36
|
+
|
|
37
|
+
**Performance:** rollup and seen-ledger writes are batched per flush, one multi-row statement each, so a fully attributed pageview costs 4 database round trips instead of 161, and a buffered batch pays those writes once for the whole batch rather than once per event. Counting is unchanged.
|
|
38
|
+
|
|
39
|
+
**Storage:** rollup and seen-ledger rows grow with the cardinality of the new dimensions (referrer host, city, `utmContent`, `utmTerm`), plus one extra bucket set per distinct hostname you ingest from. `retentionDays` prunes events and the seen ledger only, never rollups, so plan storage for that tail.
|
|
40
|
+
|
|
41
|
+
- **Additive: comparison for every source.** Period-over-period comparison used to be a capability only the native and memory adapters declared. The previous-window read is done by the engine and works the same against any source, so it is now on for every adapter unless one sets `capabilities.comparison: false`; the four providers no longer opt out, and `comparison` is optional on `AnalyticsCapabilities` for adapters of your own (the serialized form the pickers read still carries a boolean). The compare toggle, the widgets' compare checkbox and `compare=previous` on the query endpoint therefore work on Plausible, GA4, Umami and PostHog. A source with `maxLookbackDays` cannot answer a previous window that starts before its lookback, measured from today: the view hides the toggle for such a window, the widgets and display fields omit the delta, and the endpoint answers the read without `comparison` instead of failing it. A far-past absolute range on such a source is still served (the engine clamps against the read's own end) but loses its comparison.
|
|
42
|
+
|
|
43
|
+
**Additive: the filter operators each provider API supports.** Plausible applies `eq`, `contains` and `matches` on every dimension it filters by (`is`, `contains`, `matches` in its Stats API v2 grammar, re2 full match). GA4 applies the same three through `stringFilter` (`EXACT`, `CONTAINS`, `FULL_REGEXP`), with exact and regex matches case-sensitive and `contains` case-insensitive like native and Umami. Umami now targets Umami 3.x: fifteen filterable dimensions (`page`, `referrer`, `browser`, `os`, `device`, `country`, `region`, `city`, `language`, `event` and the five `utm*`) with `eq`, `contains` and `matches` written as the API's `eq.`, `c.` and `re.` value prefixes, so `contains` is a case-insensitive substring and `matches` a case-insensitive partial regex there. Regex stays provider-only; native offers `eq` and `contains`. Umami accepts one value per query parameter, so two `eq` filters on one dimension with different values answer an empty result without a request, any other collision keeps the first filter (a per-page read keeps its page), an `eq` value carrying a comma is left out entirely because Umami reads such a value as a list and offers no escape, and what was not applied is reported in a new `meta.unappliedFilters` on the result.
|
|
44
|
+
|
|
45
|
+
**Behavioral (Umami):** the page breakdown asks `/metrics?type=path`; `type=url` was the 2.x name and Umami 3.x rejects it. Umami's breakdown rows report distinct sessions, so every breakdown row now carries `visitors` rather than a number labelled with whatever metric was asked for, and the view's breakdown charts the first metric the rows do carry when the selected one is absent. `event` is filterable but no longer groupable on Umami, since the install-wide `events` metric has no source in `/stats`.
|
|
46
|
+
|
|
47
|
+
**Additive: goals and conversions on every provider.** `conversions` and the `goal` dimension are served by Plausible (`event:goal`, conversions from `events` on goal rows, revenue from `total_revenue`), GA4 (`eventName` with `keyEvents`), PostHog (`event` with `count()`) and Umami (`/metrics?type=event`). A provider does not know which of its events are this install's goals, so reads that ask about goals carry the scope's goal slugs as `AnalyticsQuery.goalSlugs`, set by the query endpoint, the widgets and the display fields, and partitioning the cache. The slug of a goal must equal the provider's own name for it: the goal's display name on Plausible, the event name on PostHog and Umami, and on GA4 the slug normalized to a valid GA4 event name (hyphens become underscores, other characters outside letters, digits and underscores are dropped, a name not starting with a letter gains an `e_` prefix, 40 characters at most), which is also the name the GA4 sink sends; that normalization is exported as `ga4EventName` from `@10x-media/analytics/adapters/ga4`, so a host that dispatches its own gtag events can send the name the adapter reads back. A goal read with no goals in scope, or whose goal request the provider rejected, keeps its site numbers and reports `meta.goalsUnresolved`. A rejected goal request is cached for the source's realtime TTL rather than its aggregate one, so a transient provider failure does not pin "no conversions" for an hour, and every goal surface (the view's goals panel and goal breakdown, the goals widget, the goals breakdown widget) renders an empty state that says the goals could not be read instead of the plain no-data one. A filter the source could not carry raises a notice of its own on the view and on the metric, trend and breakdown widgets. When conversions ride along with site metrics, Plausible and GA4 issue a second, goal-filtered request and merge it per row, so such a read costs up to two provider requests; the second one runs after the first, inside the same limiter permit. GA4's `keyEvents` counts only events the property marks as key events. Umami serves conversions as goal rows and a range total only, so a conversions trend there shows no data, and the view's trend renders its empty state rather than a flat line of zeros. The goals widget and the goals tab now register for every provider.
|
|
48
|
+
|
|
49
|
+
**Behavioral (providers):** `conversions` on a provider means completions of this install's goals, as it does on native, rather than GA4's unfiltered key-event count. An install with no goals configured reads no conversions from a provider.
|
|
50
|
+
|
|
51
|
+
**Additive: Plausible `revenueCurrency`.** Plausible's `total_revenue` requires a revenue goal, so the adapter now declares `revenue` only when `revenueCurrency` (the ISO code of the site's revenue goals) is set, in config or on the provider document, and requests it only inside a goal-filtered request. Before, any read asking for revenue sent `total_revenue` unfiltered, which the API rejects.
|
|
52
|
+
|
|
53
|
+
**Additive: GA4 capture.** Set `measurementId` on the adapter or the provider document and the GA4 source fills a capture slot: the gtag tag loads from Google's own domain (no first-party proxy; the descriptor declares no routes), `gtag('config')` sends the first page view and history-change page views come from the web data stream's enhanced measurement (on by default, and the sink does not forward pageviews so it never double counts; an install that turns that stream option off should turn it back on), and the tracker forwards events and goals with `gtag('event', name, params)`. Consent is required by default, so the tag is not in the HTML before consent and is injected by the tracker once granted. The measurement id must match `^[A-Za-z0-9-]+$`; the provider document validates it and the adapter fills no slot otherwise. The tracker's own `file_download` auto-capture overlaps with enhanced measurement's, so downloads count twice on a GA4 slot unless one side is turned off. The sink is exported as `createGa4Sink` from `@10x-media/analytics/tracker`, beside the other vendor sinks. **Behavioral:** `CaptureClientKind` gains `'ga4'`, so an exhaustive `switch` over it in consumer code needs a new arm.
|
|
54
|
+
|
|
55
|
+
**Behavioral (PostHog):** the query's time bounds are sent as `toDateTime('...', 'UTC')`. HogQL reads a bare literal in the project's timezone, so a project set to anything but UTC was reading a window shifted by its offset; buckets are still cut in the reporting timezone.
|
|
56
|
+
|
|
57
|
+
**Fixed: two attacker-keyed lookups answer through the prototype.** `extractUtm` matched a page's query keys against an object literal, so `?constructor=x` or `?__proto__=x` resolved an inherited member and wrote a key `UtmParams` does not declare into the event row. The medium table the new `source` classifier reads is keyed by `utm_medium`, which is attacker-written in the same way, and an object literal there would have put a function in the `source` column, which a Postgres batch write rejects outright. Both lookups are `Map`s now, which answer nothing for a prototype name and make the return type honest; the view's channel-label table is guarded by a type predicate for the same reason.
|
|
58
|
+
|
|
59
|
+
**Breaking (native installs): `source` is a traffic channel.** The native `source` dimension buckets each pageview into `direct`, `search`, `social`, `email`, `paid` or `referral`, classified at ingest from `utm_medium` first, then paid click ids in the query (`gclid`, `fbclid`, `msclkid`, `ttclid`), then the referrer host against a small built-in list of search engines and social networks (a brand's country sites count, `google.co.uk` and `google.de`, while a host that merely contains the brand, `google.evil.com`, does not); no referrer or a same-site referrer is `direct`, any other host `referral`. Webmail hosts (`mail.google.com` and the like) count as `referral`, since a referrer cannot prove a newsletter. The `referrer` dimension keeps the host. The six channel values are stored as lowercase tokens and rendered through typed translations in the view and the widgets, so a Sources tab reads **Search** or **Direct** in the admin's locale while filters and links carry the token; they are exported as `TRAFFIC_CHANNELS` and the `TrafficChannel` type from `@10x-media/analytics/types`. Only a native row is named that way: a provider serves `source` as a raw `utm_source`, where a row reading `email` is the campaign parameter and not the Email channel, so those rows are shown as stored. Rows ingested before the upgrade keep the host values `source` used to store, and nothing is backfilled, so a Sources tab spanning the upgrade mixes the two until the old days age out of the window.
|
|
60
|
+
|
|
61
|
+
- **Additive: widget filters.** Metric, trend and breakdown widgets take one optional filter (dimension, operator, value). The dimension is the gate, the operator defaults to `eq`, and the value is trimmed and capped at 256 characters; a dimension without a value fails validation rather than saving a filter that narrows nothing. The two pickers offer only what the widget's chosen data source declares as filterable, in contract order, falling back to the union over the request's sources when no source is chosen, and a stored value the current source no longer offers stays visible (clearable on the dimension, which is the gate; the operator always has a value). The read applies the filter, the caption states it ("Last 30 days where Country is DE"), and the "Open in Analytics" link carries it into the view as `filters=`. The caption's two halves are translated templates: the sentence is `widgetFilterCaption` (`'where {{dimension}} {{operator}} {{value}}'`) and the join that puts it after the window is its own key, `widgetCaptionWithFilter` (`'{{window}} {{filter}}'`), which `zh` ships without the space. Both are overridable through the `translations` option.
|
|
62
|
+
|
|
63
|
+
A source that cannot apply the stored filter renders "This source cannot apply this filter" rather than silently ranking unfiltered rows: `readForWidget`, `readForWidgetBreakdown` and `readForWidgetSeries` answer `status: 'filter-unsupported'` without querying the adapter. Because the pickers offer the union when no source is chosen, a dimension filterable on one source and an operator declared on another can be configured together and answered this way at read time.
|
|
64
|
+
|
|
65
|
+
**Breaking (types): `WidgetReadStatus` gains `'filter-unsupported'`.** The type is exported from `/rsc`, so an exhaustive `Record<Exclude<WidgetReadStatus, 'ok'>, T>` or a switch a consumer wrote over it stops compiling until the new member is handled. Runtime behavior of existing code is unaffected; the compiler is the thing that breaks.
|
|
66
|
+
|
|
67
|
+
**Behavioral: a widget filter that the source cannot apply now reads `filter-unsupported` where it read `unavailable` before.** Code branching on `status === 'unavailable'` to render its own "no data" message will stop matching those reads.
|
|
68
|
+
|
|
69
|
+
**Behavioral: a widget's caption renders only with the data it describes.** The breakdown widget used to render its range caption below a not-configured or unavailable message, captioning a window it had not read; it now returns title, message and link, as the metric and trend widgets already did.
|
|
70
|
+
|
|
71
|
+
**Additive API.** `widgetFilters` and the `WidgetFilter` type are exported from the root entry, so a custom widget storing the built-in filter group turns it into an `AnalyticsFilter[]` under the same rules. `FilterDimensionSelectField`, `FilterOperatorSelectField`, `useFilterCapabilities` and the `AnalyticsSources` type are exported from `/client`; `FilterCapabilities` carries `resolved` alongside `loading` and `error`, and `useAnalyticsSources` reports `loading` and `error` beside `sources`. The server `Translate` type accepts interpolation vars. 15 new translation keys ship in all 11 locales.
|
|
72
|
+
|
|
73
|
+
## 1.0.0-beta.8
|
|
74
|
+
|
|
75
|
+
### Minor Changes
|
|
76
|
+
|
|
77
|
+
- **Additive: goal surfaces.** `goals.collection` (`true`, or `{ enabled, slug, scopeField, access, overrides }`) enables an `analytics-goals` collection scoped exactly like providers: rows filter by the request's resolved scope, `scope` is stamped on write and a forged one is refused, platform admins read every scope, and slugs are unique per scope, checked on every write and backed by a unique index on `slug` for an unscoped install or on `(slug, scope)` once a `scopeResolver` is configured and the plugin owns the scope field. Two cases stay hook-guarded only: install-wide rows on a scoped Postgres install (Postgres treats a NULL scope as distinct), and a host-owned `scopeField`, which the plugin does not index. Enabled collection goals merge over config goals by slug, cached for 30 seconds per scope and invalidated on change (one read serves at most 500 enabled goals per scope), and reach the native ingest, the browser tracker config and the new `GET /api/analytics/goals` endpoint (authenticated, per scope, `{ goals: [{ slug, name, source }], collection }`).
|
|
78
|
+
|
|
79
|
+
`goalField()` is a field factory that stores a goal slug behind a picker of the request's goals, with `goalSlug()` for renderers; the picker follows native field rules (`admin.condition`, `admin.width`, `admin.description`, `admin.placeholder`), and it, `SourceSelectField` and `MetricSelectField` now resolve their path through Payload's field context, so all three behave inside blocks and array rows. `@10x-media/analytics/client` gains `GoalSelectField` and `useAnalyticsGoals` plus the `GoalsResponse` and `WireGoal` wire types, and `GoalFieldOptions` is exported from both the root and `/types`.
|
|
80
|
+
|
|
81
|
+
`trackServerEvent(payload, event, { req, flush })` records a pageview, event or goal from server code through the native ingest (no HTTP round trip, same sanitizers and goal matching). With `req` the event inherits that request's headers, so geo, device and the visitor hash follow the real request; with neither a `req` nor an explicit `userAgent` it is attributed to a stable synthetic server visitor per day per hostname and reports no device at all rather than counting as desktop. `flush: true` awaits a buffered write. An explicit `scope` is ignored on an unscoped install and is never validated against the scopes that exist. A missing required field rejects with `AnalyticsTrackError` naming the field, and nothing is written. Needs the native adapter.
|
|
82
|
+
|
|
83
|
+
`trackGoalAction({ hostname, path, scope })` returns a form-builder action definition (type `analyticsGoal`, exported as `GOAL_ACTION_TYPE`) with no form-builder dependency; register it as `actions: { [GOAL_ACTION_TYPE]: trackGoalAction({ hostname: 'example.com' }) }`. Treat `hostname` as required wherever a jobs runner queues actions, and `scope` as required there on a scoped install: a queued run carries the runner's request rather than the submitter's, so the fallback chain (option, request host, `serverURL` host, then throw) has nothing useful to fall back to. The action is not `essential`, so a failed write never fails the submission.
|
|
84
|
+
|
|
85
|
+
**Breaking (scoped installs on a custom scope field):** where `providers.collection.scopeField` or `goals.collection.scopeField` names a field the plugin does not own, the plugin no longer adds its own hidden `scope` text field to that collection, since shadowing the host's field stored the scope twice. Generated types change accordingly, and a scoped Postgres install on a custom `scopeField` wants a migration dropping the now-unused `scope` column. Boot also fails with a named error when the collection carries no field of that name (`analytics: goals.collection.scopeField "tenant" does not exist on analytics-goals; register the collection with your tenant plugin or use the default scope field`), where the same misconfiguration previously booted and misbehaved silently.
|
|
86
|
+
|
|
87
|
+
**Behavioral:** `resolveGoals` on the adapter register context and on the runtime resolves per scope once the collection is enabled, and a collection goal replaces the config goal of the same slug. The public tracker config, which was a snapshot of the config goals, now carries the request scope's merged goals, still trimmed to `slug`, `match`, `value` and `currency`, so an editor's fixed value and currency reach `trackGoal()` defaults and vendor sinks; a change reaches browsers within the 30 second resolver cache plus that endpoint's own `Cache-Control: private, max-age=60`. `AnalyticsAdapter.ingest` gains an optional `track`.
|
|
88
|
+
|
|
89
|
+
**Consumer steps:** regenerate the admin import map (`payload generate:importmap`) once a `goalField()` is in the config, so `GoalSelectField` resolves. On Postgres, enabling `goals.collection` adds a table: run `payload migrate:create` in the app afterwards, which generates the DDL from the collection config the way every other schema change in this plugin does.
|
|
90
|
+
|
|
91
|
+
Multi-tenant note: the goals collection uses the plugin's own `scope` field and the plugin's scope resolver. Registering it with `@payloadcms/plugin-multi-tenant` (a `tenant` relationship through `scopeField` plus an entry in that plugin's `collections`) is not supported yet: it hangs a tenant user's admin panel in the dev app and the cause is not diagnosed. Providers still support that wiring (`isGlobal: true`). Goals scope correctly either way (access, stamping, per-scope uniqueness, the picker, the tracker config and the endpoint all follow the resolved scope); what a multi-tenant install gives up today is the tenant selector filtering the goals list view. A fix is planned.
|
|
92
|
+
|
|
93
|
+
- **Additive: query endpoint.** `GET /api/analytics/query` reads any configured source through the surfacing engine for signed-in users allowed by `access.read`: metrics, up to two dimensions, a date range, granularity, filters, ordering, a row limit and an optional previous-period comparison, validated against the selected source's capabilities with coded `400` errors (`invalid_param`, `unsupported_metric`, `unsupported_dimension`, `unsupported_filter`, `unsupported_operator`, `unsupported_granularity`, `range_too_long`). Scope follows the same rules as the sources endpoint: it comes from the request, an explicit `scope` is honored only for platform readers (`400 untrusted_scope` otherwise), and a scoped install with no resolvable scope answers `404 unknown_source`. A listed shared source that cannot filter by scope still answers `403` for a tenant reader. Responses carry the normalized query (ISO date range), the source and its capabilities, and `meta.stale` when the engine served an expired cache entry; a provider outage with no cached answer is `503 unavailable` with `Retry-After`, and every answer is `Cache-Control: private, no-store`. Date-only bounds are interpreted in the reporting timezone (the whole `to` day included); datetime bounds must carry an offset. `fetchQuery`, `buildQueryUrl` and `QueryFetchError` from `/client` wrap the endpoint for admin code, and `QueryRequest` carries every parameter including the optional `scope` a platform reader needs; `QueryRequest`, `QueryResponse`, `QueryError` and the parser's own result types are exported from `/types`, where the contract's own key registries are now runtime values too: `DIMENSION_KEYS` and `FILTER_OPERATORS`, named here because picker and validator authors want the list rather than only the union type.
|
|
94
|
+
|
|
95
|
+
**Additive: `access.read`.** A new access option gating every authenticated read endpoint (document, realtime, sources, goals, query); it defaults to allowing any signed-in user, so existing installs see no change until they set it. It is independent of scope gating: granting `read` never widens which scope a user reads.
|
|
96
|
+
|
|
97
|
+
**Behavioral:** a `scopeResolver` that answers the platform wildcard (`'*'`) now requires `access.platformRead` on the sources endpoint too, so a non-platform user gets an empty source list instead of the config adapters.
|
|
98
|
+
|
|
99
|
+
**Behavioral:** GA4 and Plausible reads now format both range bounds as calendar days in the reporting timezone, and every widget and field on those two providers with a non-UTC `reportingTimezone` changes its numbers as a result. East of UTC the start date was one calendar day early, so a 30-day widget was querying 31 days and totals drop after the upgrade; west of UTC the end date named the following UTC day whenever local time was past the UTC rollover, so a trailing partial day is no longer included. Native, PostHog and Umami installs are unaffected.
|
|
100
|
+
|
|
101
|
+
- **Additive: analytics view.** A dedicated admin view at `/admin/analytics` (option `view: { path, defaultRange, defaultMetric, navLabel }`, `view: false` to disable, `access.view` to gate it, defaulting to `access.read`) built on the query endpoint. It shows overview cards with a previous-period comparison, a trend, capability-gated breakdown tabs (pages, sources, technology, geography, events, goals) with click-to-filter chips, a goals panel with conversion rate, and a realtime strip, for any configured source. Range, comparison, source, metric, granularity, tab, filters, row limit and sort live in the URL, so a view is a shareable link and Back undoes a change. Every control appears only when the selected source's capabilities allow it. Scope follows the request (the tenant selector on multi-tenant installs). `AnalyticsView` is exported from `/rsc`, `AnalyticsViewClient` and `AnalyticsNavLink` from `/client`, the option types from `/types`; `AnalyticsViewClientProps` gains `scopeKey`, the resolved scope the server rendered for, which keys the client so a tenant switch refetches. `@payloadcms/next` and `next` are now peer dependencies.
|
|
102
|
+
|
|
103
|
+
**Additive:** `BarList` gains two optional props. `onSelect` makes every row a button reporting its index (rows stay inert `div`s without it), and `fill="soft"` pales the bar and moves its label onto the elevation ramp, for a list whose rows can be zero-valued; the default `fill="solid"` is exactly the current widget look.
|
|
104
|
+
|
|
105
|
+
**Behavioral:** the admin gains an "Analytics" nav link and the `/analytics` route by default; set `view: false` to opt out. The `visits` metric is now labelled "Visits" wherever a metric label is rendered (display fields, the document panel and the view's cards); it carried the "Visitors" label before. No widget metric picker offers `visits`, so widget configuration is unaffected.
|
|
106
|
+
|
|
107
|
+
**Breaking: custom ranges follow the reporting timezone.** A custom widget range and a document read with a custom `from`/`to` now interpret the picked days in the reporting timezone and include the whole final day; captions show the picked days. Previously the picker's stored instant (the admin browser's local midnight) was used as-is, so the final day was mostly dropped and providers could disagree by hemisphere. Numbers move on installs whose admin browsers sit in a different zone from the reporting timezone, and on instant-comparing reads (filtered or hour-granular native reads, and the vendor adapters' calendar-day formatting), which used to drop the final day; day-rollup reads where the two zones coincide were already right. The picked day is recovered from a stored instant exactly for every browser offset in `(-12, +12]`; a browser at +12:45 or beyond recovers the previous day. Day strings (`YYYY-MM-DD`) are accepted on the document endpoint; offset-less datetimes and zero-width instant windows are rejected.
|
|
108
|
+
|
|
109
|
+
**Behavioral: cache keys for a closed window carry its exact bounds.** A window ending on the final instant of its day is no longer day-snapped in the cache key, so an entry cached under the old, narrower window is never served after this upgrade. That covers every custom range and every comparison window, presets included (a previous period ends 1ms before the current window's first day), so each of those re-keys once and reads cold the first time after upgrading. Live preset windows, which end at `now`, keep their day-snapped key and their hit rate. The warm task re-keys its custom-range targets on the stored days and resolves them per scope, so it warms the keys a non-UTC install's widgets actually request.
|
|
110
|
+
|
|
111
|
+
- **Additive: more widgets.** Five new breakdown widgets (referrers, browsers, operating systems, campaigns, events) register from the same table as the existing ones, each gated on its own dimension. A goals widget (`analytics-goals`) lists conversions, revenue and conversion rate per goal for the widget's timeframe, under each goal's own name, with a previous-period delta on conversions when comparison is on; it needs a source that serves both `conversions` and the `goal` dimension, and costs one engine read, plus one for the rate's denominator where the source serves `visitors`, plus one for the deltas with comparison on. Every built-in widget gains an "Open in Analytics" link that opens the analytics view on the widget's source, range, metric or tab; the source is the adapter that actually served the widget, not the id it asked for, and the link serializes against the install's own `view.defaultRange` / `view.defaultMetric`, so anything already on a default is left out. A custom range becomes two day strings in the reporting timezone, clamped to the last 366 days of the window where it is wider than the view can hold; `allTime`, `thisMonth` and `thisYear` are windows the view's range picker does not offer, so those links carry no range and open the view on its default. The link disappears with `view: false`.
|
|
112
|
+
|
|
113
|
+
`TrendChart` accepts `comparison`, `comparisonLabel`, `comparisonRange` and `label` (and `TrendPoint` is exported from `/client`), drawing the previous period as a muted line on a y-scale covering both series, with a legend that carries the previous window's range and a tooltip row per series. The trend widget gains a "Compare to previous period" checkbox (off by default, absent when `widgets.comparison` is false) that reads the previous window's series through `readForWidgetSeries({ compare: true })`, which now returns `comparisonPoints` aligned to `points` by index. `readForWidget` accepts `comparison: false` for callers that only want totals; `readForWidgetBreakdown` accepts `extraMetrics` and returns per-row `metrics` for them; both surface `stale`.
|
|
114
|
+
|
|
115
|
+
**Fix:** the view's trend re-dates the comparison series onto the primary axis by index before labelling it. The query endpoint buckets each window on its own week and month boundaries, so at those granularities the comparison could come back a bucket longer or shorter and the chart padded or truncated it silently.
|
|
116
|
+
|
|
117
|
+
**Behavioral:** the analytics view's trend section draws one chart with the overlay instead of stacking a second chart for the previous period. With the trend widget's comparison ticked, the previous-window read it already made is asked for by day rather than as a total, so an adapter that answers series and totals in separate calls makes one more call for it.
|
|
118
|
+
|
|
119
|
+
**Fix:** a duplicate row on the native engine's seen ledger is treated as "already seen" rather than thrown. A pageview and a goal event arriving together for the same visitor race on the same ledger key, and the loser's duplicate-key error (Mongo 11000, Postgres 23505) used to escape the ingest handler as a 500.
|
|
120
|
+
|
|
3
121
|
## 1.0.0-beta.7
|
|
4
122
|
|
|
5
123
|
### Minor Changes
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 10x Media GmbH
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 10x Media GmbH
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
# @10x-media/analytics
|
|
4
4
|
|
|
5
|
-
Adapter-based analytics for Payload v3. One adapter contract covers a self-hosted native engine and the major providers (GA4, Plausible, Umami, PostHog), surfaced through dashboard widgets and per-document stat fields, with cached reads, an opt-in sync tier, and capability gating so unsupported surfaces never appear.
|
|
5
|
+
Adapter-based analytics for Payload v3. One adapter contract covers a self-hosted native engine and the major providers (GA4, Plausible, Umami, PostHog), surfaced through an admin analytics view, dashboard widgets and per-document stat fields, with cached reads, an opt-in sync tier, and capability gating so unsupported surfaces never appear.
|
|
6
6
|
|
|
7
7
|
[](https://www.npmjs.com/package/@10x-media/analytics)
|
|
8
8
|
|
|
@@ -11,10 +11,13 @@ Part of the [@10x-media Payload plugins](https://github.com/10x-media/payload-pl
|
|
|
11
11
|
## Features
|
|
12
12
|
|
|
13
13
|
- **One adapter contract** with a capabilities model; adapters ship as code-split subpaths (`@10x-media/analytics/adapters/*`) plus a `memoryAdapter` for tests.
|
|
14
|
-
- **Native engine**: self-hosted, cookieless analytics in your own database, with atomic rollups, exact daily uniques, geo resolution (platform headers or MaxMind), retention pruning, and opt-in write batching.
|
|
15
|
-
- **Capture**: a dependency-free browser tracker (`@10x-media/analytics/tracker`) with SPA pageviews, consent gating, auto-capture, and goals, booted from React (`@10x-media/analytics/react`) or a server component; capture-capable adapters are served through a first-party proxy so a vendor's SDK loads from your own origin.
|
|
16
|
-
- **
|
|
14
|
+
- **Native engine**: self-hosted, cookieless analytics in your own database, with atomic rollups, exact daily uniques, geo resolution (platform headers or MaxMind), retention pruning, and opt-in write batching. It classifies the traffic channel (direct, search, social, email, paid, referral), referrer host, browser, OS, language and the five UTM keys at ingest, so it serves and filters every breakdown dimension the widgets offer except `goal`, which it groups but cannot filter. The view's `medium` and `campaign` groupings are the two it does not serve.
|
|
15
|
+
- **Capture**: a dependency-free browser tracker (`@10x-media/analytics/tracker`) with SPA pageviews, consent gating, auto-capture, and goals, booted from React (`@10x-media/analytics/react`) or a server component; capture-capable adapters are served through a first-party proxy so a vendor's SDK loads from your own origin, GA4 excepted, whose tag Google serves itself.
|
|
16
|
+
- **Goals**: conversions and revenue, completed from a `data-analytics-goal` attribute, a `goalField()` picker in your own blocks, a `@10x-media/form-builder` action, or `trackServerEvent` from server code (webhooks, jobs), and declared in config or in an opt-in collection editors manage per scope.
|
|
17
|
+
- **Analytics view** at `/admin/analytics`: overview cards, a trend, capability-gated breakdown tabs with click-to-filter, goals and realtime, with range, source, metric, tab and filters in the URL so a report is a shareable link.
|
|
18
|
+
- **Dashboard widgets** for Payload's Modular Dashboard: metric, trend (with an optional previous-period overlay), goals, ten breakdowns, and realtime, each capability-gated, each linking into the analytics view, plus a public API for custom widgets. Metric, trend and breakdown widgets take one optional filter, narrowed to what the chosen source can apply, stated in the caption and carried into the view.
|
|
17
19
|
- **Display fields**: `analyticsStat`, `analyticsStatRow`, `analyticsFields`, `analyticsTab`, `analyticsTabsField` place per-document stats on your collections; typed per-collection bindings resolve each document's URL path.
|
|
20
|
+
- **Query endpoint**: an authenticated `GET /api/analytics/query` over any configured source, capability-validated and scope-gated, with coded errors and a `fetchQuery` helper for admin code.
|
|
18
21
|
- **Caching** through `payload.kv` with request coalescing, plus an opt-in scheduled warm job.
|
|
19
22
|
- **Sync tier**: persist provider daily metrics into a queryable Payload collection.
|
|
20
23
|
- **Typed translations** with per-key overrides via `@10x-media/analytics/i18n`.
|
|
@@ -57,6 +60,8 @@ Full documentation at [docs.10xmedia.de](https://docs.10xmedia.de/analytics):
|
|
|
57
60
|
- [Overview](https://docs.10xmedia.de/analytics)
|
|
58
61
|
- [Quick start](https://docs.10xmedia.de/analytics/quick-start)
|
|
59
62
|
- [Adapters](https://docs.10xmedia.de/analytics/adapters)
|
|
63
|
+
- [Data sources and the query endpoint](https://docs.10xmedia.de/analytics/data-sources)
|
|
64
|
+
- [Analytics view](https://docs.10xmedia.de/analytics/analytics-view)
|
|
60
65
|
- [Native engine](https://docs.10xmedia.de/analytics/native)
|
|
61
66
|
- [Capture](https://docs.10xmedia.de/analytics/capture)
|
|
62
67
|
- [Goals](https://docs.10xmedia.de/analytics/goals)
|
|
@@ -67,6 +72,7 @@ Full documentation at [docs.10xmedia.de](https://docs.10xmedia.de/analytics):
|
|
|
67
72
|
- [Caching and warming](https://docs.10xmedia.de/analytics/cache)
|
|
68
73
|
- [Reporting timezone](https://docs.10xmedia.de/analytics/timezone)
|
|
69
74
|
- [Sync tier](https://docs.10xmedia.de/analytics/sync)
|
|
75
|
+
- [Multi-tenancy](https://docs.10xmedia.de/analytics/multi-tenancy)
|
|
70
76
|
- [i18n](https://docs.10xmedia.de/analytics/i18n)
|
|
71
77
|
|
|
72
78
|
## License
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
//#region src/adapters/ga4/eventName.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* A name GA4 accepts for an event. GA4 takes names that start with a letter and carry only
|
|
4
|
+
* letters, digits and underscores, up to 40 characters
|
|
5
|
+
* (https://support.google.com/analytics/answer/13316687,
|
|
6
|
+
* https://support.google.com/analytics/answer/9267744), so a kebab-case goal slug such as
|
|
7
|
+
* `checkout-complete` never lands as authored: hyphens become underscores, anything else
|
|
8
|
+
* outside the alphabet is dropped, and a name that would not start with a letter is prefixed.
|
|
9
|
+
*
|
|
10
|
+
* Imports nothing, because the browser tracker bundles it alongside the sink.
|
|
11
|
+
*/
|
|
12
|
+
declare const ga4EventName: (name: string) => string;
|
|
13
|
+
//#endregion
|
|
14
|
+
export { ga4EventName };
|
|
15
|
+
//# sourceMappingURL=eventName.d.ts.map
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
//#region src/adapters/ga4/eventName.ts
|
|
2
|
+
/**
|
|
3
|
+
* A name GA4 accepts for an event. GA4 takes names that start with a letter and carry only
|
|
4
|
+
* letters, digits and underscores, up to 40 characters
|
|
5
|
+
* (https://support.google.com/analytics/answer/13316687,
|
|
6
|
+
* https://support.google.com/analytics/answer/9267744), so a kebab-case goal slug such as
|
|
7
|
+
* `checkout-complete` never lands as authored: hyphens become underscores, anything else
|
|
8
|
+
* outside the alphabet is dropped, and a name that would not start with a letter is prefixed.
|
|
9
|
+
*
|
|
10
|
+
* Imports nothing, because the browser tracker bundles it alongside the sink.
|
|
11
|
+
*/
|
|
12
|
+
const ga4EventName = (name) => {
|
|
13
|
+
const cleaned = name.replace(/-/g, "_").replace(/[^A-Za-z0-9_]/g, "");
|
|
14
|
+
return (/^[A-Za-z]/.test(cleaned) ? cleaned : `e_${cleaned}`).slice(0, 40);
|
|
15
|
+
};
|
|
16
|
+
//#endregion
|
|
17
|
+
export { ga4EventName };
|
|
18
|
+
|
|
19
|
+
//# sourceMappingURL=eventName.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"eventName.js","names":[],"sources":["../../../src/adapters/ga4/eventName.ts"],"sourcesContent":["/**\n * A name GA4 accepts for an event. GA4 takes names that start with a letter and carry only\n * letters, digits and underscores, up to 40 characters\n * (https://support.google.com/analytics/answer/13316687,\n * https://support.google.com/analytics/answer/9267744), so a kebab-case goal slug such as\n * `checkout-complete` never lands as authored: hyphens become underscores, anything else\n * outside the alphabet is dropped, and a name that would not start with a letter is prefixed.\n *\n * Imports nothing, because the browser tracker bundles it alongside the sink.\n */\nexport const ga4EventName = (name: string): string => {\n\tconst cleaned = name.replace(/-/g, '_').replace(/[^A-Za-z0-9_]/g, '')\n\treturn (/^[A-Za-z]/.test(cleaned) ? cleaned : `e_${cleaned}`).slice(0, 40)\n}\n"],"mappings":";;;;;;;;;;;AAUA,MAAa,gBAAgB,SAAyB;CACrD,MAAM,UAAU,KAAK,QAAQ,MAAM,GAAG,EAAE,QAAQ,kBAAkB,EAAE;CACpE,QAAQ,YAAY,KAAK,OAAO,IAAI,UAAU,KAAK,WAAW,MAAM,GAAG,EAAE;AAC1E"}
|
|
@@ -13,6 +13,11 @@ interface Ga4Config {
|
|
|
13
13
|
projectId?: string;
|
|
14
14
|
/** Maximum days of historical data. Defaults to 425 (GA4's rolling-window limit). Pass null to disable clamping. */
|
|
15
15
|
maxLookbackDays?: number | null;
|
|
16
|
+
/**
|
|
17
|
+
* Public measurement id (`G-XXXXXXX`). Setting it turns on capture: the tag is loaded
|
|
18
|
+
* from googletagmanager.com and booted with gtag.
|
|
19
|
+
*/
|
|
20
|
+
measurementId?: string;
|
|
16
21
|
}
|
|
17
22
|
declare function ga4(config: Ga4Config): AnalyticsAdapter;
|
|
18
23
|
//#endregion
|