Feature Description

So far, Site Kit has shown users a couple of notices to set up certain Custom Dimensions that Site Kit uses to track additional data. However, if the user chooses to dismiss these notices, there is no way for them to be able to allow this in the future. With the requirement of additional custom dimensions for the new Site Goals widget, this situation is even more prominent - since without the creation of custom dimensions, there is little to no value in rendering the Site Goals widget.

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• A new Custom Dimensions setting is added to Analytics settings as per this Figma mock.
• Clicking on Enable will trigger the "create required custom dimensions" action within Site Kit which may trigger the oAuth flow if the user doesn't have the necessary scopes.
• When all the required custom dimensions have already been granted, a green tick should appear on the left as per the above Figma mock and the enable button should be hidden.
• The UI for the Enhanced Measurement setting should also be updated as per the above Figma mock.

Implementation Brief

• Add includes/Modules/Analytics_4/Advanced_Data_Breakdowns_Settings.php

  • Extend Setting and implement Setting_With_ViewOnly_Keys_Interface, following the Audience_Settings pattern
  • Option name: googlesitekit_analytics-4_advanced_data_breakdowns
  • Override get_type() to return 'object'
  • Override get_default() to return array( 'enabled' => false )
  • Override get_sanitize_callback() — cast enabled to (bool)
  • Implement get_view_only_keys() returning array( 'enabled' ) since view-only users will be able to see breakdown data
  • Add an is_enabled() accessor that returns $this->get()['enabled']
  • Add a merge() method following the same pattern as Audience_Settings::merge() for partial updates

• Add Get_Advanced_Data_Breakdowns_Settings datapoint under includes/Modules/Analytics_4/Datapoints/

  • Follow the Get_Audience_Settings pattern
  • Receives the Advanced_Data_Breakdowns_Settings instance via the $definition array
  • Returns the settings from the dedicated option, not from the main GA4 settings

• Add Save_Advanced_Data_Breakdowns_Settings datapoint under includes/Modules/Analytics_4/Datapoints/

  • Follow the Save_Audience_Settings pattern
  • Receives the Advanced_Data_Breakdowns_Settings instance via $definition
  • create_request validates enabled is a boolean, then calls merge() to update only the provided fields
  • Permission: MANAGE_OPTIONS

• In Analytics_4.php:

  • Instantiate Advanced_Data_Breakdowns_Settings in the constructor, same as $this->audience_settings
  • Call register() on it in the module's register() method
  • Add delete() call in the module's deactivation cleanup, alongside the existing audience_settings->delete()
  • Register both datapoints in get_datapoints() when the siteGoals feature flag is enabled:
    • 'GET:advanced-data-breakdowns-settings' and 'POST:save-advanced-data-breakdowns-settings'
    • Pass the settings instance in the definition array

• Add a JS datastore slice advanced-data-breakdowns.js under assets/js/modules/analytics-4/datastore/

  • Fetch stores for GET (modules/analytics-4/data/advanced-data-breakdowns-settings) and POST (modules/analytics-4/data/save-advanced-data-breakdowns-settings)
  • Action: setAdvancedDataBreakdownsEnabled( enabled ) — updates local state
  • Action: saveAdvancedDataBreakdownsSettings() — calls the dedicated POST endpoint
  • Selector: isAdvancedDataBreakdownsEnabled() — returns the enabled boolean, undefined while loading
  • Resolver for the GET selector
  • Wire into the analytics-4 datastore index.js

• Update the existing createCustomDimensions() action in custom-dimensions.js

  • After the existing resolveSelect calls at the top, also resolve MODULES_ANALYTICS_4.isAdvancedDataBreakdownsEnabled()
  • After deriving uniqueRequiredCustomDimensions from key metrics tiles, check if advanced data breakdowns is enabled and the siteGoals feature flag is on — if so, merge SITE_GOALS_CUSTOM_DIMENSIONS into the set
  • The rest of the flow (filter to missing, create loop, sync, clear in-progress) remains unchanged

• Add SITE_GOALS_CUSTOM_DIMENSIONS constant in assets/js/modules/analytics-4/datastore/constants.js

  • Array of all dimension keys from CUSTOM_DIMENSION_DEFINITIONS, extended with googlesitekit_event_provider and googlesitekit_form_id if this issue lands before Extend Conversion Tracking for Event Providers with two new custom dimensions #12775

• In Sync_Custom_Dimensions.php — no changes needed

  • parse_response already filters by the googlesitekit_ prefix, so new dimensions are automatically included in availableCustomDimensions
  • If Extend Conversion Tracking for Event Providers with two new custom dimensions #12775 has not added the new slugs to Custom_Dimensions_Data_Available::CUSTOM_DIMENSION_SLUGS, add them there

• Add SettingsAdvancedDataBreakdowns component

  • Add SettingsAdvancedDataBreakdowns.js in the analytics-4 settings components
  • Reads isAdvancedDataBreakdownsEnabled() and hasCustomDimensions( SITE_GOALS_CUSTOM_DIMENSIONS ) from MODULES_ANALYTICS_4
  • onEnable handler:
    • Checks hasScope( EDIT_SCOPE ) - if missing, sets autoSubmit: true in a form constant, then triggers OAuth via setPermissionScopeError with skipModal: true
    • If scope present: calls setAdvancedDataBreakdownsEnabled( true ) + saveAdvancedDataBreakdownsSettings(), then dispatches createCustomDimensions()
  • useEffect for OAuth return: when scope is present and autoSubmit is true, resets flag, enables, saves, dispatches creation
  • Implement states per the Figma design: loading (spinner), not enabled (star icon + Enable button), enabling (spinner + disabled button), enabled (green check, no button), error (inline error with retry)

• Update SettingsForm.js

  • Add the new component within the "Improve your measurement" group
  • Reorder children and add visual separators per the Figma mock

• Update styles in the relevant SCSS files for the new row layout

Test Coverage

• Add PHPUnit tests for Advanced_Data_Breakdowns_Settings — defaults, sanitization, is_enabled() accessor, merge() partial updates
• Add PHPUnit tests for Save_Advanced_Data_Breakdowns_Settings and Get_Advanced_Data_Breakdowns_Settings datapoints — verify saving updates only the dedicated option and does not touch the main GA4 settings
• Extend custom-dimensions.test.js for updated createCustomDimensions: verify site-goals dimensions are only included when advanced data breakdowns is enabled, and that they merge correctly with key-metrics dimensions
• Add Jest tests for the new advanced-data-breakdowns datastore slice — selectors, actions, resolver round-trip
• Add component tests for SettingsAdvancedDataBreakdowns — enable button visibility, green check state, enabling state, scope-missing OAuth path, error state
• Update SettingsEnhancedMeasurementSwitch test snapshots for the new row UI layout
• Update SettingsForm.stories.js with new section layout

QA Brief

Prerequisites

• Turn on the siteGoals feature flag in the Site Kit Tester plugin.
• Connect Analytics 4 as an admin who can manage options. Sign in with a Google account that has edit access to the Google Analytics property. This lets Site Kit create the custom dimensions.

Settings row

• Open the Analytics settings in edit mode. Check that an Advanced data breakdowns row sits in the Improve your measurement group. It should have a star icon, a title, a description, and an Enable button.
• Check that the whole Improve your measurement section matches the Figma mock, not just the new Advanced data breakdowns row. The section also has the Enhanced measurement setting and Plugin conversion tracking.
• Turn the siteGoals flag off. Check that the row no longer shows.

Enable with the edit scope present

• Click Enable when the Analytics edit scope is already granted. The button should show a spinner while the setting saves and the dimensions are created. Then a green check replaces the button.
• In Google Analytics, check that the Site Goals custom dimensions were created on the property.

Enable without the edit scope

• Reconnect Analytics without the edit scope. Click Enable. The OAuth permission screen should open right away, with no extra modal first.
• Grant the scope. Site Kit should come back, then enable, save, and create the dimensions on its own.

Green check when all dimensions exist

• Use a property that already has every Site Goals custom dimension, with the setting on. The row should show a green check on the left and no Enable button.

When enabling fails

• Connect Analytics with a Google account that can see the property but cannot make changes to it in Google Analytics. Click Enable, and grant the permission if Site Kit asks. An error message should appear at the top of the settings, and no new custom dimensions are added in Google Analytics.

Cancel keeps synced dimensions

• Sync the dimensions, then click Cancel on the settings form. The synced dimensions should stay, and the Enable button should not come back.

Learn more links

• Click the Learn more link on each row. Each one opens its help article in a new tab.

Changelog entry

• Add Custom Dimensions setup in Analytics Settings.