Feature Description

Handle Analytics account creation errors on the Analytics setup screen.

For reference, see the Account creation errors section in the design doc, and the Figma design.

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

Acceptance criteria

• If an error occurs when the user tries to create an Analytics account:
  • The user is redirected to the Analytics setup screen, which is shown in Create Account mode.
    • The form is repopulated with the details of the account to create.
    • A secondary CTA button is shown, with the label Continue without Analytics.
      • Clicking the button proceeds directly to the dashboard.
    • The AnalyticsAccountCreationErrorNotice component is shown (see Add the Analytics account creation error notification to Storybook. #12376).
      • The notification matches the Figma design, with copy as follows:
        • Terms of service not accepted variant (shown for the user_cancel error code):
          • Title: Analytics account creation failed
          • Description: Creating a new Analytics account failed because the Terms of Service were not accepted. Go to Analytics to accept the Terms of Service.
          • Button: Go to Analytics
        • Analytics account limit reached variant (shown for the max_accounts_reached error code):
          • Title: Analytics account creation failed
          • Description: Creating a new Analytics account failed because the Analytics account limit has been reached. You can manage the number of Analytics accounts associated with your Google account and then try again, or get help
          • Button: Retry
        • Generic error variant (shown for any other error code):
          • Title: Analytics account creation failed
          • Description: Something went wrong. Try again or get help
      • Clicking the Retry button retries the account creation process.
      • Clicking the Go to Analytics button navigates back to the Terms of Service screen.
• These changes are gated by the setupFlowRefresh feature flag.

Implementation Brief

See the implementation guide in the design doc.

In includes/Modules/Analytics_4.php:

• Update the handle_provisioning_callback() method to redirect to the Analytics setup screen instead of the dashboard when an error occurs.
  • When the error query parameter is present, redirect to the Analytics setup screen using $this->context->admin_url( 'dashboard', [ 'slug' => 'analytics-4', 'reauth' => true, ... ] ) instead of redirecting to the dashboard with error_code.
    • Pass the error value as the accountCreationErrorCode query parameter on the redirect URL.
    • If the show_progress query parameter is set, also pass showProgress on the redirect URL. This ensures the progress bar continues to be shown during the initial setup flow.
  • Apply the same redirect change for the account_ticket_id_mismatch and callback_missing_parameter error cases, so they also redirect to the Analytics setup screen with the appropriate accountCreationErrorCode.

In assets/js/modules/analytics-4/components/common/AccountCreate/AnalyticsAccountCreationErrorNotice.tsx:

• Update the max_accounts_reached variant description to match the new copy from the AC: "Creating a new Analytics account failed because the Analytics account limit has been reached. You can manage the number of Analytics accounts associated with your Google account and then try again, or <a>get help</a>". The existing analyticsAccountLimitHelpURL should remain wired up to the <a> placeholder via createInterpolateElement.
• Verify the user_cancel variant copy (title, description, "Go to Analytics" button) and the generic fallback variant copy (title, description, "Retry" button) match the AC. No copy change is expected for these variants based on current code, but they should be confirmed against the AC and Figma during implementation.
• Update AnalyticsAccountCreationErrorNotice.stories.tsx to reflect the updated max_accounts_reached copy.

In assets/js/modules/analytics-4/components/setup/SetupMain.js:

• Include a check for the presence of the accountCreationErrorCode query parameter (via useQueryArg or getQueryArg) in the condition for determining isCreateAccount. This will ensure the Create Account screen is shown when an error is present, even if the user has existing accounts.

In assets/js/modules/analytics-4/components/common/AccountCreate/index.js:

• Before navigating to the Terms of Service URL, snapshot only the CORE_FORMS store (via dispatch( CORE_FORMS ).createSnapshot()) so that the account creation form values are retained without snapshotting unrelated state. This ensures the form is repopulated upon returning with an error.
• When the accountCreationErrorCode query parameter is present (read via getQueryArg( location.href, 'accountCreationErrorCode' )):
  • Render the AnalyticsAccountCreationErrorNotice component (from Add the Analytics account creation error notification to Storybook. #12376), passing the accountCreationErrorCode value and the handleSubmit callback as its onRetry prop.
  • If the showProgress query parameter is also present (i.e. the user is in the initial setup flow), render a Continue without Analytics button (secondary/tertiary style). Its onClick handler should navigate to the dashboard without setting up Analytics.
    • If the user also has existing accounts (i.e. the Back button is present), render the Continue without Analytics button to the right of the Back button.
• Gate these changes behind the setupFlowRefresh feature flag.
• Update AccountCreate/index.stories.js to add stories for the error state variants, using the withQuery addon to simulate the accountCreationErrorCode query parameter.

Test Coverage

• Update AnalyticsAccountCreationErrorNotice.test.tsx to assert the updated max_accounts_reached description copy.
• Update AccountCreate/index.test.js to cover the error state: notice rendering, Retry button, and Continue without Analytics button (the latter only when showProgress is present).
• Update SetupMain tests to verify isCreateAccount is true when accountCreationErrorCode is present.
• Add PHP tests for handle_provisioning_callback() to verify the redirect URL and query parameters for each error case.

QA Brief

Setup

• Enable the setupFlowRefresh feature flag.
• Start the Site Kit setup flow and proceed to the Analytics setup screen. Choose to set up a new Analytics account.

Triggering errors

The simplest way to trigger an error is to decline the Terms of Service on the Google Analytics ToS screen. This produces the user_cancel error and routes the user back to the Analytics setup screen.

Other error variants (max_accounts_reached, generic backend errors) can be simulated by manually appending the corresponding accountCreationErrorCode query parameter to the Analytics setup screen URL, e.g.:

…/wp-admin/admin.php?page=googlesitekit-dashboard&slug=analytics-4&reAuth=true&showProgress=true&accountCreationErrorCode=max_accounts_reached

Verify the error state on the Analytics setup screen

• The Analytics setup screen is shown in Create Account mode.
• The form is repopulated with the values you entered before clicking "Create Account" (account name, property name, data stream name, country, timezone, etc.).
• The AnalyticsAccountCreationErrorNotice component is shown above the form, with the copy matching the AC for each variant:
  • user_cancel: title "Analytics account creation failed", description about Terms of Service not being accepted, Go to Analytics button.
  • max_accounts_reached: title "Analytics account creation failed", description mentioning "You can manage the number of Analytics accounts associated with your Google account…", Retry button.
  • Any other error code (e.g. accountCreationErrorCode=backend_error): title "Analytics account creation failed", description "Something went wrong. Try again or get help", Retry button.
• Clicking Retry triggers a fresh account creation attempt (you should be redirected to the Google Analytics Terms of Service screen again).
• Clicking Go to Analytics (on the user_cancel variant) navigates back to the Terms of Service screen via history.back().

Continue without Analytics button (initial setup flow only)

• When in the initial setup flow (i.e. showProgress=true is in the URL), a secondary Continue without Analytics button is shown next to the Create Account button.
• Clicking Continue without Analytics navigates directly to the Site Kit dashboard without setting up Analytics.
• When the user has existing Analytics accounts, both the Back button and the Continue without Analytics button are visible — the Continue without Analytics button appears to the right of the Back button.
• When not in the initial setup flow (e.g. setting up Analytics post-initial setup, no showProgress=true in URL), the Continue without Analytics button is not shown — only the error notice and the existing Create Account / Back buttons appear.

Changelog entry

• Enhance Analytics account creation flow to show errors inline.