@10x-media/analytics 1.0.0-beta.8 → 1.0.0-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +70 -0
- package/LICENSE +21 -21
- package/README.md +3 -3
- 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 +178 -70
- package/dist/adapters/ga4/ga4.js.map +1 -1
- package/dist/adapters/ga4/measurementId.js +15 -0
- package/dist/adapters/ga4/measurementId.js.map +1 -0
- package/dist/adapters/goalRead.js +126 -0
- package/dist/adapters/goalRead.js.map +1 -0
- package/dist/adapters/plausible/plausible.d.ts +15 -0
- package/dist/adapters/plausible/plausible.js +110 -42
- package/dist/adapters/plausible/plausible.js.map +1 -1
- package/dist/adapters/posthog/posthog.js +47 -25
- package/dist/adapters/posthog/posthog.js.map +1 -1
- package/dist/adapters/umami/umami.d.ts +8 -0
- package/dist/adapters/umami/umami.js +237 -28
- package/dist/adapters/umami/umami.js.map +1 -1
- package/dist/charts/BarList.js +8 -2
- package/dist/charts/BarList.js.map +1 -1
- package/dist/core/cacheKey.js +11 -1
- package/dist/core/cacheKey.js.map +1 -1
- package/dist/core/capabilities.js +7 -2
- package/dist/core/capabilities.js.map +1 -1
- package/dist/core/capture.d.ts +1 -1
- package/dist/core/contract.d.ts +32 -2
- package/dist/core/contract.js.map +1 -1
- package/dist/core/options.d.ts +8 -2
- package/dist/core/options.js +4 -2
- package/dist/core/options.js.map +1 -1
- package/dist/core/serverEvent.d.ts +4 -2
- package/dist/core/serverEvent.js.map +1 -1
- package/dist/exports/adapters/ga4.d.ts +2 -1
- package/dist/exports/adapters/ga4.js +2 -1
- package/dist/exports/client.d.ts +5 -2
- package/dist/exports/client.js +4 -1
- package/dist/exports/rsc.d.ts +2 -1
- package/dist/exports/tracker.d.ts +3 -2
- package/dist/exports/tracker.js +2 -1
- package/dist/exports/types.d.ts +2 -1
- package/dist/exports/types.js +2 -1
- 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 +1 -1
- package/dist/fields/config/SourceSelectField.js +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.js +16 -4
- package/dist/fields/readForDocument.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +2 -1
- package/dist/index.js.map +1 -1
- package/dist/native/collections/events.js +36 -0
- package/dist/native/collections/events.js.map +1 -1
- package/dist/native/eventScan.js +25 -0
- package/dist/native/eventScan.js.map +1 -0
- package/dist/native/ingest/browser.js +47 -0
- package/dist/native/ingest/browser.js.map +1 -0
- package/dist/native/ingest/flushBatch.js +26 -26
- package/dist/native/ingest/flushBatch.js.map +1 -1
- package/dist/native/ingest/language.js +14 -0
- package/dist/native/ingest/language.js.map +1 -0
- package/dist/native/ingest/normalizeEvent.d.ts +6 -0
- package/dist/native/ingest/normalizeEvent.js +32 -5
- package/dist/native/ingest/normalizeEvent.js.map +1 -1
- package/dist/native/ingest/referrer.js +48 -0
- package/dist/native/ingest/referrer.js.map +1 -0
- package/dist/native/ingest/serverTrack.js +1 -0
- package/dist/native/ingest/serverTrack.js.map +1 -1
- package/dist/native/ingest/source.d.ts +7 -0
- package/dist/native/ingest/source.js +139 -14
- package/dist/native/ingest/source.js.map +1 -1
- package/dist/native/ingest/utm.js +33 -0
- package/dist/native/ingest/utm.js.map +1 -0
- package/dist/native/nativeAdapter.js +32 -26
- package/dist/native/nativeAdapter.js.map +1 -1
- package/dist/native/query/eventAgg.js +14 -1
- package/dist/native/query/eventAgg.js.map +1 -1
- package/dist/native/rollups/bucketKey.js +15 -0
- package/dist/native/rollups/bucketKey.js.map +1 -0
- package/dist/native/rollups/bumpRollups.js +116 -0
- package/dist/native/rollups/bumpRollups.js.map +1 -0
- package/dist/native/rollups/deltas.js +30 -15
- package/dist/native/rollups/deltas.js.map +1 -1
- package/dist/native/rollups/insertManyIfNew.js +93 -0
- package/dist/native/rollups/insertManyIfNew.js.map +1 -0
- package/dist/next/captureRewrites.d.ts +3 -2
- package/dist/next/captureRewrites.js +3 -2
- package/dist/next/captureRewrites.js.map +1 -1
- package/dist/plugin/documentEndpoint.js +26 -7
- package/dist/plugin/documentEndpoint.js.map +1 -1
- package/dist/plugin/goalHint.d.ts +1 -0
- package/dist/plugin/goalHint.js +24 -0
- package/dist/plugin/goalHint.js.map +1 -0
- package/dist/plugin/queryEndpoint.js +19 -12
- package/dist/plugin/queryEndpoint.js.map +1 -1
- package/dist/plugin/realtimeEndpoint.js +40 -15
- package/dist/plugin/realtimeEndpoint.js.map +1 -1
- package/dist/plugin/responses.js +17 -0
- package/dist/plugin/responses.js.map +1 -0
- package/dist/plugin/sourcesEndpoint.js +10 -3
- package/dist/plugin/sourcesEndpoint.js.map +1 -1
- package/dist/providers/collection.js +14 -4
- package/dist/providers/collection.js.map +1 -1
- package/dist/providers/factory.js +4 -2
- package/dist/providers/factory.js.map +1 -1
- package/dist/query/response.d.ts +4 -1
- package/dist/query/response.js +11 -0
- package/dist/query/response.js.map +1 -0
- package/dist/surfacing/engine.js +1 -1
- package/dist/surfacing/engine.js.map +1 -1
- package/dist/testing/memoryAdapter.js +0 -1
- package/dist/testing/memoryAdapter.js.map +1 -1
- package/dist/tracker/createTracker.js +13 -1
- package/dist/tracker/createTracker.js.map +1 -1
- package/dist/tracker/sinks/ga4.d.ts +21 -0
- package/dist/tracker/sinks/ga4.js +26 -0
- package/dist/tracker/sinks/ga4.js.map +1 -0
- package/dist/tracker/types.d.ts +5 -0
- package/dist/translations/ar.js +30 -1
- package/dist/translations/ar.js.map +1 -1
- package/dist/translations/de.js +30 -1
- package/dist/translations/de.js.map +1 -1
- package/dist/translations/en.js +30 -1
- package/dist/translations/en.js.map +1 -1
- package/dist/translations/es.js +30 -1
- package/dist/translations/es.js.map +1 -1
- package/dist/translations/fr.js +30 -1
- package/dist/translations/fr.js.map +1 -1
- package/dist/translations/id.js +30 -1
- package/dist/translations/id.js.map +1 -1
- package/dist/translations/keys.d.ts +29 -0
- package/dist/translations/keys.js +30 -1
- package/dist/translations/keys.js.map +1 -1
- package/dist/translations/ko.js +30 -1
- package/dist/translations/ko.js.map +1 -1
- package/dist/translations/metricKeys.js +7 -1
- package/dist/translations/metricKeys.js.map +1 -1
- package/dist/translations/pt.js +30 -1
- package/dist/translations/pt.js.map +1 -1
- package/dist/translations/ru.js +30 -1
- package/dist/translations/ru.js.map +1 -1
- package/dist/translations/server.js.map +1 -1
- package/dist/translations/uk.js +30 -1
- package/dist/translations/uk.js.map +1 -1
- package/dist/translations/zh.js +30 -1
- package/dist/translations/zh.js.map +1 -1
- package/dist/view/AnalyticsViewClient.js +13 -2
- package/dist/view/AnalyticsViewClient.js.map +1 -1
- package/dist/view/gating.js +40 -3
- package/dist/view/gating.js.map +1 -1
- package/dist/view/labels.js +21 -1
- package/dist/view/labels.js.map +1 -1
- package/dist/view/sections/Breakdowns.js +78 -38
- package/dist/view/sections/Breakdowns.js.map +1 -1
- package/dist/view/sections/FilterChips.js +8 -3
- package/dist/view/sections/FilterChips.js.map +1 -1
- package/dist/view/sections/GoalsPanel.js +2 -1
- package/dist/view/sections/GoalsPanel.js.map +1 -1
- package/dist/view/sections/RealtimeStrip.js +4 -1
- package/dist/view/sections/RealtimeStrip.js.map +1 -1
- package/dist/view/sections/Toolbar.js +10 -3
- package/dist/view/sections/Toolbar.js.map +1 -1
- package/dist/view/sections/Trend.js +8 -2
- package/dist/view/sections/Trend.js.map +1 -1
- package/dist/view/state.js +7 -2
- package/dist/view/state.js.map +1 -1
- package/dist/view/useViewQueries.js +6 -3
- package/dist/view/useViewQueries.js.map +1 -1
- package/dist/widgets/AnalyticsBreakdownWidget.js +59 -10
- package/dist/widgets/AnalyticsBreakdownWidget.js.map +1 -1
- package/dist/widgets/AnalyticsGoalsWidget.js +10 -2
- package/dist/widgets/AnalyticsGoalsWidget.js.map +1 -1
- package/dist/widgets/AnalyticsMetricWidget.js +30 -3
- package/dist/widgets/AnalyticsMetricWidget.js.map +1 -1
- package/dist/widgets/AnalyticsRealtimeWidget.js +3 -1
- package/dist/widgets/AnalyticsRealtimeWidget.js.map +1 -1
- package/dist/widgets/AnalyticsTrendWidget.js +30 -3
- package/dist/widgets/AnalyticsTrendWidget.js.map +1 -1
- package/dist/widgets/RealtimeCounter.d.ts +4 -0
- package/dist/widgets/RealtimeCounter.js +10 -1
- package/dist/widgets/RealtimeCounter.js.map +1 -1
- package/dist/widgets/breakdownTypes.js.map +1 -1
- package/dist/widgets/comparison.js +15 -1
- package/dist/widgets/comparison.js.map +1 -1
- package/dist/widgets/defaults.d.ts +6 -2
- package/dist/widgets/defaults.js +72 -25
- package/dist/widgets/defaults.js.map +1 -1
- package/dist/widgets/filterCaption.js +27 -0
- package/dist/widgets/filterCaption.js.map +1 -0
- package/dist/widgets/filterField.d.ts +19 -0
- package/dist/widgets/filterField.js +75 -0
- package/dist/widgets/filterField.js.map +1 -0
- package/dist/widgets/prepareWidgetRead.d.ts +7 -0
- package/dist/widgets/prepareWidgetRead.js +74 -0
- package/dist/widgets/prepareWidgetRead.js.map +1 -0
- package/dist/widgets/readForWidget.d.ts +12 -2
- package/dist/widgets/readForWidget.js +34 -49
- package/dist/widgets/readForWidget.js.map +1 -1
- package/dist/widgets/readForWidgetBreakdown.d.ts +17 -1
- package/dist/widgets/readForWidgetBreakdown.js +29 -42
- package/dist/widgets/readForWidgetBreakdown.js.map +1 -1
- package/dist/widgets/readForWidgetGoals.d.ts +11 -1
- package/dist/widgets/readForWidgetGoals.js +44 -30
- package/dist/widgets/readForWidgetGoals.js.map +1 -1
- package/dist/widgets/readForWidgetRealtime.d.ts +8 -0
- package/dist/widgets/readForWidgetRealtime.js +21 -20
- package/dist/widgets/readForWidgetRealtime.js.map +1 -1
- package/dist/widgets/readForWidgetSeries.d.ts +11 -1
- package/dist/widgets/readForWidgetSeries.js +38 -49
- package/dist/widgets/readForWidgetSeries.js.map +1 -1
- package/dist/widgets/readMeta.js +18 -0
- package/dist/widgets/readMeta.js.map +1 -0
- package/dist/widgets/registerWidgets.js +5 -2
- package/dist/widgets/registerWidgets.js.map +1 -1
- package/dist/widgets/types.d.ts +15 -0
- package/dist/widgets/types.js.map +1 -1
- package/dist/widgets/viewLink.js +5 -2
- package/dist/widgets/viewLink.js.map +1 -1
- package/package.json +5 -5
- package/dist/native/rollups/applyDistinctDeltas.js +0 -9
- package/dist/native/rollups/applyDistinctDeltas.js.map +0 -1
- package/dist/native/rollups/bumpRollup.js +0 -73
- package/dist/native/rollups/bumpRollup.js.map +0 -1
- package/dist/native/rollups/insertIfNew.js +0 -53
- package/dist/native/rollups/insertIfNew.js.map +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,75 @@
|
|
|
1
1
|
# @10x-media/analytics
|
|
2
2
|
|
|
3
|
+
## 1.0.0-beta.9
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- **Fixed: a failed goal resolver no longer poisons the healthy cache entry.** When the goals resolver threw, the read carried an empty goal hint, the provider answered `meta.goalsUnresolved`, and the engine cached that answer at the aggregate TTL under the same key a healthy read with no goals uses. The hint is now three-way: the scope's slugs (an empty list when no goals are configured, which is an empty result rather than a failure), `'unresolved'` when the resolver failed (its own `goals:!unresolved` cache segment, which no list of slugs can produce, and the short realtime TTL), or absent when the read does not ask about goals.
|
|
8
|
+
|
|
9
|
+
**Behavioral for adapter authors: `AnalyticsQuery.goalSlugs` is typed `string[] | 'unresolved'`.** An adapter that reads the hint must handle the sentinel: the slugs to filter goal rows by, an empty list to filter by none, or a failure to report as `meta.goalsUnresolved` rather than as an empty table. The built-in provider adapters answer all three through one shared helper. `GET /api/analytics/query` echoes the hint it used under `query.goalSlugs`, so a client can tell a scope with no goals from a resolver that failed.
|
|
10
|
+
|
|
11
|
+
**Fixed: a scope with no goals says so instead of reading as nobody converting.** The goals panel, the goals widget and both goal breakdowns fell through to the plain "No data yet" whenever the scope configured no goals. They now render `stateNoGoals` ("No goals are configured for this scope", in all 11 locales) for that case, keeping the unresolved-goals state for a source that could not answer at all.
|
|
12
|
+
|
|
13
|
+
**Fixed: a sampled native read says so everywhere.** A filtered or hourly native read that hits the event scan limit sets `meta.sampled`; `realtime()` now sets it too (both paths build their meta through one `eventScanMeta`), and the view and the widgets show a notice for it beside the clamped and stale ones instead of presenting truncated numbers as exact. **Additive:** the realtime strip and the realtime widget carry the notice through their polls, and `RealtimeCounter` gained two optional props for it, `initialSampled` and `sampledLabel`, with no notice rendered when the label is left off.
|
|
14
|
+
|
|
15
|
+
**Behavioral: every widget carries the same read flags.** The five widget read helpers share one prologue and one meta mapping, so the metric widget now shows the unresolved-goals notice for `conversions` and the trend widget shows the stale notice, both of which they used to omit while their siblings showed them.
|
|
16
|
+
|
|
17
|
+
**Fixed: the realtime endpoint answers 503 with `Retry-After` when its source fails**, matching the query endpoint, instead of an unhandled 500. A gate that throws is not retryable and answers 500 instead, since polling again cannot fix a configuration bug. The realtime, sources and document endpoints send `cache-control: private, no-store` like the query endpoint, since all of them answer per reader.
|
|
18
|
+
|
|
19
|
+
**Behavioral: `analyticsDefaultWidgets()` lists every built-in widget.** The default dashboard layout stopped at the seven widgets of Phase 3a and omitted goals, realtime, referrers, browsers, operating systems, campaigns and events; it now places all of them. Installs that passed their own layout are unaffected.
|
|
20
|
+
|
|
21
|
+
- **Additive: native dimensions.** The native engine now serves `referrer`, `region`, `city`, `browser`, `os`, `language`, `utmSource`, `utmMedium`, `utmCampaign`, `utmContent` and `utmTerm` as breakdown dimensions, from the rollup and the filtered read paths alike, and all eleven are filterable with `eq` and `contains`. Browser and OS are classified from the user agent at ingest with a small built-in table, language from the request's first accepted language, and the campaign keys (case preserved, capped at 128) from a new `query` field the tracker sends with pageviews. The referrers, browsers, operating systems and campaigns widgets therefore rank rows on a native-only install instead of being skipped for lack of a serving adapter. Native's `filters` set is now every dimension it serves except `goal`, whose completions live in a json column rather than a field a `where` can compare.
|
|
22
|
+
|
|
23
|
+
**Additive: `capture.autoCapture.query`** (default true). The tracker sends each pageview's query string, without its leading `?` and capped at 512 characters, so ingest can extract the five `utm_*` keys. The raw query is never stored, only those five values; set the option false to stop sending it at all, at the cost of the campaign breakdowns.
|
|
24
|
+
|
|
25
|
+
**Breaking (native installs):** the events collection gains nine text columns (`browser`, `os`, `language`, the five `utm*`, and `referrerHost`, the bare host the `referrer` dimension groups and filters on). Postgres migrate-mode installs must run the migration in the native docs before upgrading; it is idempotent and deliberately not reversible, since dropping the columns would discard already-attributed events. Mongo needs nothing, and push-mode installs pick the columns up on the next boot. Events ingested before the migration keep their old attribution: nothing is backfilled.
|
|
26
|
+
|
|
27
|
+
**Additive: a group-by picker per breakdown tab.** Each breakdown tab in the analytics view read one dimension, so the eleven new ones were unreachable in the view, and most had no widget either. A tab that groups by more than one dimension the source serves now carries a **Group by** select beside the row limit: technology switches between devices, browsers and operating systems, geography between countries, regions, cities and languages, sources between the source dimension, the referrer and every campaign key. The pick is URL state (`dim`), omitted when it is the tab's default, and dropped when the selected source cannot serve it. Breakdown widgets pass their own dimension into their view link, so the browsers, operating systems, referrers and campaigns widgets now open the view on the grouping they were showing.
|
|
28
|
+
|
|
29
|
+
**Behavioral (the Sources tab's default):** the tab now opens on `source` rather than `referrer`. That is no change on native, which did not serve `referrer` before this release, but a provider serving both (Plausible, GA4) opens the Sources tab on the derived source instead of the referring host it used to rank. The referring host is one pick away in the new **Group by** select, and an existing link naming `tab=sources` opens on the new default unless it also carries `dim=referrer`.
|
|
30
|
+
|
|
31
|
+
**Behavioral (the breakdown panel while it refetches):** a read kept on screen through a refetch answers the grouping asked for when it was issued, so switching tab or dimension used to rank the previous grouping's rows under the new column header with no labels at all. The panel now shows its skeleton until the read for the grouping on screen lands.
|
|
32
|
+
|
|
33
|
+
**Fixed:** bar-list rows are keyed by rank rather than by label. Two rows sharing a label (a provider answering an unattributed bucket as an empty string) collided, and React stranded the duplicates in the DOM across a rerender, leaving rows on screen that belonged to no read.
|
|
34
|
+
|
|
35
|
+
**Behavioral:** the `referrer` dimension groups by the referring host (lowercased, `www.` stripped) and excludes same-site referrals, so a site's own domain can never top its own referrers breakdown; the `source` dimension calls those visits `Direct`. `source` now compares the event's own hostname case-insensitively, so a `Referer` differing from the site's host only in case counts as the one self-referral rule rather than as its own bucket. Stored referrers lose their query string and fragment and are capped at 512 characters (a same-origin referrer carries the previous page's whole URL, tokens included). Geo values (`country`, `region`, `city`) are capped at 128 characters. An ingest body whose `referrer` is not a string answers `202` and drops the field instead of failing with a `500`.
|
|
36
|
+
|
|
37
|
+
**Performance:** rollup and seen-ledger writes are batched per flush, one multi-row statement each, so a fully attributed pageview costs 4 database round trips instead of 161, and a buffered batch pays those writes once for the whole batch rather than once per event. Counting is unchanged.
|
|
38
|
+
|
|
39
|
+
**Storage:** rollup and seen-ledger rows grow with the cardinality of the new dimensions (referrer host, city, `utmContent`, `utmTerm`), plus one extra bucket set per distinct hostname you ingest from. `retentionDays` prunes events and the seen ledger only, never rollups, so plan storage for that tail.
|
|
40
|
+
|
|
41
|
+
- **Additive: comparison for every source.** Period-over-period comparison used to be a capability only the native and memory adapters declared. The previous-window read is done by the engine and works the same against any source, so it is now on for every adapter unless one sets `capabilities.comparison: false`; the four providers no longer opt out, and `comparison` is optional on `AnalyticsCapabilities` for adapters of your own (the serialized form the pickers read still carries a boolean). The compare toggle, the widgets' compare checkbox and `compare=previous` on the query endpoint therefore work on Plausible, GA4, Umami and PostHog. A source with `maxLookbackDays` cannot answer a previous window that starts before its lookback, measured from today: the view hides the toggle for such a window, the widgets and display fields omit the delta, and the endpoint answers the read without `comparison` instead of failing it. A far-past absolute range on such a source is still served (the engine clamps against the read's own end) but loses its comparison.
|
|
42
|
+
|
|
43
|
+
**Additive: the filter operators each provider API supports.** Plausible applies `eq`, `contains` and `matches` on every dimension it filters by (`is`, `contains`, `matches` in its Stats API v2 grammar, re2 full match). GA4 applies the same three through `stringFilter` (`EXACT`, `CONTAINS`, `FULL_REGEXP`), with exact and regex matches case-sensitive and `contains` case-insensitive like native and Umami. Umami now targets Umami 3.x: fifteen filterable dimensions (`page`, `referrer`, `browser`, `os`, `device`, `country`, `region`, `city`, `language`, `event` and the five `utm*`) with `eq`, `contains` and `matches` written as the API's `eq.`, `c.` and `re.` value prefixes, so `contains` is a case-insensitive substring and `matches` a case-insensitive partial regex there. Regex stays provider-only; native offers `eq` and `contains`. Umami accepts one value per query parameter, so two `eq` filters on one dimension with different values answer an empty result without a request, any other collision keeps the first filter (a per-page read keeps its page), an `eq` value carrying a comma is left out entirely because Umami reads such a value as a list and offers no escape, and what was not applied is reported in a new `meta.unappliedFilters` on the result.
|
|
44
|
+
|
|
45
|
+
**Behavioral (Umami):** the page breakdown asks `/metrics?type=path`; `type=url` was the 2.x name and Umami 3.x rejects it. Umami's breakdown rows report distinct sessions, so every breakdown row now carries `visitors` rather than a number labelled with whatever metric was asked for, and the view's breakdown charts the first metric the rows do carry when the selected one is absent. `event` is filterable but no longer groupable on Umami, since the install-wide `events` metric has no source in `/stats`.
|
|
46
|
+
|
|
47
|
+
**Additive: goals and conversions on every provider.** `conversions` and the `goal` dimension are served by Plausible (`event:goal`, conversions from `events` on goal rows, revenue from `total_revenue`), GA4 (`eventName` with `keyEvents`), PostHog (`event` with `count()`) and Umami (`/metrics?type=event`). A provider does not know which of its events are this install's goals, so reads that ask about goals carry the scope's goal slugs as `AnalyticsQuery.goalSlugs`, set by the query endpoint, the widgets and the display fields, and partitioning the cache. The slug of a goal must equal the provider's own name for it: the goal's display name on Plausible, the event name on PostHog and Umami, and on GA4 the slug normalized to a valid GA4 event name (hyphens become underscores, other characters outside letters, digits and underscores are dropped, a name not starting with a letter gains an `e_` prefix, 40 characters at most), which is also the name the GA4 sink sends; that normalization is exported as `ga4EventName` from `@10x-media/analytics/adapters/ga4`, so a host that dispatches its own gtag events can send the name the adapter reads back. A goal read with no goals in scope, or whose goal request the provider rejected, keeps its site numbers and reports `meta.goalsUnresolved`. A rejected goal request is cached for the source's realtime TTL rather than its aggregate one, so a transient provider failure does not pin "no conversions" for an hour, and every goal surface (the view's goals panel and goal breakdown, the goals widget, the goals breakdown widget) renders an empty state that says the goals could not be read instead of the plain no-data one. A filter the source could not carry raises a notice of its own on the view and on the metric, trend and breakdown widgets. When conversions ride along with site metrics, Plausible and GA4 issue a second, goal-filtered request and merge it per row, so such a read costs up to two provider requests; the second one runs after the first, inside the same limiter permit. GA4's `keyEvents` counts only events the property marks as key events. Umami serves conversions as goal rows and a range total only, so a conversions trend there shows no data, and the view's trend renders its empty state rather than a flat line of zeros. The goals widget and the goals tab now register for every provider.
|
|
48
|
+
|
|
49
|
+
**Behavioral (providers):** `conversions` on a provider means completions of this install's goals, as it does on native, rather than GA4's unfiltered key-event count. An install with no goals configured reads no conversions from a provider.
|
|
50
|
+
|
|
51
|
+
**Additive: Plausible `revenueCurrency`.** Plausible's `total_revenue` requires a revenue goal, so the adapter now declares `revenue` only when `revenueCurrency` (the ISO code of the site's revenue goals) is set, in config or on the provider document, and requests it only inside a goal-filtered request. Before, any read asking for revenue sent `total_revenue` unfiltered, which the API rejects.
|
|
52
|
+
|
|
53
|
+
**Additive: GA4 capture.** Set `measurementId` on the adapter or the provider document and the GA4 source fills a capture slot: the gtag tag loads from Google's own domain (no first-party proxy; the descriptor declares no routes), `gtag('config')` sends the first page view and history-change page views come from the web data stream's enhanced measurement (on by default, and the sink does not forward pageviews so it never double counts; an install that turns that stream option off should turn it back on), and the tracker forwards events and goals with `gtag('event', name, params)`. Consent is required by default, so the tag is not in the HTML before consent and is injected by the tracker once granted. The measurement id must match `^[A-Za-z0-9-]+$`; the provider document validates it and the adapter fills no slot otherwise. The tracker's own `file_download` auto-capture overlaps with enhanced measurement's, so downloads count twice on a GA4 slot unless one side is turned off. The sink is exported as `createGa4Sink` from `@10x-media/analytics/tracker`, beside the other vendor sinks. **Behavioral:** `CaptureClientKind` gains `'ga4'`, so an exhaustive `switch` over it in consumer code needs a new arm.
|
|
54
|
+
|
|
55
|
+
**Behavioral (PostHog):** the query's time bounds are sent as `toDateTime('...', 'UTC')`. HogQL reads a bare literal in the project's timezone, so a project set to anything but UTC was reading a window shifted by its offset; buckets are still cut in the reporting timezone.
|
|
56
|
+
|
|
57
|
+
**Fixed: two attacker-keyed lookups answer through the prototype.** `extractUtm` matched a page's query keys against an object literal, so `?constructor=x` or `?__proto__=x` resolved an inherited member and wrote a key `UtmParams` does not declare into the event row. The medium table the new `source` classifier reads is keyed by `utm_medium`, which is attacker-written in the same way, and an object literal there would have put a function in the `source` column, which a Postgres batch write rejects outright. Both lookups are `Map`s now, which answer nothing for a prototype name and make the return type honest; the view's channel-label table is guarded by a type predicate for the same reason.
|
|
58
|
+
|
|
59
|
+
**Breaking (native installs): `source` is a traffic channel.** The native `source` dimension buckets each pageview into `direct`, `search`, `social`, `email`, `paid` or `referral`, classified at ingest from `utm_medium` first, then paid click ids in the query (`gclid`, `fbclid`, `msclkid`, `ttclid`), then the referrer host against a small built-in list of search engines and social networks (a brand's country sites count, `google.co.uk` and `google.de`, while a host that merely contains the brand, `google.evil.com`, does not); no referrer or a same-site referrer is `direct`, any other host `referral`. Webmail hosts (`mail.google.com` and the like) count as `referral`, since a referrer cannot prove a newsletter. The `referrer` dimension keeps the host. The six channel values are stored as lowercase tokens and rendered through typed translations in the view and the widgets, so a Sources tab reads **Search** or **Direct** in the admin's locale while filters and links carry the token; they are exported as `TRAFFIC_CHANNELS` and the `TrafficChannel` type from `@10x-media/analytics/types`. Only a native row is named that way: a provider serves `source` as a raw `utm_source`, where a row reading `email` is the campaign parameter and not the Email channel, so those rows are shown as stored. Rows ingested before the upgrade keep the host values `source` used to store, and nothing is backfilled, so a Sources tab spanning the upgrade mixes the two until the old days age out of the window.
|
|
60
|
+
|
|
61
|
+
- **Additive: widget filters.** Metric, trend and breakdown widgets take one optional filter (dimension, operator, value). The dimension is the gate, the operator defaults to `eq`, and the value is trimmed and capped at 256 characters; a dimension without a value fails validation rather than saving a filter that narrows nothing. The two pickers offer only what the widget's chosen data source declares as filterable, in contract order, falling back to the union over the request's sources when no source is chosen, and a stored value the current source no longer offers stays visible (clearable on the dimension, which is the gate; the operator always has a value). The read applies the filter, the caption states it ("Last 30 days where Country is DE"), and the "Open in Analytics" link carries it into the view as `filters=`. The caption's two halves are translated templates: the sentence is `widgetFilterCaption` (`'where {{dimension}} {{operator}} {{value}}'`) and the join that puts it after the window is its own key, `widgetCaptionWithFilter` (`'{{window}} {{filter}}'`), which `zh` ships without the space. Both are overridable through the `translations` option.
|
|
62
|
+
|
|
63
|
+
A source that cannot apply the stored filter renders "This source cannot apply this filter" rather than silently ranking unfiltered rows: `readForWidget`, `readForWidgetBreakdown` and `readForWidgetSeries` answer `status: 'filter-unsupported'` without querying the adapter. Because the pickers offer the union when no source is chosen, a dimension filterable on one source and an operator declared on another can be configured together and answered this way at read time.
|
|
64
|
+
|
|
65
|
+
**Breaking (types): `WidgetReadStatus` gains `'filter-unsupported'`.** The type is exported from `/rsc`, so an exhaustive `Record<Exclude<WidgetReadStatus, 'ok'>, T>` or a switch a consumer wrote over it stops compiling until the new member is handled. Runtime behavior of existing code is unaffected; the compiler is the thing that breaks.
|
|
66
|
+
|
|
67
|
+
**Behavioral: a widget filter that the source cannot apply now reads `filter-unsupported` where it read `unavailable` before.** Code branching on `status === 'unavailable'` to render its own "no data" message will stop matching those reads.
|
|
68
|
+
|
|
69
|
+
**Behavioral: a widget's caption renders only with the data it describes.** The breakdown widget used to render its range caption below a not-configured or unavailable message, captioning a window it had not read; it now returns title, message and link, as the metric and trend widgets already did.
|
|
70
|
+
|
|
71
|
+
**Additive API.** `widgetFilters` and the `WidgetFilter` type are exported from the root entry, so a custom widget storing the built-in filter group turns it into an `AnalyticsFilter[]` under the same rules. `FilterDimensionSelectField`, `FilterOperatorSelectField`, `useFilterCapabilities` and the `AnalyticsSources` type are exported from `/client`; `FilterCapabilities` carries `resolved` alongside `loading` and `error`, and `useAnalyticsSources` reports `loading` and `error` beside `sources`. The server `Translate` type accepts interpolation vars. 15 new translation keys ship in all 11 locales.
|
|
72
|
+
|
|
3
73
|
## 1.0.0-beta.8
|
|
4
74
|
|
|
5
75
|
### 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
|
@@ -11,11 +11,11 @@ Part of the [@10x-media Payload plugins](https://github.com/10x-media/payload-pl
|
|
|
11
11
|
## Features
|
|
12
12
|
|
|
13
13
|
- **One adapter contract** with a capabilities model; adapters ship as code-split subpaths (`@10x-media/analytics/adapters/*`) plus a `memoryAdapter` for tests.
|
|
14
|
-
- **Native engine**: self-hosted, cookieless analytics in your own database, with atomic rollups, exact daily uniques, geo resolution (platform headers or MaxMind), retention pruning, and opt-in write batching.
|
|
15
|
-
- **Capture**: a dependency-free browser tracker (`@10x-media/analytics/tracker`) with SPA pageviews, consent gating, auto-capture, and goals, booted from React (`@10x-media/analytics/react`) or a server component; capture-capable adapters are served through a first-party proxy so a vendor's SDK loads from your own origin.
|
|
14
|
+
- **Native engine**: self-hosted, cookieless analytics in your own database, with atomic rollups, exact daily uniques, geo resolution (platform headers or MaxMind), retention pruning, and opt-in write batching. It classifies the traffic channel (direct, search, social, email, paid, referral), referrer host, browser, OS, language and the five UTM keys at ingest, so it serves and filters every breakdown dimension the widgets offer except `goal`, which it groups but cannot filter. The view's `medium` and `campaign` groupings are the two it does not serve.
|
|
15
|
+
- **Capture**: a dependency-free browser tracker (`@10x-media/analytics/tracker`) with SPA pageviews, consent gating, auto-capture, and goals, booted from React (`@10x-media/analytics/react`) or a server component; capture-capable adapters are served through a first-party proxy so a vendor's SDK loads from your own origin, GA4 excepted, whose tag Google serves itself.
|
|
16
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
17
|
- **Analytics view** at `/admin/analytics`: overview cards, a trend, capability-gated breakdown tabs with click-to-filter, goals and realtime, with range, source, metric, tab and filters in the URL so a report is a shareable link.
|
|
18
|
-
- **Dashboard widgets** for Payload's Modular Dashboard: metric, trend (with an optional previous-period overlay), goals, ten breakdowns, and realtime, each capability-gated, each linking into the analytics view, plus a public API for custom widgets.
|
|
18
|
+
- **Dashboard widgets** for Payload's Modular Dashboard: metric, trend (with an optional previous-period overlay), goals, ten breakdowns, and realtime, each capability-gated, each linking into the analytics view, plus a public API for custom widgets. Metric, trend and breakdown widgets take one optional filter, narrowed to what the chosen source can apply, stated in the caption and carried into the view.
|
|
19
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
20
|
- **Query endpoint**: an authenticated `GET /api/analytics/query` over any configured source, capability-validated and scope-gated, with coded errors and a `fetchQuery` helper for admin code.
|
|
21
21
|
- **Caching** through `payload.kv` with request coalescing, plus an opt-in scheduled warm job.
|
|
@@ -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
|
package/dist/adapters/ga4/ga4.js
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
import { zonedCalendarDay } from "../../timeframe/tz.js";
|
|
2
|
+
import { MEASUREMENT_ID_PATTERN } from "./measurementId.js";
|
|
3
|
+
import { emptyGoalBreakdown, goalHint, hintSlugs, mergeGoalRows, mergeGoalTotals, providerMetricKeys, readGoalPair, splitGoalMetrics } from "../goalRead.js";
|
|
2
4
|
import { dayIso } from "../series.js";
|
|
5
|
+
import { ga4EventName } from "./eventName.js";
|
|
3
6
|
//#region src/adapters/ga4/ga4.ts
|
|
7
|
+
/**
|
|
8
|
+
* Google's documented install snippet (https://developers.google.com/tag-platform/gtagjs/install):
|
|
9
|
+
* the inline publishes `dataLayer` and `gtag` and configures the measurement id, then the tag
|
|
10
|
+
* loads from googletagmanager.com. Inline first is Google's own ordering for consent mode, and
|
|
11
|
+
* it leaves the queue defined even when the tag itself is blocked. The tag is served from
|
|
12
|
+
* Google's CDN with the id in the query string, so there is nothing to proxy and `routes`
|
|
13
|
+
* stays empty; the snippet is rendered from an absolute `src` and the slot's proxy mount
|
|
14
|
+
* answers 404.
|
|
15
|
+
*/
|
|
16
|
+
function buildCapture(measurementId) {
|
|
17
|
+
const id = JSON.stringify(measurementId);
|
|
18
|
+
return {
|
|
19
|
+
proxy: { routes: [] },
|
|
20
|
+
snippet: () => ({ scripts: [{ inline: `window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments)}gtag("js",new Date());gtag("config",${id})` }, {
|
|
21
|
+
src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(measurementId)}`,
|
|
22
|
+
async: true
|
|
23
|
+
}] }),
|
|
24
|
+
client: {
|
|
25
|
+
kind: "ga4",
|
|
26
|
+
measurementId
|
|
27
|
+
}
|
|
28
|
+
};
|
|
29
|
+
}
|
|
4
30
|
const METRIC_MAP = {
|
|
5
31
|
pageviews: "screenPageViews",
|
|
6
32
|
visitors: "totalUsers",
|
|
@@ -28,10 +54,54 @@ const DIMENSION_MAP = {
|
|
|
28
54
|
region: "region",
|
|
29
55
|
city: "city",
|
|
30
56
|
language: "language",
|
|
31
|
-
event: "eventName"
|
|
57
|
+
event: "eventName",
|
|
58
|
+
goal: "eventName"
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Metrics GA4 answers only for a goal-restricted read. A goal matches the GA4 event named by
|
|
62
|
+
* its normalized slug, since GA4 refuses the kebab-case slug itself. `keyEvents` counts
|
|
63
|
+
* events the property itself marks as key events, so an event that is a goal here but not
|
|
64
|
+
* marked there reports 0.
|
|
65
|
+
*/
|
|
66
|
+
const GOAL_METRICS = new Set(["conversions"]);
|
|
67
|
+
/**
|
|
68
|
+
* The hint's slugs keyed by the GA4 event name each one normalizes to, which is both the
|
|
69
|
+
* `eventName` list the goal request sends and the way its rows map back. Two slugs can
|
|
70
|
+
* normalize to one GA4 event, which GA4 counts once: the first hint slug owns those rows.
|
|
71
|
+
*/
|
|
72
|
+
const goalSlugsByEventName = (slugs) => {
|
|
73
|
+
const byName = /* @__PURE__ */ new Map();
|
|
74
|
+
for (const slug of slugs) {
|
|
75
|
+
const name = ga4EventName(slug);
|
|
76
|
+
if (!byName.has(name)) byName.set(name, slug);
|
|
77
|
+
}
|
|
78
|
+
return byName;
|
|
79
|
+
};
|
|
80
|
+
/**
|
|
81
|
+
* FULL_REGEXP is a full match, so a pattern has to cover the whole value (`/docs/.*`, not
|
|
82
|
+
* `^/docs`). PARTIAL_REGEXP exists but is not the contract's `matches`.
|
|
83
|
+
*/
|
|
84
|
+
const MATCH_TYPE_MAP = {
|
|
85
|
+
eq: "EXACT",
|
|
86
|
+
contains: "CONTAINS",
|
|
87
|
+
matches: "FULL_REGEXP"
|
|
32
88
|
};
|
|
89
|
+
const CASE_SENSITIVE = {
|
|
90
|
+
EXACT: true,
|
|
91
|
+
CONTAINS: false,
|
|
92
|
+
FULL_REGEXP: true
|
|
93
|
+
};
|
|
94
|
+
const stringFilter = (fieldName, matchType, value) => ({ filter: {
|
|
95
|
+
fieldName,
|
|
96
|
+
stringFilter: {
|
|
97
|
+
matchType,
|
|
98
|
+
value,
|
|
99
|
+
caseSensitive: CASE_SENSITIVE[matchType]
|
|
100
|
+
}
|
|
101
|
+
} });
|
|
33
102
|
const ga4Metrics = new Set(Object.keys(METRIC_MAP));
|
|
34
103
|
const ga4Dimensions = new Set(Object.keys(DIMENSION_MAP));
|
|
104
|
+
const ga4Filters = new Set([...ga4Dimensions].filter((dimension) => dimension !== "goal"));
|
|
35
105
|
const toContractValue = (metric, raw) => {
|
|
36
106
|
if (metric === "avgDuration") return Math.round(raw * 1e3);
|
|
37
107
|
if (metric === "bounceRate") return Math.round(raw * 100);
|
|
@@ -41,13 +111,16 @@ function ga4(config) {
|
|
|
41
111
|
const capabilities = {
|
|
42
112
|
perPageQuery: true,
|
|
43
113
|
realtime: false,
|
|
44
|
-
comparison: false,
|
|
45
114
|
minGranularity: "day",
|
|
46
115
|
maxLookbackDays: config.maxLookbackDays !== void 0 ? config.maxLookbackDays : 425,
|
|
47
116
|
metrics: ga4Metrics,
|
|
48
117
|
dimensions: ga4Dimensions,
|
|
49
|
-
filters:
|
|
50
|
-
filterOperators: new Set([
|
|
118
|
+
filters: ga4Filters,
|
|
119
|
+
filterOperators: new Set([
|
|
120
|
+
"eq",
|
|
121
|
+
"contains",
|
|
122
|
+
"matches"
|
|
123
|
+
]),
|
|
51
124
|
batchPageReport: true,
|
|
52
125
|
rateLimit: {
|
|
53
126
|
maxConcurrent: 10,
|
|
@@ -75,122 +148,157 @@ function ga4(config) {
|
|
|
75
148
|
})();
|
|
76
149
|
return clientPromise;
|
|
77
150
|
};
|
|
151
|
+
const measurementId = config.measurementId;
|
|
78
152
|
return {
|
|
79
153
|
id: "ga4",
|
|
80
154
|
label: "Google Analytics 4",
|
|
81
155
|
capabilities,
|
|
156
|
+
...measurementId && MEASUREMENT_ID_PATTERN.test(measurementId) ? { capture: buildCapture(measurementId) } : {},
|
|
82
157
|
isConfigured: () => Boolean(config.propertyId && config.credentials?.client_email && config.credentials?.private_key),
|
|
83
158
|
async query(q, _ctx) {
|
|
84
159
|
const fetchedAt = q.dateRange.end.toISOString();
|
|
85
|
-
const wanted = q.metrics.filter((m) => METRIC_MAP[m]);
|
|
86
|
-
const providerMetrics = [...new Set(wanted.map((m) => METRIC_MAP[m]))];
|
|
87
160
|
const dims = (q.dimensions ?? []).filter((d) => DIMENSION_MAP[d]);
|
|
161
|
+
const goalBreakdown = dims.includes("goal");
|
|
162
|
+
const hint = goalHint(q);
|
|
163
|
+
const slugs = hintSlugs(hint);
|
|
164
|
+
const empty = goalBreakdown ? emptyGoalBreakdown({
|
|
165
|
+
provider: "ga4",
|
|
166
|
+
q,
|
|
167
|
+
hint
|
|
168
|
+
}) : null;
|
|
169
|
+
if (empty) return empty;
|
|
170
|
+
const { siteMetrics, goalMetrics, unresolved } = splitGoalMetrics({
|
|
171
|
+
wanted: q.metrics.filter((m) => METRIC_MAP[m]),
|
|
172
|
+
goalOnly: GOAL_METRICS,
|
|
173
|
+
goalBreakdown,
|
|
174
|
+
hint
|
|
175
|
+
});
|
|
176
|
+
const siteKeys = providerMetricKeys(siteMetrics, METRIC_MAP);
|
|
177
|
+
const goalKeys = providerMetricKeys(goalMetrics, METRIC_MAP);
|
|
88
178
|
const providerDims = [...new Set(dims.map((d) => DIMENSION_MAP[d]))];
|
|
89
|
-
|
|
179
|
+
let goalsFailed = false;
|
|
180
|
+
const meta = () => ({
|
|
181
|
+
provider: "ga4",
|
|
182
|
+
fetchedAt,
|
|
183
|
+
...unresolved || goalsFailed ? { goalsUnresolved: true } : {}
|
|
184
|
+
});
|
|
185
|
+
const readMetrics = (ms, keys, row) => {
|
|
90
186
|
const out = {};
|
|
91
|
-
for (const m of
|
|
92
|
-
const idx =
|
|
187
|
+
for (const m of ms) {
|
|
188
|
+
const idx = keys.indexOf(METRIC_MAP[m]);
|
|
93
189
|
out[m] = toContractValue(m, Number(row.metricValues?.[idx]?.value ?? 0));
|
|
94
190
|
}
|
|
95
191
|
return out;
|
|
96
192
|
};
|
|
97
193
|
const filterExprs = [];
|
|
98
|
-
if (q.path) filterExprs.push(
|
|
99
|
-
|
|
100
|
-
stringFilter: {
|
|
101
|
-
matchType: "EXACT",
|
|
102
|
-
value: q.path
|
|
103
|
-
}
|
|
104
|
-
} });
|
|
105
|
-
if (q.hostname) filterExprs.push({ filter: {
|
|
106
|
-
fieldName: "hostName",
|
|
107
|
-
stringFilter: {
|
|
108
|
-
matchType: "EXACT",
|
|
109
|
-
value: q.hostname
|
|
110
|
-
}
|
|
111
|
-
} });
|
|
194
|
+
if (q.path) filterExprs.push(stringFilter("pagePath", "EXACT", q.path));
|
|
195
|
+
if (q.hostname) filterExprs.push(stringFilter("hostName", "EXACT", q.hostname));
|
|
112
196
|
for (const filter of q.filters ?? []) {
|
|
113
|
-
const fieldName = DIMENSION_MAP[filter.dimension];
|
|
114
|
-
if (!fieldName
|
|
115
|
-
filterExprs.push(
|
|
116
|
-
fieldName,
|
|
117
|
-
stringFilter: {
|
|
118
|
-
matchType: "EXACT",
|
|
119
|
-
value: filter.value
|
|
120
|
-
}
|
|
121
|
-
} });
|
|
197
|
+
const fieldName = ga4Filters.has(filter.dimension) ? DIMENSION_MAP[filter.dimension] : void 0;
|
|
198
|
+
if (!fieldName) continue;
|
|
199
|
+
filterExprs.push(stringFilter(fieldName, MATCH_TYPE_MAP[filter.operator], filter.value));
|
|
122
200
|
}
|
|
123
|
-
const
|
|
124
|
-
const
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
}
|
|
130
|
-
|
|
131
|
-
|
|
201
|
+
const goalSlugs = slugs ? goalSlugsByEventName(slugs) : null;
|
|
202
|
+
const goalExprs = goalSlugs ? [...filterExprs, { filter: {
|
|
203
|
+
fieldName: "eventName",
|
|
204
|
+
inListFilter: {
|
|
205
|
+
values: [...goalSlugs.keys()],
|
|
206
|
+
caseSensitive: true
|
|
207
|
+
}
|
|
208
|
+
} }] : filterExprs;
|
|
209
|
+
const asFilter = (exprs) => exprs.length === 0 ? void 0 : exprs.length === 1 ? exprs[0] : { andGroup: { expressions: exprs } };
|
|
210
|
+
const request = (metrics, exprs, extra) => {
|
|
211
|
+
const dimensionFilter = asFilter(exprs);
|
|
212
|
+
return {
|
|
213
|
+
property: `properties/${config.propertyId}`,
|
|
214
|
+
dateRanges: [{
|
|
215
|
+
startDate: zonedCalendarDay(q.dateRange.start, q.timezone ?? "UTC"),
|
|
216
|
+
endDate: zonedCalendarDay(q.dateRange.end, q.timezone ?? "UTC")
|
|
217
|
+
}],
|
|
218
|
+
metrics: metrics.map((name) => ({ name })),
|
|
219
|
+
...dimensionFilter ? { dimensionFilter } : {},
|
|
220
|
+
...extra
|
|
221
|
+
};
|
|
132
222
|
};
|
|
133
223
|
const client = await getClient();
|
|
224
|
+
const rowKeys = (row) => (row.dimensionValues ?? []).map((value) => value.value ?? "");
|
|
225
|
+
/**
|
|
226
|
+
* One report shape run twice, plainly and goal-filtered, unioned per row. A row the
|
|
227
|
+
* goal report has no counterpart for carries no conversions: no key event fired there.
|
|
228
|
+
* `limit` is the site report's alone, since a goal ranked outside its top N would
|
|
229
|
+
* otherwise be lost from the union.
|
|
230
|
+
*/
|
|
231
|
+
const runPair = async (extra, limit) => {
|
|
232
|
+
const runReport = async (metrics, exprs, reportExtra) => {
|
|
233
|
+
const [response] = await client.runReport(request(metrics, exprs, reportExtra));
|
|
234
|
+
return response;
|
|
235
|
+
};
|
|
236
|
+
const siteExprs = goalBreakdown ? goalExprs : filterExprs;
|
|
237
|
+
const siteExtra = limit ? {
|
|
238
|
+
...extra,
|
|
239
|
+
limit
|
|
240
|
+
} : extra;
|
|
241
|
+
const pair = await readGoalPair({
|
|
242
|
+
site: siteKeys.length ? () => runReport(siteKeys, siteExprs, siteExtra) : void 0,
|
|
243
|
+
goals: goalKeys.length ? () => runReport(goalKeys, goalExprs, extra) : void 0
|
|
244
|
+
});
|
|
245
|
+
if (pair.failed) goalsFailed = true;
|
|
246
|
+
const keyed = (response, ms, keys) => response?.rows?.map((row) => ({
|
|
247
|
+
keys: rowKeys(row),
|
|
248
|
+
metrics: readMetrics(ms, keys, row)
|
|
249
|
+
})) ?? (response ? [] : void 0);
|
|
250
|
+
const siteTotals = pair.site?.totals?.[0];
|
|
251
|
+
const goalTotals = pair.goals?.totals?.[0];
|
|
252
|
+
return {
|
|
253
|
+
rows: mergeGoalRows(keyed(pair.site, siteMetrics, siteKeys), keyed(pair.goals, goalMetrics, goalKeys)),
|
|
254
|
+
totals: mergeGoalTotals(siteTotals ? readMetrics(siteMetrics, siteKeys, siteTotals) : void 0, goalTotals ? readMetrics(goalMetrics, goalKeys, goalTotals) : void 0)
|
|
255
|
+
};
|
|
256
|
+
};
|
|
134
257
|
if (q.granularity === "day" && !dims.length) {
|
|
135
|
-
const
|
|
136
|
-
...baseRequest,
|
|
258
|
+
const report = await runPair({
|
|
137
259
|
dimensions: [{ name: "date" }],
|
|
138
260
|
metricAggregations: ["TOTAL"],
|
|
139
261
|
orderBys: [{ dimension: { dimensionName: "date" } }]
|
|
140
262
|
});
|
|
141
263
|
const rows = [];
|
|
142
|
-
for (const row of
|
|
143
|
-
const ymd = row.
|
|
264
|
+
for (const row of report.rows) {
|
|
265
|
+
const ymd = row.keys[0] ?? "";
|
|
144
266
|
const ts = dayIso(`${ymd.slice(0, 4)}-${ymd.slice(4, 6)}-${ymd.slice(6, 8)}`);
|
|
145
267
|
if (ts) rows.push({
|
|
146
268
|
timestamp: ts,
|
|
147
|
-
metrics:
|
|
269
|
+
metrics: row.metrics
|
|
148
270
|
});
|
|
149
271
|
}
|
|
150
|
-
const totalsRow = response.totals?.[0];
|
|
151
272
|
return {
|
|
152
273
|
rows,
|
|
153
|
-
totals:
|
|
154
|
-
meta:
|
|
155
|
-
provider: "ga4",
|
|
156
|
-
fetchedAt
|
|
157
|
-
}
|
|
274
|
+
totals: report.totals ?? {},
|
|
275
|
+
meta: meta()
|
|
158
276
|
};
|
|
159
277
|
}
|
|
160
|
-
const
|
|
161
|
-
...baseRequest,
|
|
162
|
-
...providerDims.length ? { dimensions: providerDims.map((name) => ({ name })) } : {},
|
|
163
|
-
...q.limit ? { limit: q.limit } : {}
|
|
164
|
-
});
|
|
278
|
+
const report = await runPair(providerDims.length ? { dimensions: providerDims.map((name) => ({ name })) } : {}, q.limit);
|
|
165
279
|
if (!dims.length) {
|
|
166
|
-
const
|
|
167
|
-
const totals = row ? readRow(row) : {};
|
|
280
|
+
const totals = report.rows[0]?.metrics ?? {};
|
|
168
281
|
return {
|
|
169
282
|
rows: [{ metrics: totals }],
|
|
170
283
|
totals,
|
|
171
|
-
meta:
|
|
172
|
-
provider: "ga4",
|
|
173
|
-
fetchedAt
|
|
174
|
-
}
|
|
284
|
+
meta: meta()
|
|
175
285
|
};
|
|
176
286
|
}
|
|
177
287
|
return {
|
|
178
|
-
rows:
|
|
288
|
+
rows: report.rows.map((row) => {
|
|
179
289
|
const dimValues = {};
|
|
180
290
|
for (const d of dims) {
|
|
181
291
|
const idx = providerDims.indexOf(DIMENSION_MAP[d]);
|
|
182
|
-
|
|
292
|
+
const value = row.keys[idx] ?? "";
|
|
293
|
+
dimValues[d] = d === "goal" ? goalSlugs?.get(value) ?? value : value;
|
|
183
294
|
}
|
|
184
295
|
return {
|
|
185
296
|
dimensions: dimValues,
|
|
186
|
-
metrics:
|
|
297
|
+
metrics: row.metrics
|
|
187
298
|
};
|
|
188
299
|
}),
|
|
189
300
|
totals: void 0,
|
|
190
|
-
meta:
|
|
191
|
-
provider: "ga4",
|
|
192
|
-
fetchedAt
|
|
193
|
-
}
|
|
301
|
+
meta: meta()
|
|
194
302
|
};
|
|
195
303
|
}
|
|
196
304
|
};
|