Standardise custom dimension creation across the Key Metrics, Audience Segmentation and Site Goals notices #13552

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"

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 required by Site Kit on the selected Analytics property, not just the subset that the notice in question needs:
  • the Key Metrics metrics selection panel notice, on save;
  • the Key Metrics per-tile "Update" CTA;
  • the Audience Segmentation "Top content" tile CTA;
  • the Site Goals "Get breakdown" CTA (already the case; behaviour must not regress);
  • the "Enable" button in the Analytics settings advanced data breakdowns section (already the case; behaviour must not regress).
• Dimensions that already exist are not recreated, and a CTA with nothing left to create should still complete without error.
• 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 Enable Plugin Conversion Tracking from the Site Goals breakdown CTA with a disclosure variant of the notice #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.
  • Note that this removes the last behavioural consumer of the per-property advancedDataBreakdowns flag — SettingsAdvancedDataBreakdowns only reads hasAllCustomDimensions for its display state. Leave the setting in place here; retiring it is a separate clean-up.
• 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.
• Require plugin conversion tracking alongside the breakdown dimension, wherever the breakdown's on/off state is derived. Each of these currently checks hasCustomDimensions( breakdownDimension ) on its own and should also require isConversionTrackingEnabled() from CORE_SITE:
  • assets/js/modules/analytics-4/components/site-goals/hooks/useSiteGoalsBreakdown.tsx — and update the comment above hasBreakdownDimension, which currently states that creating the dimension is what turns the breakdown on.
  • assets/js/modules/analytics-4/components/site-goals/notifications/BreakdownNoticeArea.tsx — fold the condition into hasBreakdownDimensions / getBreakdownDimensionState so the notice and the widget stay in sync. Enable Plugin Conversion Tracking from the Site Goals breakdown CTA with a disclosure variant of the notice #13398 already reads isConversionTrackingEnabled in this component to pick the notice variant, so the two should land on one shared selector rather than two reads.
  • 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 — so the badge, the view event and the survey trigger do not fire for a breakdown that is not rendered.
  • Hold the existing "not yet loaded" state while isConversionTrackingEnabled() reads undefined, so the widget does not flash the aggregated state before the setting resolves.
  • A shared hook or selector is worth extracting here, since five call sites need the same pair of conditions.

Test Coverage

• datastore/custom-dimensions.test.js — createCustomDimensions creates every dimension whatever the selected metric tiles and the advanced data breakdowns setting, and creates only the missing ones when some already exist. Rewrite the existing assertions for the key-metrics-derived list and the breakdowns gate.
• hooks/useCreateCustomDimensionForAudienceEffect.test.ts (new file) — the Audience Segmentation CTA creates every dimension, leaves plugin conversion tracking off, and clears its form values once creation settles, including on failure.
• AudienceTilesWidget/hooks/useCreateCustomDimension.test.ts — isSaving covers any dimension being created, and onCancel clears the error for every dimension.
• KeyMetrics/MetricsSelectionPanel/index.test.js and utils/withCustomDimensions.test.js — both Key Metrics CTAs create every dimension and leave plugin conversion tracking unchanged.
• useSiteGoalsBreakdown.test.tsx and BreakdownNoticeArea.test.tsx — the breakdown renders only when the dimensions exist and conversion tracking is on; the notice shows in the other three combinations; neither renders while the setting is still loading.
• GatheringBreakdownDataBadge.test.tsx and SiteGoalsSurveyTriggers.test.tsx — neither fires for a site that has the dimensions but conversion tracking off.
• Add the conversion tracking settings to the setup of the remaining tests that render BreakdownNoticeArea, the Site Goals widgets, or the Audience Segmentation top content tile.
• No new Storybook story: the notice variants this gating shows are added in Enable Plugin Conversion Tracking from the Site Goals breakdown CTA with a disclosure variant of the notice #13398.
• No VRT changes expected.

QA Brief

Setup: Site Kit connected with Analytics, on a property with no Site Kit custom dimensions (googlesitekit_*). Archive them in GA Admin → Custom definitions, or use a fresh property, before each scenario.

1. Key Metrics: Select an author or category tile in the metrics selection panel and save (or click "Update" on a tile which requires these custom dimensions, ie. Top authors, top categories, etc.). Check that all five dimensions are created in GA: googlesitekit_post_date, googlesitekit_post_author, googlesitekit_post_categories, googlesitekit_post_type, googlesitekit_event_provider.
2. Audience Segmentation: Click the CTA on the "Top content" tile. Check that all five dimensions are created.
3. After either CTA, check that none of the other custom dimension notices show (Key Metrics, Top content, Site Goals).
4. After the Key Metrics or Audience Segmentation CTA, check that Plugin Conversion Tracking is unchanged in Settings → Admin Settings.
5. Site Goals breakdown:
   • If the dimensions exist and conversion tracking is on, the breakdown shows automatically, with no "Get breakdown" notice.
   • If the dimensions exist and conversion tracking is off, the notice still shows its conversion tracking variant.
   • The "Get breakdown" CTA and the "Enable" button in Analytics settings → advanced data breakdowns still work as before.
6. Run a CTA again when all the dimensions already exist. It should finish without an error and not create duplicates.

Changelog entry

• Standardize custom dimension notices and creation throughout plugin.