Standardise custom dimension creation across the Key Metrics, Audience Segmentation and Site Goals notices
- Dominant language
- JavaScript
- Stars
- 1.4k
- Forks
- 383
- Avg merge
- 4d 12h
- Merged PRs (30d)
- 80
Description
## Feature Description
Site Kit asks the user to create Analytics custom dimensions from three separate places, and each of them creates a different subset today:
* **Key Metrics** — the metrics selection panel notice and the per-tile "Update" CTA create only the dimensions required by the metric tiles the user has selected, i.e. some of `googlesitekit_post_date`, `googlesitekit_post_author`, `googlesitekit_post_categories` and `googlesitekit_post_type`.
* **Audience Segmentation** — the "Top content" tile CTA creates only `googlesitekit_post_type`, and it bypasses the shared `createCustomDimensions` action entirely, calling `fetchCreateCustomDimension` directly.
* **Site Goals** — the "Get breakdown" CTA already creates every dimension in `CUSTOM_DIMENSION_DEFINITIONS`.
The result is that accepting one notice does not clear the others: a user who enables the Audience Segmentation top content metric is still shown the Key Metrics notice when they select an author or category tile, and is still shown the Site Goals breakdown CTA. Each acceptance costs a round trip to the Analytics Admin API and, when the user lacks the Analytics edit scope, a separate OAuth redirect. All three notices should therefore create the same complete set of custom dimensions.
Auto-enabling the **Plugin Conversion Tracking** setting is deliberately *not* standardised alongside this. It is only genuinely required for the Site Goals breakdown and should only be enabled from the "Enable breakdown CTA" as before.
If Plugin Conversion Tracking is already enabled AND Site Kit's custom dimensions have been created from the actioning of a CTA from either Key Metrics or Audience Segmentation, then there is no need to show the "Enable Breakdown CTA" and breakdown should already be enabled once both these conditions are met. If any or both of the above conditions aren't met, then the appropriate version of the Enable Breakdown CTA will continue to display.
Design doc: [[SK] Site Goals Enhancements - Mini Design Doc – "Standardise Custom Dimensions creation across all notices"](https://docs.google.com/document/d/1Sg_FySdYMAj1cO43OCyMin0YoAveB3zsndLQa8HiW80/edit?tab=t.0#heading=h.d7zj1ai7wswh)
Related: #13398 (auto-enabling Plugin Conversion Tracking from the Site Goals breakdown CTA only).
---------------
_Do not alter or remove anything below. The following sections will be managed by moderators only._
## Acceptance criteria
* Accepting any of the three "Site Kit requires custom dimensions" CTAs creates **every** dimension defined in `CUSTOM_DIMENSION_DEFINITIONS` on the selected Analytics property, not just the subset that the notice in question needs:
* [the Key Metrics metrics selection panel notice, on save; ](https://storage.googleapis.com/site-kit-github-artifacts/storybook/develop/index.html?path=/story/key-metrics-metricsselectionpanel--default)
* [the Key Metrics per-tile "Update" CTA;](https://storage.googleapis.com/site-kit-github-artifacts/storybook/develop/index.html?path=/story/key-metrics-topcategorieswidget--error-missing-custom-dimensions)
* [the Audience Segmentation "Top content" tile CTA; ](https://storage.googleapis.com/site-kit-github-artifacts/storybook/develop/index.html?path=/story/modules-analytics4-components-audiencesegmentation-dashboard-audiencetile--missing-custom-dimension)
* [the Site Goals "Get breakdown" CTA](https://www.figma.com/design/S2CNc1toIzC7UrGMgs79S6/Site-Goals?node-id=8009-24920&m=dev) (already the case; behaviour must not regress);
* [the "Enable" button in the Analytics settings advanced data breakdowns section](https://www.figma.com/design/S2CNc1toIzC7UrGMgs79S6/Site-Goals?node-id=6115-22502&m=dev) (already the case; behaviour must not regress).
* Dimensions that already exist are not recreated, and a CTA with nothing left to create still completes.
* After accepting any one CTA, none of the other custom dimension notices are shown.
* The Key Metrics and Audience Segmentation CTAs leave Plugin Conversion Tracking unchanged.
* The Site Goals breakdown state is automatically enabled without the "Get breakdown" notice if the breakdown custom dimensions exist **and** Plugin Conversion Tracking is enabled.
* While either is missing, the appropriate notice or variant added in #13398 is shown and its CTA informs the user of the missing part. A site that gained the dimensions from another CTA but has conversion tracking off keeps seeing the notice.
## Implementation Brief
* [ ] Update `assets/js/modules/analytics-4/datastore/constants.ts`
* Rename `SITE_GOALS_CUSTOM_DIMENSIONS` to `ALL_CUSTOM_DIMENSIONS`, keeping its `Object.keys( CUSTOM_DIMENSION_DEFINITIONS )` definition. The name is already misleading — it holds every dimension, not the Site Goals subset — and it becomes the single list every CTA creates.
* Update its three call sites (`custom-dimensions.js`, `SettingsAdvancedDataBreakdowns.tsx`, `SettingsAdvancedDataBreakdowns.test.tsx`).
* [ ] Update `assets/js/modules/analytics-4/datastore/custom-dimensions.js`
* In `createCustomDimensions`, replace the required-dimension computation with `ALL_CUSTOM_DIMENSIONS`: drop the `KEY_METRICS_WIDGETS` lookup over `getKeyMetrics()`, the deduplication, and the `isAdvancedDataBreakdownsEnabled` gate that currently decides whether the Site Goals dimensions are included.
* Drop the now-unused `customDimensions` parameter and the `getKeyMetricsSettings`, `getUserInputSettings` and `getAdvancedDataBreakdownsSettings` awaits at the top of the action, keeping only the `getSettings` await needed for `getPropertyID()`.
* Leave the rest of the action as is: the `getCustomDimensions( propertyID )` read, the missing-dimension filter, the `receiveIsCustomDimensionGatheringData` call per created dimension, and the `fetchSyncAvailableCustomDimensions` at the end.
* Add an `@since n.e.x.t` line to the docblock recording that the action now always creates every Site Kit custom dimension.
* [ ] Update the call sites that passed an explicit list to `createCustomDimensions`, so they call it with no arguments:
* `assets/js/modules/analytics-4/hooks/useBreakdownEnableHandler.ts` — remove the local `ALL_CUSTOM_DIMENSIONS` constant and import the shared one from the datastore constants for its `inProgress` selector and its `FORM_CUSTOM_DIMENSIONS_CREATE` form value.
* `assets/js/modules/analytics-4/components/site-goals/goal-drivers/TopAuthorsGoalDriver.tsx` — keep `TOP_AUTHORS_REQUIRED_CUSTOM_DIMENSIONS` for the "which dimension am I waiting on" selectors, but stop passing it to `createCustomDimensions`.
* `assets/js/modules/analytics-4/components/site-goals/selection-panel/CustomDimensionsNotice.tsx` — same: `requiredCustomDimensions` still drives `hasCustomDimensions` and the busy state, but not the creation call.
* `assets/js/modules/analytics-4/hooks/useCreateCustomDimensionsEffect.js` — keep reading the `customDimensions` form value as the `hasExplicitCustomDimensions` gate for the OAuth-return auto-submit, but call `createCustomDimensions()` without it.
* [ ] Update `assets/js/modules/analytics-4/hooks/useCreateCustomDimensionForAudienceEffect.js`
* Replace the `fetchCreateCustomDimension( propertyID, CUSTOM_DIMENSION_DEFINITIONS.googlesitekit_post_type )`, `receiveIsCustomDimensionGatheringData` and `fetchSyncAvailableCustomDimensions` sequence with a single `await createCustomDimensions()`; the action already does all three for each missing dimension.
* `propertyID` is no longer read here, since the action resolves it itself.
* [ ] Update `assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/hooks/useCreateCustomDimension.ts`
* Make `isCreatingCustomDimension` true while **any** dimension in `ALL_CUSTOM_DIMENSIONS` is being created, instead of only `googlesitekit_post_type`.
* In `onCancel`, clear the `createCustomDimension` action error for every dimension in `ALL_CUSTOM_DIMENSIONS`, not only `googlesitekit_post_type`.
* [ ] Update `assets/js/modules/analytics-4/components/audience-segmentation/dashboard/CustomDimensionErrorModal.tsx`
* Pass the errors for all of `ALL_CUSTOM_DIMENSIONS` to `AudienceErrorModal`'s `apiErrors`, filtered to those that are set, rather than the single `googlesitekit_post_type` error.
* [ ] Update `assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTile/AudienceTilePagesMetric.js`
* `hasMissingCustomDimension` keeps checking `googlesitekit_post_type` only — that is the dimension this tile reports on — but `customDimensionError`, which drives `shouldShowErrorModal`, should be true for a failure on any of `ALL_CUSTOM_DIMENSIONS`.
* [ ] Gate the Site Goals breakdown on the saved setting, not on dimension existence:
* `assets/js/modules/analytics-4/components/site-goals/hooks/useSiteGoalsBreakdown.tsx` — require `isAdvancedDataBreakdownsEnabled( propertyID ) === true` alongside the existing `hasCustomDimensions( breakdownDimension )` check, and update the comment above it, which currently states that creating the dimension is what turns the breakdown on.
* `assets/js/modules/analytics-4/components/site-goals/notifications/BreakdownNoticeArea.tsx` — apply the same condition in `computeNoticeState` where it swaps the CTA for the breakdown, so the notice and the widget stay in sync.
* `assets/js/modules/analytics-4/components/site-goals/components/GatheringBreakdownDataBadge.tsx`, `assets/js/modules/analytics-4/components/site-goals/hooks/useSiteGoalsWidgetViewAction.tsx` and `assets/js/modules/analytics-4/components/site-goals/SiteGoalsSurveyTriggers.tsx` — same condition, so the badge, the view event and the survey trigger do not fire for a breakdown that is not rendered.
* Return the existing "not yet loaded" state while `isAdvancedDataBreakdownsEnabled` reads `undefined`, so the widget does not flash the aggregated state before the setting resolves.
* [ ] Update `assets/js/modules/analytics-4/hooks/useBreakdownEnableHandler.ts`
* In `onEnable`, dispatch `setAdvancedDataBreakdownsEnabled( { [ propertyID ]: true } )` and `await saveAdvancedDataBreakdownsSettings()` before `createCustomDimensions()`, matching `enableAndCreate` in `SettingsAdvancedDataBreakdowns.tsx`.
* Return early without creating dimensions when that save reports an error, and clear the form keys so the CTA returns for a retry, as the existing error path does.
* On the no-edit-scope path, do the save before setting `autoSubmit` and redirecting, so the setting is already persisted when the user returns from OAuth.
* [ ] Add the backfill for sites that already have the breakdown dimensions, in `includes/Modules/Analytics_4.php`
* On plugin upgrade, where `availableCustomDimensions` in the Analytics settings contains `googlesitekit_event_provider` or `googlesitekit_form_id` and the saved property has no entry in `Advanced_Data_Breakdowns_Settings`, set that property's flag to `true`.
* Follow the existing upgrade hook pattern in the module; the backfill runs once and is a no-op for every other site.
### Test Coverage
* Extend `assets/js/modules/analytics-4/datastore/custom-dimensions.test.js`:
* `createCustomDimensions` creates every dimension in `ALL_CUSTOM_DIMENSIONS` for a property that has none, regardless of which key metric tiles are selected and regardless of the advanced data breakdowns setting.
* It creates only the missing ones for a property that already has some, and only syncs when they all exist.
* Remove or rewrite the existing assertions that cover the key-metrics-derived list and the advanced data breakdowns gate.
* Add `assets/js/modules/analytics-4/hooks/useCreateCustomDimensionForAudienceEffect.test.js` (no test file exists today):
* With `autoSubmit` set, the edit scope granted and Analytics connected, all of Site Kit's custom dimensions are created, not only `googlesitekit_post_type`.
* Plugin conversion tracking is untouched.
* The form's `autoSubmit` and `isAutoCreatingCustomDimensionsForAudience` values are cleared once creation settles, including when creation fails.
* Extend `assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/hooks/useCreateCustomDimension.test.ts`:
* `isSaving` is true while any of the dimensions is being created.
* `onCancel` clears the action error for every dimension.
* Extend `assets/js/components/KeyMetrics/MetricsSelectionPanel/index.test.js`:
* Saving a selection that requires one dimension creates all of them.
* Plugin conversion tracking is untouched.
* The Site Goals breakdown does not become enabled as a result — the advanced data breakdowns setting stays off.
* Extend `assets/js/modules/analytics-4/utils/withCustomDimensions.test.js` to cover the per-tile CTA creating the full set.
* Extend `assets/js/modules/analytics-4/hooks/useBreakdownEnableHandler.test.ts`:
* `onEnable` saves the advanced data breakdowns setting for the selected property before creating the dimensions, with and without the edit scope.
* A failed save creates no dimensions and clears the form keys.
* Extend `assets/js/modules/analytics-4/components/site-goals/hooks/useSiteGoalsBreakdown.test.tsx` and `assets/js/modules/analytics-4/components/site-goals/notifications/BreakdownNoticeArea.test.tsx`:
* The breakdown stays off for a property that has the breakdown dimensions but no saved advanced data breakdowns flag.
* The breakdown renders when both the flag and the dimensions are present.
* Neither renders a state while the setting is still loading.
* Add a PHPUnit case in `tests/phpunit/integration/Modules/Analytics_4Test.php` for the upgrade backfill: a site with the breakdown dimensions in `availableCustomDimensions` and no advanced data breakdowns entry ends up with the flag set for its saved property; a site without them is left untouched.
* Update the other tests that render `BreakdownNoticeArea`, the Site Goals widgets or the Audience Segmentation top content tile to provide the advanced data breakdowns settings in their setup.
* Update any failing VRT.
## QA Brief
## Changelog entry
*
Contributor guide
Assessment
This issue has not been assessed yet.