@10x-media/analytics 0.1.0-beta.5 → 1.0.0-beta.10
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 +270 -0
- package/LICENSE +21 -21
- package/README.md +15 -4
- package/dist/adapters/ga4/disableKey.d.ts +9 -0
- package/dist/adapters/ga4/disableKey.js +21 -0
- package/dist/adapters/ga4/disableKey.js.map +1 -0
- 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 +186 -58
- 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/http/fetchJson.js +1 -1
- package/dist/adapters/plausible/plausible.d.ts +25 -0
- package/dist/adapters/plausible/plausible.js +159 -38
- package/dist/adapters/plausible/plausible.js.map +1 -1
- package/dist/adapters/posthog/posthog.d.ts +10 -1
- package/dist/adapters/posthog/posthog.js +130 -21
- package/dist/adapters/posthog/posthog.js.map +1 -1
- package/dist/adapters/series.js +11 -1
- package/dist/adapters/series.js.map +1 -1
- package/dist/adapters/umami/umami.d.ts +13 -1
- package/dist/adapters/umami/umami.js +278 -26
- package/dist/adapters/umami/umami.js.map +1 -1
- package/dist/binding/resolvePath.js +18 -2
- package/dist/binding/resolvePath.js.map +1 -1
- package/dist/capture/getTrackerConfig.d.ts +20 -0
- package/dist/capture/getTrackerConfig.js +31 -0
- package/dist/capture/getTrackerConfig.js.map +1 -0
- package/dist/capture/mountPath.js +14 -0
- package/dist/capture/mountPath.js.map +1 -0
- package/dist/capture/proxyEndpoint.js +127 -0
- package/dist/capture/proxyEndpoint.js.map +1 -0
- package/dist/capture/proxyRoutes.js +108 -0
- package/dist/capture/proxyRoutes.js.map +1 -0
- package/dist/capture/requestBody.js +68 -0
- package/dist/capture/requestBody.js.map +1 -0
- package/dist/capture/slots.d.ts +8 -0
- package/dist/capture/slots.js +54 -0
- package/dist/capture/slots.js.map +1 -0
- package/dist/capture/trackerConfig.d.ts +33 -0
- package/dist/capture/trackerConfig.js +95 -0
- package/dist/capture/trackerConfig.js.map +1 -0
- package/dist/capture/trackerEndpoint.js +35 -0
- package/dist/capture/trackerEndpoint.js.map +1 -0
- package/dist/charts/BarList.d.ts +16 -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 +4 -0
- package/dist/charts/bars.js +3 -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 +26 -3
- package/dist/core/cacheKey.js.map +1 -1
- package/dist/core/capabilities.d.ts +5 -1
- package/dist/core/capabilities.js +11 -2
- package/dist/core/capabilities.js.map +1 -1
- package/dist/core/capture.d.ts +49 -0
- package/dist/core/contract.d.ts +74 -5
- package/dist/core/contract.js +30 -1
- package/dist/core/contract.js.map +1 -1
- package/dist/core/granularity.js +1 -1
- package/dist/core/options.d.ts +164 -6
- package/dist/core/options.js +126 -3
- package/dist/core/options.js.map +1 -1
- package/dist/core/registry.d.ts +1 -0
- package/dist/core/scopeList.js +32 -0
- package/dist/core/scopeList.js.map +1 -0
- package/dist/core/scopedRead.js +101 -30
- package/dist/core/scopedRead.js.map +1 -1
- package/dist/core/serverEvent.d.ts +60 -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/adapters/native.d.ts +3 -1
- package/dist/exports/adapters/native.js +2 -1
- package/dist/exports/client.d.ts +13 -3
- package/dist/exports/client.js +10 -1
- package/dist/exports/geo.d.ts +2 -2
- package/dist/exports/next.d.ts +2 -1
- package/dist/exports/next.js +2 -1
- package/dist/exports/react.d.ts +4 -0
- package/dist/exports/react.js +5 -0
- package/dist/exports/rsc.d.ts +11 -3
- package/dist/exports/rsc.js +7 -2
- package/dist/exports/tracker.d.ts +21 -0
- package/dist/exports/tracker.js +15 -0
- package/dist/exports/types.d.ts +16 -3
- package/dist/exports/types.js +4 -2
- package/dist/fields/AnalyticsPanelClient.js +2 -2
- 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/fetchSources.js +7 -3
- package/dist/fields/config/fetchSources.js.map +1 -1
- package/dist/fields/config/narrow.js +2 -0
- package/dist/fields/config/narrow.js.map +1 -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 +22 -10
- 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 +254 -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 +33 -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 +58 -0
- package/dist/goals/goalsEndpoint.js.map +1 -0
- package/dist/goals/match.js +64 -0
- package/dist/goals/match.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 +76 -0
- package/dist/goals/trackGoalAction.js +158 -0
- package/dist/goals/trackGoalAction.js.map +1 -0
- package/dist/goals/types.d.ts +33 -0
- package/dist/goals/types.js +7 -0
- package/dist/goals/types.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 +14 -3
- package/dist/index.js +174 -19
- package/dist/index.js.map +1 -1
- package/dist/native/collections/events.js +65 -1
- package/dist/native/collections/events.js.map +1 -1
- package/dist/native/collections/rollups.js +39 -3
- package/dist/native/collections/rollups.js.map +1 -1
- package/dist/native/eventScan.js +25 -0
- package/dist/native/eventScan.js.map +1 -0
- package/dist/native/geo/composeGeoResolvers.js +2 -2
- package/dist/native/geo/composeGeoResolvers.js.map +1 -1
- package/dist/native/geo/geoResolver.d.ts +9 -2
- package/dist/native/geo/geoResolver.js.map +1 -1
- package/dist/native/geo/maxmindResolver.js +3 -5
- package/dist/native/geo/maxmindResolver.js.map +1 -1
- package/dist/native/ingest/bots.d.ts +11 -0
- package/dist/native/ingest/bots.js +71 -0
- package/dist/native/ingest/bots.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/clientIp.js +20 -0
- package/dist/native/ingest/clientIp.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 +107 -21
- package/dist/native/ingest/endpoint.js.map +1 -1
- package/dist/native/ingest/flushBatch.js +29 -38
- 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 +30 -0
- package/dist/native/ingest/normalizeEvent.js +115 -16
- 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/requestHost.js +57 -0
- package/dist/native/ingest/requestHost.js.map +1 -0
- package/dist/native/ingest/resolveHostname.d.ts +29 -0
- package/dist/native/ingest/resolveHostname.js +52 -0
- package/dist/native/ingest/resolveHostname.js.map +1 -0
- package/dist/native/ingest/salt.js +27 -2
- package/dist/native/ingest/salt.js.map +1 -1
- package/dist/native/ingest/serverTrack.d.ts +20 -0
- package/dist/native/ingest/serverTrack.js +109 -0
- package/dist/native/ingest/serverTrack.js.map +1 -0
- package/dist/native/ingest/source.d.ts +11 -0
- package/dist/native/ingest/source.js +264 -16
- 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 +26 -0
- package/dist/native/ingest/validate.js.map +1 -0
- package/dist/native/nativeAdapter.d.ts +37 -1
- package/dist/native/nativeAdapter.js +175 -22
- package/dist/native/nativeAdapter.js.map +1 -1
- package/dist/native/query/eventAgg.js +175 -0
- package/dist/native/query/eventAgg.js.map +1 -0
- package/dist/native/retention/pruneTask.js +53 -13
- package/dist/native/retention/pruneTask.js.map +1 -1
- package/dist/native/rollupAcc.js +12 -1
- package/dist/native/rollupAcc.js.map +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 +86 -11
- 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 +42 -0
- package/dist/next/captureRewrites.js +57 -0
- package/dist/next/captureRewrites.js.map +1 -0
- package/dist/next/posthogProxyRewrites.d.ts +5 -0
- package/dist/next/posthogProxyRewrites.js +16 -21
- package/dist/next/posthogProxyRewrites.js.map +1 -1
- package/dist/plugin/documentEndpoint.js +71 -24
- package/dist/plugin/documentEndpoint.js.map +1 -1
- package/dist/plugin/errors.d.ts +31 -0
- package/dist/plugin/errors.js +79 -0
- package/dist/plugin/errors.js.map +1 -0
- 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 +17 -1
- package/dist/plugin/paths.js.map +1 -1
- package/dist/plugin/queryEndpoint.js +124 -0
- package/dist/plugin/queryEndpoint.js.map +1 -0
- package/dist/plugin/readContextForRequest.js +73 -0
- package/dist/plugin/readContextForRequest.js.map +1 -0
- package/dist/plugin/realtimeEndpoint.js +37 -16
- package/dist/plugin/realtimeEndpoint.js.map +1 -1
- package/dist/plugin/refreshEndpoint.js +113 -0
- package/dist/plugin/refreshEndpoint.js.map +1 -0
- package/dist/plugin/runtime.d.ts +1 -0
- package/dist/plugin/runtime.js +33 -1
- package/dist/plugin/runtime.js.map +1 -1
- package/dist/plugin/scopeChange.js +22 -0
- package/dist/plugin/scopeChange.js.map +1 -0
- package/dist/plugin/scopeFieldBoot.js +22 -0
- package/dist/plugin/scopeFieldBoot.js.map +1 -0
- package/dist/plugin/sourcesEndpoint.js +16 -41
- 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 +89 -29
- package/dist/providers/collection.js.map +1 -1
- package/dist/providers/factory.js +11 -3
- 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 +14 -0
- package/dist/query/fetchQuery.d.ts +79 -0
- package/dist/query/fetchQuery.js +117 -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/react/AnalyticsProvider.d.ts +50 -0
- package/dist/react/AnalyticsProvider.js +67 -0
- package/dist/react/AnalyticsProvider.js.map +1 -0
- package/dist/react/TrackerBoot.d.ts +22 -0
- package/dist/react/TrackerBoot.js +30 -0
- package/dist/react/TrackerBoot.js.map +1 -0
- package/dist/react/useAnalytics.d.ts +20 -0
- package/dist/react/useAnalytics.js +52 -0
- package/dist/react/useAnalytics.js.map +1 -0
- package/dist/rsc/AnalyticsScripts.d.ts +30 -0
- package/dist/rsc/AnalyticsScripts.js +41 -0
- package/dist/rsc/AnalyticsScripts.js.map +1 -0
- package/dist/surfacing/cacheStore.d.ts +1 -0
- package/dist/surfacing/cacheStore.js +18 -2
- package/dist/surfacing/cacheStore.js.map +1 -1
- package/dist/surfacing/engine.d.ts +1 -0
- package/dist/surfacing/engine.js +47 -6
- package/dist/surfacing/engine.js.map +1 -1
- package/dist/surfacing/epoch.d.ts +1 -0
- package/dist/surfacing/epoch.js +72 -0
- package/dist/surfacing/epoch.js.map +1 -0
- package/dist/surfacing/queue.js +22 -6
- package/dist/surfacing/queue.js.map +1 -1
- package/dist/surfacing/rateLimiter.js +130 -0
- package/dist/surfacing/rateLimiter.js.map +1 -0
- package/dist/surfacing/retryPolicy.js +15 -0
- package/dist/surfacing/retryPolicy.js.map +1 -0
- package/dist/sync/collection.js +23 -7
- package/dist/sync/collection.js.map +1 -1
- package/dist/sync/syncTask.js +68 -33
- package/dist/sync/syncTask.js.map +1 -1
- package/dist/testing/memoryAdapter.d.ts +2 -0
- package/dist/testing/memoryAdapter.js +17 -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/autoCapture.d.ts +48 -0
- package/dist/tracker/autoCapture.js +129 -0
- package/dist/tracker/autoCapture.js.map +1 -0
- package/dist/tracker/consent.d.ts +24 -0
- package/dist/tracker/consent.js +48 -0
- package/dist/tracker/consent.js.map +1 -0
- package/dist/tracker/createTracker.d.ts +18 -0
- package/dist/tracker/createTracker.js +215 -0
- package/dist/tracker/createTracker.js.map +1 -0
- package/dist/tracker/exclusion.d.ts +28 -0
- package/dist/tracker/exclusion.js +50 -0
- package/dist/tracker/exclusion.js.map +1 -0
- package/dist/tracker/initTracker.d.ts +22 -0
- package/dist/tracker/initTracker.js +33 -0
- package/dist/tracker/initTracker.js.map +1 -0
- package/dist/tracker/loadScript.d.ts +14 -0
- package/dist/tracker/loadScript.js +41 -0
- package/dist/tracker/loadScript.js.map +1 -0
- package/dist/tracker/pageTracking.d.ts +17 -0
- package/dist/tracker/pageTracking.js +38 -0
- package/dist/tracker/pageTracking.js.map +1 -0
- package/dist/tracker/registry.d.ts +27 -0
- package/dist/tracker/registry.js +73 -0
- package/dist/tracker/registry.js.map +1 -0
- package/dist/tracker/sinks/ga4.d.ts +29 -0
- package/dist/tracker/sinks/ga4.js +30 -0
- package/dist/tracker/sinks/ga4.js.map +1 -0
- package/dist/tracker/sinks/native.d.ts +22 -0
- package/dist/tracker/sinks/native.js +56 -0
- package/dist/tracker/sinks/native.js.map +1 -0
- package/dist/tracker/sinks/plausible.d.ts +20 -0
- package/dist/tracker/sinks/plausible.js +32 -0
- package/dist/tracker/sinks/plausible.js.map +1 -0
- package/dist/tracker/sinks/posthog.d.ts +18 -0
- package/dist/tracker/sinks/posthog.js +30 -0
- package/dist/tracker/sinks/posthog.js.map +1 -0
- package/dist/tracker/sinks/umami.d.ts +18 -0
- package/dist/tracker/sinks/umami.js +23 -0
- package/dist/tracker/sinks/umami.js.map +1 -0
- package/dist/tracker/sinks/vendor.d.ts +14 -0
- package/dist/tracker/sinks/vendor.js +81 -0
- package/dist/tracker/sinks/vendor.js.map +1 -0
- package/dist/tracker/transport.js +28 -0
- package/dist/tracker/transport.js.map +1 -0
- package/dist/tracker/types.d.ts +91 -0
- package/dist/translations/ar.js +221 -0
- package/dist/translations/ar.js.map +1 -0
- package/dist/translations/de.js +145 -1
- package/dist/translations/de.js.map +1 -1
- package/dist/translations/en.js +145 -1
- package/dist/translations/en.js.map +1 -1
- package/dist/translations/es.js +221 -0
- package/dist/translations/es.js.map +1 -0
- package/dist/translations/fr.js +221 -0
- package/dist/translations/fr.js.map +1 -0
- package/dist/translations/id.js +221 -0
- package/dist/translations/id.js.map +1 -0
- package/dist/translations/index.d.ts +10 -1
- package/dist/translations/index.js +19 -1
- package/dist/translations/index.js.map +1 -1
- package/dist/translations/keys.d.ts +144 -0
- package/dist/translations/keys.js +145 -1
- package/dist/translations/keys.js.map +1 -1
- package/dist/translations/ko.js +221 -0
- package/dist/translations/ko.js.map +1 -0
- package/dist/translations/metricKeys.js +8 -2
- package/dist/translations/metricKeys.js.map +1 -1
- package/dist/translations/pt.js +221 -0
- package/dist/translations/pt.js.map +1 -0
- package/dist/translations/ru.js +221 -0
- package/dist/translations/ru.js.map +1 -0
- package/dist/translations/server.js.map +1 -1
- package/dist/translations/uk.js +221 -0
- package/dist/translations/uk.js.map +1 -0
- package/dist/translations/zh.js +221 -0
- package/dist/translations/zh.js.map +1 -0
- 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 +244 -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 +76 -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 +198 -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 +207 -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 +76 -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 +18 -4
- 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 +38 -0
- 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 +78 -23
- 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 +26 -3
- package/dist/widgets/readForWidget.js +48 -44
- package/dist/widgets/readForWidget.js.map +1 -1
- package/dist/widgets/readForWidgetBreakdown.d.ts +34 -2
- package/dist/widgets/readForWidgetBreakdown.js +53 -49
- 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 +23 -21
- package/dist/widgets/readForWidgetRealtime.js.map +1 -1
- package/dist/widgets/readForWidgetSeries.d.ts +26 -2
- package/dist/widgets/readForWidgetSeries.js +78 -53
- 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/realtimePoll.js +13 -1
- package/dist/widgets/realtimePoll.js.map +1 -1
- package/dist/widgets/registerWidgets.js +62 -10
- package/dist/widgets/registerWidgets.js.map +1 -1
- package/dist/widgets/types.d.ts +15 -0
- package/dist/widgets/types.js +16 -2
- 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 +28 -8
- package/dist/native/rollups/applyDistinctDeltas.js +0 -9
- package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
- package/dist/native/rollups/bumpRollup.js +0 -68
- 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,275 @@
|
|
|
1
1
|
# @10x-media/analytics
|
|
2
2
|
|
|
3
|
+
## 1.0.0-beta.10
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- **Additive: a configuration change invalidates that scope's cached reads.** Correcting a provider document, or adding or editing a goal, used to leave every cached read in place until its TTL ran out, up to an hour on most sources, because only the in-process lookup maps were cleared. Every cache key now carries a per-scope cache epoch, an opaque token kept in `payload.kv`. Saving or deleting a provider document or a goal document bumps the epoch of the scope it belongs to, and of the scope it left when a document moves between scopes, so the next read of that scope misses and asks the source again. Old entries are not deleted; they expire by TTL under keys no read asks for. An instance reads a scope's token at most once every ten seconds, so a change made on one instance reaches the others within ten seconds. A token that cannot be read falls back to `0` with a warning logged once per process, not once per incident, and never fails an analytics read; for that ten second window the instance may serve entries written before the bump it could not see. A bump that fails, or has not settled after two seconds, is logged and dropped rather than failing the save that triggered it; a save that moved a document between scopes bumps both of them under that one two second deadline.
|
|
8
|
+
|
|
9
|
+
**Additive: `POST /api/analytics/refresh` and a Refresh button.** The endpoint bumps one scope's epoch and answers `{ "epoch": "<token>" }`. It takes the same authentication and `access.read` as the read endpoints, and decides scope through the same code the query endpoint reads with, so it refuses every request that endpoint refuses: only a platform reader may name a `scope` in the JSON body, and on a scoped install a request that resolves no scope at all is refused too, both with `400 untrusted_scope`. `scope: "*"` bumps the install-wide epoch, which is what a cross-scope read's entries key on; a tenant's reads key on that tenant's own epoch and are not refreshed by it. A body over 4 KiB answers `413 payload_too_large`. **Breaking for exhaustive switches:** `QueryErrorCode`, exported from `@10x-media/analytics/types`, gains `payload_too_large`, so a `switch` over it with a `never` default needs a new arm. One instance bumps a given scope at most once every five seconds for this endpoint, answering the token already in force inside that window, so a looped call cannot turn a scope's cached reads into provider calls over and over; the document hooks are never debounced. The endpoint is state-changing and cookie-authenticated, so configure Payload's `csrf` allowlist on any install that exposes it. The analytics view's toolbar gains a **Refresh** button that calls it and reissues the cards, trend, breakdown and goals sections; the realtime strip and already-rendered dashboard widgets pick the bump up on their own next read. `refreshCache(apiRoute, { scope, signal })` is exported from `@10x-media/analytics/client` beside `fetchQuery`, with `RefreshRequest` and `RefreshResponse` in `@10x-media/analytics/types`.
|
|
10
|
+
|
|
11
|
+
**Behavioral: the cache key format changed.** Every key now carries the epoch as its second segment, so entries written by the previous release are never read again and every read misses once after the upgrade. Nothing needs to be cleared by hand, and the orphaned entries expire on their own.
|
|
12
|
+
|
|
13
|
+
- **Breaking (contract): `channel` is a new dimension.** `DIMENSION_KEYS` gains `channel`, right after `source`. Code holding an exhaustive `Record<DimensionKey, ...>` needs the new key. `source` and `channel` now mean the same two things on every adapter that serves them: `source` is the visit's named origin (the `utm_source` tag when there is one, otherwise the referrer), and `channel` is the classification of that origin into an acquisition channel, in each source's own vocabulary. `TRAFFIC_CHANNELS` and `TrafficChannel`, exported from `@10x-media/analytics/types`, go from six tokens to twelve, so an exhaustive `Record<TrafficChannel, ...>` needs the new members.
|
|
14
|
+
|
|
15
|
+
**Breaking (native installs): `source` stores the named origin again, and `channel` stores the classification.** The previous release stored one of six channel tokens in `source`. Native now stores `utm_source` lowercased, else the referring host, else the token `direct` in `source`, and one of twelve tokens in the new `channel` column: `direct`, `organic-search`, `paid-search`, `organic-social`, `paid-social`, `organic-video`, `paid-video`, `email`, `affiliate`, `display`, `referral`, `paid-other`. A paid visit is one whose `utm_medium` is `cpc`, `ppc` or starts with `paid`, or whose query carries a Google Ads, Microsoft Ads or TikTok Ads click id (`gclid`, `gbraid`, `wbraid`, `msclkid`, `ttclid`); the platform comes from the referrer host, from `utm_source` by name when there is no referrer host at all, and on the paid path from `utm_source` too when the host names no platform, so an ad click arriving through a network's redirect host keeps its platform. `utm_medium` values `email`, `newsletter`, `affiliate`, `affiliates`, `display`, `banner`, `cpm`, `retargeting`, `remarketing`, `social`, `social-media`, `sm`, `organic` and `search` classify directly. Events also carry `channelVersion`, the version of the rules that classified them, so a later reclassification can find rows written under older rules. The events collection gains the `channel` and `channel_version` columns: Postgres migrate-mode installs add them with the updated snippet in the native docs; Mongo and push-mode installs need nothing. Nothing is backfilled, so rows written by the previous release keep the token they stored in `source`. The `channelSearch`, `channelSocial` and `channelPaid` translation keys are gone, replaced by `channelOrganicSearch` / `channelPaidSearch`, `channelOrganicSocial` / `channelPaidSocial` and `channelPaidOther`; an override of a removed key fails to compile. Because `source` now holds lowercased `utm_source` values (capped at 128 characters), its rollup rows grow with the number of distinct values an install's traffic carries, one row per value per hostname family, where the old six-token set bounded them.
|
|
16
|
+
|
|
17
|
+
**Fixed: `fbclid` no longer reads as paid.** Facebook appends `fbclid` to every outbound link, organic posts included, so the previous release overcounted paid traffic. It is now a social signal only: with no referrer host, and when no `utm_source` names a platform either, it names the social platform inside whichever of the paid or organic branches the other signals chose, so a visit carrying nothing but `fbclid` is organic social.
|
|
18
|
+
|
|
19
|
+
**Fixed: a row with no value reads "Not set" and offers no filter.** A source can answer a row with no value for the dimension it was grouped by, PostHog's empty `$channel_type` for a pageview captured outside a session among them. The bar carried no label, and clicking it built an `eq ''` filter the query endpoint rejects, since a filter value is one character at minimum. Such a row now renders the new translated `valueNotSet` key on every dimension and every source, and is inert in the view's breakdowns while the rows beside it keep their click.
|
|
20
|
+
|
|
21
|
+
**Additive: providers serve `channel` too.** Plausible maps it to `visit:channel`, GA4 to `sessionDefaultChannelGroup`, PostHog to the session's `$channel_type`, and Umami to `/metrics?type=channel`. Each returns its own channel names, rendered as they arrive; native's tokens render through twelve typed `channel*` translations. `channel` is filterable on native, Plausible, GA4 and PostHog, and groupable only on Umami, whose API takes no channel filter.
|
|
22
|
+
|
|
23
|
+
**Behavioral: the Sources tab opens on channels.** The tab's dimensions now lead with `channel`, then `source`, then `referrer` and the campaign keys, so it opens on the channel overview wherever the source serves one; the named origin and the referring host are one pick away in **Group by**. PostHog gains a Sources tab, which it did not have before. An existing link naming `tab=sources` opens on channels unless it also carries `dim`.
|
|
24
|
+
|
|
25
|
+
**Additive: a channels widget.** `analytics-breakdown-channels` ranks channels on the dashboard, opening on visitors, and links into the Sources tab; `analyticsDefaultWidgets()` places it after the sources card. The sources widget keeps ranking `source`.
|
|
26
|
+
|
|
27
|
+
- **Breaking (wire): every endpoint answers errors in one envelope.** The query and refresh endpoints answered `{ "error": { "code", "message", "param"? } }`. The document, sources, goals and native ingest endpoints answered a bare string, `{ "error": "forbidden" }`, and the realtime endpoint answered one shape or the other depending on which failure it hit. All of them now answer the envelope, over one typed code vocabulary. Code that read `error` as a string from any of those endpoints reads `error.code` and `error.message` instead. Status codes are unchanged except on the document endpoint, and no success body changed. The capture proxy stays bodyless and is the one endpoint that sends no envelope: it relays a vendor SDK's own traffic, and that SDK, not admin code, reads the answer.
|
|
28
|
+
|
|
29
|
+
**Breaking (types): the code union gains `not_found`.** It is what the document endpoint answers for a document that is not there or not this caller's to read. `QueryErrorCode` is now an alias of the plugin-wide `AnalyticsErrorCode`, so an exhaustive `switch` over either name stops compiling until it handles the new member. Treat an unrecognized code as a generic failure of its status: the union is open to additions.
|
|
30
|
+
|
|
31
|
+
**Behavioral: the document endpoint no longer hides a broken install as a `404`.** Its catch-all answered `404` for every failure while reading a document. A document that does not exist, one this caller may not read, an unbound collection and a missing `id` are all still a uniform `404 not_found`, so analytics never confirm a document exists; `findByID` failing for any other reason is now a logged `500 internal`.
|
|
32
|
+
|
|
33
|
+
**Behavioral: two answers changed their headers.** The goals endpoint sends `cache-control: private, no-store` on every answer, successful listings included, like every other scope-dependent endpoint whose answer is not cached at all. The document endpoint's `503` now carries `Retry-After: 30`, matching the query endpoint on the same condition. Native ingest refusals carry `no-store` as well, which is harmless on a public endpoint and keeps one builder for every error. The tracker config endpoint is deliberately untouched: it has no failure path to convert, and it keeps `private, max-age=60` with `Vary: Host, Cookie`, the one scope-dependent answer that is cached at all.
|
|
34
|
+
|
|
35
|
+
**Behavioral: the realtime counter stops polling on a refusal aimed at the reader.** A `401 unauthorized` or a `403 forbidden` ends the interval, since no later tick talks its way out of either. An outage, an unreadable body and a body from an older server all keep polling. The counter shows the paused label it always did, so there is no new state and no new string.
|
|
36
|
+
|
|
37
|
+
**Behavioral: `QueryFetchError.error` is undefined for a code this release does not know.** `fetchQuery` and `refreshCache` read the envelope through the same reader the rest of the package uses, so a body carrying a code a newer server added is reported as a generic failure of its status rather than typed as a `QueryErrorCode` it is not. `status` and `retryAfter` are unchanged, and `error` is still set for every code this release defines.
|
|
38
|
+
|
|
39
|
+
**Additive: refusals name the field at fault.** Native ingest puts the first field an event failed on in `param`, checked as `type`, `path`, `hostname`, `name`; unparseable JSON names `type`, and a body that died in transit names nothing. The document endpoint names the custom range bound at fault, `from` or `to`, where it answered `{ "error": "invalid range" }` with nothing to branch on; an inverted window blames `to`.
|
|
40
|
+
|
|
41
|
+
**Additive: `AnalyticsErrorCode`, `AnalyticsError`, `ANALYTICS_ERROR_CODES`, `analyticsError`, `readErrorCode` and `readResponseError`.** `readErrorCode(body)` answers the code of an envelope body and `undefined` for anything else, so admin code branches on a failed answer without parsing it by hand; it is exported from `@10x-media/analytics/client` and `@10x-media/analytics/types`, which both also export the `AnalyticsError` and `AnalyticsErrorCode` types. `readResponseError(res)` is the same read over a `Response` nothing has parsed yet, answering the whole error and `undefined` for a body that is not JSON, an empty and an already-consumed one included, rather than throwing; it is exported from `@10x-media/analytics/client`. `ANALYTICS_ERROR_CODES` is exported from `@10x-media/analytics/types` and the package root, and the builder `analyticsError` from the root. `QueryError` and `QueryErrorCode` stay exported under their own names as aliases.
|
|
42
|
+
|
|
43
|
+
- A native event is attributed to the request that carried it, not to the hostname its body claims.
|
|
44
|
+
|
|
45
|
+
**Breaking:** the hostname a native event is stored under is now the host the request carried (the `x-forwarded-host` entry `n` from the right where `trustedProxyHops` is `n >= 1`, else `Host`), and the body's claim is ignored. The forwarded chain is counted from the trusted end exactly as `x-forwarded-for` is, because a proxy that appends rather than replaces leaves the client's own value at the head of it; a chain shorter than `n`, or an entry that is no hostname, falls back to `Host`, whose peer is the trusted proxy. `Origin` is never read: a scripted client can pair a valid `Host` with any `Origin` and mint unlimited hostname bucket families inside one scope, which is the hole this closes. An install whose beacons already post from the site they are counting sees no change, because the request's host is the page's host; an install whose tracker posts to a different host than the page runs on sees its stored hostname change, and should use the new `hostname` resolver form.
|
|
46
|
+
|
|
47
|
+
**Breaking:** there is now one definition of a hostname, and config entries, the request host, a resolver's answer and a form goal action's host are all held to it. A value is lowercased and loses its port, its brackets and every trailing root dot, and must then be dot-separated labels of `a-z`, `0-9`, `_` and `-` (every IPv4 literal included) or an IPv6 literal of hex groups and colons, within 253 characters. `example.com.`, `example.com..` and `Example.COM:3000` are therefore one hostname rather than four bucket families, `[::1]:3000` is stored as `::1` rather than `[::1]`, and a name over 253 characters is refused instead of truncated into a name of its own. Anything else (a leading or doubled dot, an unclosed bracket, a percent-encoded or non-ASCII spelling, a non-numeric port, a scheme) drops the event.
|
|
48
|
+
|
|
49
|
+
**Breaking:** on an install with a `scopeResolver`, an event whose request resolves no scope is dropped instead of being stored install-wide, unless its resolved hostname is listed in the native adapter's `platformHostnames`. A dropped event answers exactly what an accepted one answers, `202` with `{ ok: true }`, and nothing per event is logged, so the endpoint is no oracle for which hosts or tenants exist.
|
|
50
|
+
|
|
51
|
+
**Behavioral:** the first drop of each reason writes one `warn` line, naming the `scopeResolver` or the `hostname` option to look at, and every later drop of that reason is silent for the life of the process. A public endpoint must not be a log amplifier, since an attacker would otherwise choose how much it writes, but a misconfigured resolver discarding all traffic should not be invisible either.
|
|
52
|
+
|
|
53
|
+
**Breaking:** the ingest body's `hostname` is optional, and a body carrying one is only type-checked. A missing `hostname` no longer answers `400`; a non-string one still does. `trackServerEvent` is unaffected and still requires its own, since trusted server code has no request to attribute an event to.
|
|
54
|
+
|
|
55
|
+
**Additive:** `native({ hostname })` takes `'request'` (the default), a list of hostnames (the request host is stored only when the list holds it, and this is the form to use on a single-site install with no `scopeResolver` and no edge validating `Host`), or an `EventHostnameResolver`, `({ claimed, req, scope }) => string | null`, that decides per event, where `null` drops it and a throw drops it too. It is named apart from the binding `HostnameResolver`, which names the hostname a document is read under. A resolver's answer must itself be a hostname: an id, a slug or a label drops the event rather than being stored as free text per event. List entries are validated at boot: a scheme or a port in an entry, or an empty list, fails the boot rather than silently dropping every event.
|
|
56
|
+
|
|
57
|
+
**Additive:** `native({ platformHostnames })` names the platform's own domains on a scoped install, which ingest under the null scope rather than being dropped. The list is static on purpose: those domains change with a deploy, not with a signup. Tenant domains never belong in it, because a tenant's custom domain is tracked the moment its document is saved, through the install's own `scopeResolver`.
|
|
58
|
+
|
|
59
|
+
**Additive:** `analytics({ trustedProxyHops })` sets how many proxies in front of the app are trusted, counted from the right of `x-forwarded-for`. It is plugin-level because one helper reads the client address for the native visitor hash, for geo, and for the capture proxy's upstream `X-Forwarded-For`. Unset keeps today's leftmost entry, which is correct for honest traffic and client-writable otherwise. At `n >= 1` the forwarded chain is the only source, and a chain shorter than `n` yields no address rather than falling back to the client-writable `x-real-ip`. There is no default of `1`: an install behind a CDN plus a proxy would then read the CDN's address for every visitor, collapsing geo and the visitor hash onto one value.
|
|
60
|
+
|
|
61
|
+
**Additive:** `GeoResolver` gained an optional second argument carrying `trustedProxyHops`, so a resolver that does its own IP lookup reads the same address the rest of the pipeline does. `maxmindResolver` honors it. A one-argument resolver still type-checks and still runs. `GeoResolverOptions`, the type of that argument, is exported from `@10x-media/analytics/geo` beside `GeoResolver`.
|
|
62
|
+
|
|
63
|
+
**Behavioral:** a binding's `hostname` is reduced to the bare lowercased host before it reaches an adapter query, so a tenant domain stored as `https://Example.com/` or with a port still matches the hostnames the native engine writes, which are compared exactly. A value that is no hostname at all reaches the adapter unchanged.
|
|
64
|
+
|
|
65
|
+
**Breaking:** `trackGoalAction` no longer stores the submitting request's `Host` as given. It resolves the `hostname` option first, then that request under the native adapter's own `hostname` policy (so a forged host the ingest endpoint would refuse is refused here too), then the host of `serverURL`. The scoped-install drop rule does not apply, since a submission's scope comes from the form document. With none of the three (no `serverURL`, and a request with no usable host), the completion is not recorded at all: the action writes one `warn` line for the life of the process and returns, rather than throwing inside a submission it is not essential to. The policy is read off the very adapter the event would be written through, so one adapter cannot judge a hostname another one stores. `trackServerEvent` called directly by server code is unchanged: it is trusted, supplies its own hostname, and still requires one.
|
|
66
|
+
|
|
67
|
+
**Additive:** an adapter's `ingest` seam may expose `hostname`, which applies that adapter's own hostname policy to a request. The native adapter provides it, and it is how the form goal action attributes exactly as the endpoint does.
|
|
68
|
+
|
|
69
|
+
**Behavioral:** an existing single-site install sees the same hostname it saw before in the common same-origin case, since the request's host is the page's host there. The visitor hash and the same-site referral check both key off the resolved hostname rather than the claimed one, so a forged body no longer splits one visitor across hostname buckets. The salt, timezone and goal resolvers now run only for an event that will be kept.
|
|
70
|
+
|
|
71
|
+
Rate limiting is deliberately not part of this. The plugin decides what one accepted request may write; how many requests are accepted belongs to the edge, where a per-IP limit can throttle an abuser instead of the whole install's traffic.
|
|
72
|
+
|
|
73
|
+
- Staff can take themselves out of the numbers with a link, and the docs say what a stored event holds.
|
|
74
|
+
|
|
75
|
+
**Additive:** any page opened with `?analytics_exclude=1` takes that browser out of capture, and `=0` puts it back (`true` and `false` work too). The tracker reads the parameter on boot and leaves the URL alone. While the flag is set nothing is delivered to any sink, nothing is queued for a pending consent decision, and no vendor script is injected even after consent is granted; clearing resumes from that point and replays nothing that was skipped. The flag lives in `localStorage` under `analytics:exclude`, so it is per browser and per site, and a browser with storage blocked is excluded for the page the link was opened on and no further, without throwing.
|
|
76
|
+
|
|
77
|
+
**Additive:** `exclusionParam` on `createTracker`/`initTracker` options, beside `persistConsent`. A string renames the parameter, `false` ignores it while still honouring a flag an earlier visit set. Default `analytics_exclude`.
|
|
78
|
+
|
|
79
|
+
**Additive:** `tracker.exclude(next)` and the read-only `tracker.excluded` on the `Tracker` interface, `setExcluded` and `excluded` on `useAnalytics()`, and `EXCLUSION_STORAGE_KEY`, `DEFAULT_EXCLUSION_PARAM`, `readExclusion`, `writeExclusion`, `readExclusionParam` and `subscribeExclusion` from `@10x-media/analytics/tracker`, for a host rendering its own switch. `AnalyticsApi` gains the `excluded` flag and is now `AnalyticsCommands` (the imperative half, also exported from `@10x-media/analytics/react`) plus that flag; nothing was removed from it, and the React context itself is not part of the package's export surface.
|
|
80
|
+
|
|
81
|
+
**Additive:** the vendor sinks expose their own opt-out through the optional `Sink.exclude`, with `PLAUSIBLE_IGNORE_KEY`, `UMAMI_DISABLED_KEY`, `GA4_DISABLE_PREFIX` and `Ga4SinkArgs` exported alongside them.
|
|
82
|
+
|
|
83
|
+
**Behavioral:** a visitor who arrives with the parameter is excluded from then on in that browser, and the exclusion is mirrored into each vendor's own switch for the slots the config has: `plausible_ignore`, `umami.disabled`, PostHog's `opt_out_capturing()` and GA4's `ga-disable-<measurementId>`. A snippet the server rendered for a slot that does not require consent runs before the tracker boots, so that vendor's own page view for the page the link was opened on may already have been sent; Plausible, Umami and PostHog persist their switch and are silent from the next load. GA4's is a window property that does not persist and counts only ahead of the first `gtag()` call, so the rendered GA4 snippet reads `analytics:exclude` itself and sets the switch before its own `gtag('config', ...)`: the page the link is opened on may still be measured, and from the next page load on nothing is. A gated slot, which is GA4's default, never loads while the browser is excluded. A vendor key the tracker did not set is cleared only by an explicit `=0` or `exclude(false)`, so one a staff member set by hand survives an ordinary visit; an explicit clear does clear it, which is the cost of off meaning off.
|
|
84
|
+
|
|
85
|
+
**Breaking (types only):** the exported `Tracker` type gains two required members, `excluded` and `exclude`. Code that implements `Tracker` itself, such as a test double or a wrapper, has to add them. The same holds for `AnalyticsApi`, the return type of `useAnalytics()`, which gains a required `excluded`: a hand-built value of that type, such as a mocked hook in a test, has to add it. Callers are unaffected.
|
|
86
|
+
|
|
87
|
+
**Behavioral:** the tracker's built entry grows by about 6 KB unminified. It stays dependency-free.
|
|
88
|
+
|
|
89
|
+
**Additive:** a Privacy page in the docs states, column by column, what a stored native event holds and where each value comes from, that no cookie is set and which `localStorage` keys exist, how the daily-salted visitor hash works and why two days cannot be joined once its salt is swept, that the client address is used for the hash and geo and stored nowhere, that the raw query string is read for the campaign keys and the ad click ids and then discarded, what a `path` or a prop the site authors can therefore carry, and what an access or erasure request can and cannot find. It states facts about the code and makes no legal claim. Capture documents the exclusion link beside it, including what a link carrying the parameter costs when anyone sends one to a real visitor.
|
|
90
|
+
|
|
91
|
+
- Everything the native engine stores has an end, and automated traffic does not count.
|
|
92
|
+
|
|
93
|
+
**Behavioral:** crawlers, link-preview fetchers, monitors and headless clients are dropped at ingest by default, decided from the request's `user-agent` before the body is read. A dropped beacon answers exactly what a kept one answers, `202` with `{ ok: true }` and the same headers, and a recognized marker logs nothing at all: automated traffic is expected on a public endpoint rather than a misconfiguration to report. An empty or absent agent counts as automated, since every real browser sends one. Native numbers therefore fall on upgrade, to what real visitors did, with the `other` bucket of the `browser` breakdown dropping the most; nothing is backfilled, so a range spanning the upgrade mixes filtered days with unfiltered ones. `trackServerEvent` writes through its own path and is never filtered, whatever agent it attributes the event to.
|
|
94
|
+
|
|
95
|
+
**Behavioral:** the nightly prune task (`analytics-prune-events`) is registered only on an install that sets `retentionDays` or the new `rollupRetentionDays`, and it sweeps the daily visitor salts as well as the collections whenever it runs. An install that sets neither registers no task, so it gains no jobs config it did not ask for. Setting a window on an install that had no tasks or workflows at all does give it Payload's `payload-jobs` collection and, for a scheduled task, the `payload-jobs-stats` global: push-mode installs pick the tables up on the next boot, and a migrate-mode Postgres install creates them in a migration, the same as for any other new collection. That was already true of `retentionDays` before this release and is unchanged by it.
|
|
96
|
+
|
|
97
|
+
**Additive:** `native({ rollupRetentionDays })` deletes rollup rows whose `period` is older than the window. Off by default, because rollups are the long-term store and an unfiltered day-granularity read is served from them alone. It takes a whole number of days above zero, requires `retentionDays`, and may not be shorter than it; both rules fail the boot rather than the sweep. Pruning rollups while keeping raw events forever would make an unfiltered long window answer less than the same window filtered, and a shorter rollup window would make a two-year report show less than a three-month one. Once a rollup row is pruned, the day it covered reports nothing rather than falling back to raw events. `retentionDays` itself is otherwise unchanged, including that zero or less still means keep everything; a value above zero now goes through the same check as the rollup window, so a window that is not a whole number of days, `Infinity` among them, fails the boot rather than the first nightly run.
|
|
98
|
+
|
|
99
|
+
**Additive:** `native({ filterBots })` takes `false` to count every beacon, or a `(ua: string) => boolean` predicate that replaces the built-in rule rather than extending it. A predicate that throws keeps the event and warns once per process, naming `filterBots`: a broken filter must not discard a site's traffic, and it must not do it in silence either.
|
|
100
|
+
|
|
101
|
+
**Additive:** a beacon that arrives with no user agent at all is dropped like any other automated traffic, and warns once per process that an intermediary may be stripping the header. A proxy that strips it would otherwise take an install's numbers to zero with nothing in the log to look at, while a recognized marker stays silent.
|
|
102
|
+
|
|
103
|
+
**Additive:** `isBot` and the `BotFilter` type are exported from `@10x-media/analytics/adapters/native`, so the same rule can run in an install's own middleware or edge config, or be composed with a filter of its own. It matches a small hand-held set of lowercase substrings anywhere in the agent, covering crawlers, link-preview fetchers, monitors and audits, headless and automation drivers, and the default agents of HTTP libraries; the docs table lists the families, and the set itself is deliberately not exported. There is no third-party list and no new dependency. Matching mid-word is what makes `bot` cover `Googlebot` and `AhrefsBot` without an entry each, so `Cubot` handset models are stripped from the agent before the scan and a Cubot phone stays a visitor.
|
|
104
|
+
|
|
105
|
+
**Fixed:** the daily visitor salts in `payload.kv` accumulated forever, one key per UTC day, with nothing ever deleting one. A first event of a new UTC day now deletes the seven days before the two most recent, at ingest, fire and forget, so no install needs a jobs runner to stop them piling up; the nightly task sweeps the days 2 to 62 back when it runs. Today's and yesterday's are always kept, since an event arriving just before midnight is still hashed with yesterday's. Keys are deleted by computed name rather than by listing them, so a sweep costs no scan, works on every kv adapter, and a day already gone is a no-op. An install down for longer than 62 days keeps the salts older than that, inert and one small value per day.
|
|
106
|
+
|
|
107
|
+
**Fixed:** the prune loaded every document it deleted. Deletes now go through the database adapter's bulk delete, so nothing is read in order to be removed, whatever the window matches. Collection hooks and access control are bypassed by a database-level delete, and the three collections involved use neither.
|
|
108
|
+
|
|
109
|
+
**Behavioral:** the prune task's output is consequently `{}` rather than `{ deleted: number }`, a shape change for anyone reading a job result: a count would cost exactly the read the bulk delete avoids.
|
|
110
|
+
|
|
111
|
+
### Patch Changes
|
|
112
|
+
|
|
113
|
+
- **Fixed: scroll depth read from raw events no longer collapses on Postgres.** The raw-event path (an hourly series, and any filtered read that bypasses the rollups) counted one scroll sample per event whenever the driver returned an unreported depth as `null` rather than omitting the field, which Postgres does for every event that carried no depth. The average was then divided by every event in range instead of by the pageviews that actually reported a depth, so a site whose tracker reports depth on a fraction of its pageviews saw a scroll depth several times too low on Postgres while the rollup-backed reads of the same range showed the right number. Only a depth that is a number counts as a sample now, on both adapters, and a reported `0` still counts.
|
|
114
|
+
|
|
115
|
+
## 1.0.0-beta.9
|
|
116
|
+
|
|
117
|
+
### Minor Changes
|
|
118
|
+
|
|
119
|
+
- **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.
|
|
120
|
+
|
|
121
|
+
**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.
|
|
122
|
+
|
|
123
|
+
**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.
|
|
124
|
+
|
|
125
|
+
**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.
|
|
126
|
+
|
|
127
|
+
**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.
|
|
128
|
+
|
|
129
|
+
**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.
|
|
130
|
+
|
|
131
|
+
**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.
|
|
132
|
+
|
|
133
|
+
- **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.
|
|
134
|
+
|
|
135
|
+
**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.
|
|
136
|
+
|
|
137
|
+
**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.
|
|
138
|
+
|
|
139
|
+
**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.
|
|
140
|
+
|
|
141
|
+
**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`.
|
|
142
|
+
|
|
143
|
+
**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.
|
|
144
|
+
|
|
145
|
+
**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.
|
|
146
|
+
|
|
147
|
+
**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`.
|
|
148
|
+
|
|
149
|
+
**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.
|
|
150
|
+
|
|
151
|
+
**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.
|
|
152
|
+
|
|
153
|
+
- **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.
|
|
154
|
+
|
|
155
|
+
**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.
|
|
156
|
+
|
|
157
|
+
**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`.
|
|
158
|
+
|
|
159
|
+
**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.
|
|
160
|
+
|
|
161
|
+
**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.
|
|
162
|
+
|
|
163
|
+
**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.
|
|
164
|
+
|
|
165
|
+
**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.
|
|
166
|
+
|
|
167
|
+
**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.
|
|
168
|
+
|
|
169
|
+
**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.
|
|
170
|
+
|
|
171
|
+
**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.
|
|
172
|
+
|
|
173
|
+
- **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.
|
|
174
|
+
|
|
175
|
+
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.
|
|
176
|
+
|
|
177
|
+
**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.
|
|
178
|
+
|
|
179
|
+
**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.
|
|
180
|
+
|
|
181
|
+
**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.
|
|
182
|
+
|
|
183
|
+
**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.
|
|
184
|
+
|
|
185
|
+
## 1.0.0-beta.8
|
|
186
|
+
|
|
187
|
+
### Minor Changes
|
|
188
|
+
|
|
189
|
+
- **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 }`).
|
|
190
|
+
|
|
191
|
+
`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`.
|
|
192
|
+
|
|
193
|
+
`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.
|
|
194
|
+
|
|
195
|
+
`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.
|
|
196
|
+
|
|
197
|
+
**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.
|
|
198
|
+
|
|
199
|
+
**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`.
|
|
200
|
+
|
|
201
|
+
**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.
|
|
202
|
+
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
- **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.
|
|
206
|
+
|
|
207
|
+
**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.
|
|
208
|
+
|
|
209
|
+
**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.
|
|
210
|
+
|
|
211
|
+
**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.
|
|
212
|
+
|
|
213
|
+
- **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.
|
|
214
|
+
|
|
215
|
+
**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.
|
|
216
|
+
|
|
217
|
+
**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.
|
|
218
|
+
|
|
219
|
+
**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.
|
|
220
|
+
|
|
221
|
+
**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.
|
|
222
|
+
|
|
223
|
+
- **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`.
|
|
224
|
+
|
|
225
|
+
`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`.
|
|
226
|
+
|
|
227
|
+
**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.
|
|
228
|
+
|
|
229
|
+
**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.
|
|
230
|
+
|
|
231
|
+
**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.
|
|
232
|
+
|
|
233
|
+
## 1.0.0-beta.7
|
|
234
|
+
|
|
235
|
+
### Minor Changes
|
|
236
|
+
|
|
237
|
+
- **Breaking: first-class event capture.** Capture-capable adapters (native, PostHog, Plausible, Umami) now declare a `capture` descriptor: proxy routes, a snippet, and a public client config. An adapter declares one only when the public config capture needs is present, so a read-only PostHog (no `projectToken`) or a Plausible with neither `domain` nor `scriptId` gets no proxy route, no snippet, and fills no slot; reads are unaffected. The descriptor drives three new surfaces:
|
|
238
|
+
|
|
239
|
+
- A first-party runtime proxy at `/api/analytics/p/<slot>/*` (public; declared routes only; GET, POST and OPTIONS served, and PUT, PATCH and DELETE answered 405; cookies and authorization never forwarded and `set-cookie` never returned; body cap and timeout via `capture.proxy.{maxBodyBytes,timeoutMs}`; 404 for unknown slots or paths, 413 over the cap, 400 on a body that dies in transit, 502 on upstream failure). No rate limiting yet.
|
|
240
|
+
- `captureRewrites([{ path, adapter }])` from `@10x-media/analytics/next` for installs that prefer Next rewrites. `posthogProxyRewrites` now wraps it and is deprecated; its emitted param name changed from `:path*` to `:p*` (equivalent for Next). Root mounts and nested or duplicate mount paths throw.
|
|
241
|
+
- A public `GET /api/analytics/tracker` endpoint plus `getTrackerConfig(payload, { headers })` and the `AnalyticsScripts` server component (`@10x-media/analytics/rsc`) that resolve per-request capture config for up to two slots, `global` and `tenant`, one adapter each, deduped when both resolve to the same adapter. Vendor snippets are rendered only for slots that do not require consent; consent-gated vendors load after `consent('granted')`.
|
|
242
|
+
|
|
243
|
+
**Breaking: native engine.** Ingest accepts `type: 'goal'`, plus `value`, `currency` and `scrollDepth` on any event; a missing or non-string `name` on events and goals answers 400 (a nameless `type: 'event'` previously ingested); `name` is capped at 128 characters and `props`, previously stored verbatim, is sanitized to at most 20 flat scalar keys. Config `goals` (`{ slug, name, match: { kind: 'goal' | 'event' | 'path' }, value?, currency? }`) are matched at ingest into `goal` rollup buckets and stamped onto the stored event. `DimensionKey` gains `goal`, `RollupDelta.inc` widens to the full counter set, and `AdapterRegisterContext` gains a required `resolveGoals(req, scope)` that any code building that context by hand must supply. Existing native installs need a migration adding four numeric rollup counters, the `value`, `currency`, `scrollDepth` and `goals` event fields, and the `goal` event type (snippet in the native docs; on Postgres the enum change is irreversible).
|
|
244
|
+
|
|
245
|
+
**Behavioral:** native serves `conversions`, `revenue` (summed in the event's currency, no conversion) and `scrollDepth` (average over the pageviews that reported one), and a `goal` dimension that is groupable but not filterable. A `goal` event counts under `events` and never appears in the `event` dimension breakdown. Goal buckets also accrue visitor and session rows. The native ingest endpoint now caps the request body at 64 KiB (`413` above it), answers `400` on unparseable or non-object JSON (previously a logged `500`), drops a non-finite, negative or over-a-day `durationMs`, and truncates `path` to 512 and `hostname` to 253 characters. `autoCapture` is on by default except `scrollDepth`. Consent defaults per tracker family: vendors require it, native does not.
|
|
246
|
+
|
|
247
|
+
**Additive:** new subpaths `@10x-media/analytics/tracker` (dependency-free browser tracker: `page`, `track`, `trackGoal`, a consent gate whose decision persists under the `analytics:consent` storage key and whose pending events wait in a bounded in-memory queue, SPA route tracking, scroll depth, outbound links, file downloads, `data-analytics-goal` on click and submit) and `@10x-media/analytics/react` (`AnalyticsProvider`, `useAnalytics`, `TrackerBoot`). `useAnalytics()` also works without a provider once `TrackerBoot` has booted. Vendor snippets are self-sequencing (PostHog's official queued stub, Plausible's per-site stub) and carry the CSP nonce, which the PostHog stub propagates onto the bundle it injects. New options: `capture.{slots, paths, consent, autoCapture, proxy}` and `goals` (array, or `{ defaults }`); `capture.slots.<slot>: false` disables a slot; `capture.consent` overrides per slot, per adapter id, or through a resolver. `AnalyticsAdapter` gains optional `capture` and `ingest` members; PostHog gains `region` and `projectToken`; Plausible gains `domain` and `scriptId`; Umami's `host` also serves as the app origin for capture. The widget pickers offer `conversions`, `revenue` and `scrollDepth`, and a new `analytics-breakdown-goals` block lists goal completions.
|
|
248
|
+
|
|
249
|
+
- Engine hardening. Provider reads now run under a real timeout (`cache.timeoutMs`, default 15s) delivered to adapters as `AdapterContext.signal`, retry with backoff only on 429/5xx (one retry for network failures, none for other 4xx or aborts), and respect each adapter's declared rate limits through per-adapter token buckets (`requestsPerMinute`/`requestsPerHour`/`maxConcurrent`). When a refresh fails and an expired cache entry is still within a 24 hour stale window, the read serves it flagged `meta.stale: true` instead of degrading, and failures are logged with the adapter id. Also: native `realtime()` now honors `hostname` and `path` the way aggregate reads do, multiple filters on one dimension compose as AND instead of last-wins, and the client-side capability check mirrors the server's filter requirements.
|
|
250
|
+
|
|
251
|
+
- Multi-tenancy completes. A new `scopes` option enumerates tenant scopes so the cache-warm and sync cron tiers fan out per tenant (each scope resolves its own runtime providers and sync rows carry that scope); without it both tiers keep running install-wide only. Installs with runtime providers (`providers.collection` or `providers.resolve`) no longer treat the config-adapter capability union as a ceiling: every built-in widget registers, the metric pickers offer every metric, and the realtime endpoint is always available, with the per-request sources endpoint and pickers narrowing to what each tenant's sources actually serve. The dev app gains a `TENANCY=on` mode wired through `@payloadcms/plugin-multi-tenant` with two seeded tenants, and the e2e suite runs in both tenancy shapes. The sync task no longer derives a scope from the job request (it fans out over `scopes` and otherwise runs install-wide), and reads on a scoped install that resolve no scope now fail closed unless `access.platformRead` grants.
|
|
252
|
+
|
|
253
|
+
### Patch Changes
|
|
254
|
+
|
|
255
|
+
- Updated dependencies:
|
|
256
|
+
- @10x-media/fields@0.1.0-beta.7
|
|
257
|
+
|
|
258
|
+
## 1.0.0-beta.6
|
|
259
|
+
|
|
260
|
+
### Minor Changes
|
|
261
|
+
|
|
262
|
+
- More built-in locales for the `analytics:` strings.
|
|
263
|
+
|
|
264
|
+
- Added: `es`, `fr`, `id`, `pt`, `ru`, `zh`, `uk`, `ar`, `ko`. Every key is covered in each.
|
|
265
|
+
|
|
266
|
+
- **Breaking:** the query contract grows real filters and finer granularity, and two schemas change. `AnalyticsCapabilities` now requires `filters` and `filterOperators` declarations (custom adapters must add them). `AnalyticsQuery.filters` is honored by native (from raw events, retention-bounded, `eq`/`contains`), PostHog (`eq`/`contains`/`matches` via HogQL), Plausible and GA4 (`eq`), and the widget read helpers accept a `filters` option gated by capability. Native gains the `event` name dimension and `hour` granularity (UTC hour buckets from raw events). Native rollups are now keyed by hostname: deltas write both a hostname-less and a per-hostname bucket family, so `binding.hostname` finally filters native reads with exact unique counts; existing installs must run a migration adding the `hostname` column (backfill `''`) and, on Postgres, rebuilding the rollup unique index to include it: until that index is rebuilt, every native rollup write fails outright on migrate-mode Postgres, not just colliding ones (rebuild DDL is in the native docs). Distinct counting resets once within the deploy-day bucket because ledger keys changed shape. The sync collection gains a required `scope` column (backfill `''`, unique key now source+date+scope) and its read access is scope-filtered in scoped installs, closing a would-be cross-tenant read of synced daily metrics. Migrate-mode Postgres installs must rebuild that unique index too, exactly like the rollups index above; both rebuilds are documented in the native docs' upgrade note.
|
|
267
|
+
|
|
268
|
+
### Patch Changes
|
|
269
|
+
|
|
270
|
+
- Updated dependencies:
|
|
271
|
+
- @10x-media/fields@0.1.0-beta.6
|
|
272
|
+
|
|
3
273
|
## 0.1.0-beta.5
|
|
4
274
|
|
|
5
275
|
### 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,9 +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
|
-
- **
|
|
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 of events, the seen ledger and the daily visitor salts, with rollups pruned only once you set a window of their own, and opt-in write batching. Crawlers, link-preview fetchers, monitors and headless clients are dropped at ingest by their user agent, on by default and replaceable with your own predicate. It classifies the visit's named origin (`utm_source`, else the referrer host, else `direct`), its acquisition channel (twelve tokens, paid split per platform), the 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; `?analytics_exclude=1` takes a staff browser out of capture (and sets each vendor's own opt-out), `=0` puts it back; 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, eleven 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.
|
|
16
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 a `fetchQuery` helper for admin code. Every endpoint the plugin registers answers a refusal in one envelope, `{ error: { code, message, param? } }`, over one typed code vocabulary, with `readErrorCode` for clients that branch on it; the capture proxy is the deliberate exception and stays bodyless for the vendor SDK reading it.
|
|
17
21
|
- **Caching** through `payload.kv` with request coalescing, plus an opt-in scheduled warm job.
|
|
18
22
|
- **Sync tier**: persist provider daily metrics into a queryable Payload collection.
|
|
19
23
|
- **Typed translations** with per-key overrides via `@10x-media/analytics/i18n`.
|
|
@@ -47,7 +51,7 @@ export default buildConfig({
|
|
|
47
51
|
})
|
|
48
52
|
```
|
|
49
53
|
|
|
50
|
-
Run `payload generate:importmap`,
|
|
54
|
+
Run `payload generate:importmap`, render `<AnalyticsScripts config={await getTrackerConfig(payload, { headers: await headers() })} />` from `@10x-media/analytics/rsc` in your root layout, and the dashboard fills in.
|
|
51
55
|
|
|
52
56
|
## Documentation
|
|
53
57
|
|
|
@@ -56,13 +60,20 @@ Full documentation at [docs.10xmedia.de](https://docs.10xmedia.de/analytics):
|
|
|
56
60
|
- [Overview](https://docs.10xmedia.de/analytics)
|
|
57
61
|
- [Quick start](https://docs.10xmedia.de/analytics/quick-start)
|
|
58
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)
|
|
59
65
|
- [Native engine](https://docs.10xmedia.de/analytics/native)
|
|
66
|
+
- [Capture](https://docs.10xmedia.de/analytics/capture)
|
|
67
|
+
- [Goals](https://docs.10xmedia.de/analytics/goals)
|
|
68
|
+
- [First-party proxy](https://docs.10xmedia.de/analytics/proxy)
|
|
60
69
|
- [Geo resolution](https://docs.10xmedia.de/analytics/geo)
|
|
70
|
+
- [Privacy](https://docs.10xmedia.de/analytics/privacy)
|
|
61
71
|
- [Display fields](https://docs.10xmedia.de/analytics/display-fields)
|
|
62
72
|
- [Dashboard widgets](https://docs.10xmedia.de/analytics/widgets)
|
|
63
73
|
- [Caching and warming](https://docs.10xmedia.de/analytics/cache)
|
|
64
74
|
- [Reporting timezone](https://docs.10xmedia.de/analytics/timezone)
|
|
65
75
|
- [Sync tier](https://docs.10xmedia.de/analytics/sync)
|
|
76
|
+
- [Multi-tenancy](https://docs.10xmedia.de/analytics/multi-tenancy)
|
|
66
77
|
- [i18n](https://docs.10xmedia.de/analytics/i18n)
|
|
67
78
|
|
|
68
79
|
## License
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
//#region src/adapters/ga4/disableKey.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* GA4's own kill switch: `window['ga-disable-<measurementId>'] = true` stops the tag sending
|
|
4
|
+
* anything (https://developers.google.com/tag-platform/security/guides/privacy).
|
|
5
|
+
*/
|
|
6
|
+
declare const GA4_DISABLE_PREFIX = "ga-disable-";
|
|
7
|
+
//#endregion
|
|
8
|
+
export { GA4_DISABLE_PREFIX };
|
|
9
|
+
//# sourceMappingURL=disableKey.d.ts.map
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import { EXCLUSION_STORAGE_KEY } from "../../tracker/exclusion.js";
|
|
2
|
+
//#region src/adapters/ga4/disableKey.ts
|
|
3
|
+
/**
|
|
4
|
+
* GA4's own kill switch: `window['ga-disable-<measurementId>'] = true` stops the tag sending
|
|
5
|
+
* anything (https://developers.google.com/tag-platform/security/guides/privacy).
|
|
6
|
+
*/
|
|
7
|
+
const GA4_DISABLE_PREFIX = "ga-disable-";
|
|
8
|
+
/** The switch's property name for one measurement id. */
|
|
9
|
+
const ga4DisableKey = (measurementId) => `${GA4_DISABLE_PREFIX}${measurementId}`;
|
|
10
|
+
/**
|
|
11
|
+
* The statement the snippet runs before its first `gtag()` call. Google honours the switch
|
|
12
|
+
* only ahead of that call and the property does not survive a page load, so the rendered
|
|
13
|
+
* snippet has to read the exclusion flag itself: the tracker's own effect runs after the
|
|
14
|
+
* snippet has already queued `gtag('config', ...)`. Storage can be blocked, and a snippet
|
|
15
|
+
* that threw would take the rest of the inline with it.
|
|
16
|
+
*/
|
|
17
|
+
const ga4ExcludeGuard = (measurementId) => `try{if(localStorage.getItem(${JSON.stringify(EXCLUSION_STORAGE_KEY)})==="1")window[${JSON.stringify(ga4DisableKey(measurementId))}]=true}catch(e){}`;
|
|
18
|
+
//#endregion
|
|
19
|
+
export { GA4_DISABLE_PREFIX, ga4DisableKey, ga4ExcludeGuard };
|
|
20
|
+
|
|
21
|
+
//# sourceMappingURL=disableKey.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"disableKey.js","names":[],"sources":["../../../src/adapters/ga4/disableKey.ts"],"sourcesContent":["import { EXCLUSION_STORAGE_KEY } from '../../tracker/exclusion'\n\n/**\n * GA4's own kill switch: `window['ga-disable-<measurementId>'] = true` stops the tag sending\n * anything (https://developers.google.com/tag-platform/security/guides/privacy).\n */\nexport const GA4_DISABLE_PREFIX = 'ga-disable-'\n\n/** The switch's property name for one measurement id. */\nexport const ga4DisableKey = (measurementId: string): string =>\n\t`${GA4_DISABLE_PREFIX}${measurementId}`\n\n/**\n * The statement the snippet runs before its first `gtag()` call. Google honours the switch\n * only ahead of that call and the property does not survive a page load, so the rendered\n * snippet has to read the exclusion flag itself: the tracker's own effect runs after the\n * snippet has already queued `gtag('config', ...)`. Storage can be blocked, and a snippet\n * that threw would take the rest of the inline with it.\n */\nexport const ga4ExcludeGuard = (measurementId: string): string =>\n\t`try{if(localStorage.getItem(${JSON.stringify(EXCLUSION_STORAGE_KEY)})===\"1\")window[${JSON.stringify(ga4DisableKey(measurementId))}]=true}catch(e){}`\n"],"mappings":";;;;;;AAMA,MAAa,qBAAqB;;AAGlC,MAAa,iBAAiB,kBAC7B,GAAG,qBAAqB;;;;;;;;AASzB,MAAa,mBAAmB,kBAC/B,+BAA+B,KAAK,UAAU,qBAAqB,EAAE,iBAAiB,KAAK,UAAU,cAAc,aAAa,CAAC,EAAE"}
|
|
@@ -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
|