Return to the Settings screen on Analytics account creation error, when initiated from that screen

[techanvil]

Feature Description

If Analytics account creation is initiated from the Settings screen and an error occurs, the user should be returned to the Settings screen, with the error notice displayed and the account creation form repopulated with the relevant details.

This was raised in the bug bash, see this Asana task.

---

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

Acceptance criteria

• When Analytics account creation is initiated from the settings edit screen and an error occurs, the user is returned to the settings edit screen.
• The error notice is displayed and the account creation form is repopulated with the details of the account, property and data stream to create, as shown in the mock-up below.
• The error notice looks and behaves as described in Handle Analytics account creation errors on the Analytics setup screen. #12377.
• All form controls behave as expected - clicking Create account retries account creation, the Back button returns the user to the form variant with the dropdown to select their existing account, etc.
• This change is gated behind the setupFlowRefresh feature flag.

Implementation Brief

In includes/Modules/Analytics_4.php

• Update Analytics_4::get_provisioning_callback_error_redirect_url() so that the setupFlowRefresh branch returns the admin URL for 'settings#/connected-services/analytics-4/edit' if $this->is_connected(), with the $error_code passed through as the accountCreationErrorCode param.

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

• On the setting screen render the error notice below the "Create your Analytics account" heading, matching the mock-up. Use viewContext to conditionally render depending on the screen.

In assets/js/modules/analytics-4/components/settings/SettingsEdit.js

• Read the error code with getQueryArg( location.href, 'accountCreationErrorCode' ) on each render, the way AccountCreate reads it. A useQueryArg read stays stale after Fix Back button on the Analytics setup screen when an account creation error occurs #12875's Back handling removes the parameter from the URL.
• Extend isCreateAccount following SetupMain's check:
• Add an effect that dispatches setAccountID( ACCOUNT_CREATE ) while the error code is present, the same effect Fix Back button on the Analytics setup screen when an account creation error occurs #12875 adds to SetupMain. The Back button's rollbackSettings() needs this client-side change to revert, or the screen never re-renders out of the error state.

Test Coverage

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

• Cover clicking Back on a settings URL removing accountCreationErrorCode and keeping the #connected-services/analytics-4/edit route. Seed a saved accountID, dispatch setAccountID( ACCOUNT_CREATE ), and seed one account summary so the Back button renders.

Create assets/js/modules/analytics-4/components/settings/SettingsEdit.test.tsx.

• Cover the create account form and the error notice rendering when accountCreationErrorCode is in the URL, the setupFlowRefresh flag is on, and the saved accountID points at an existing account, with accountID becoming ACCOUNT_CREATE in the store.
• Cover SettingsForm rendering when the flag is off, even with the error code present.
• Cover SettingsForm rendering when there is no error code.
• Cover clicking Back rendering SettingsForm again, with accountID back at the saved value, the error code removed from the URL, and the route/hash kept.

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

• Add a settings-context account creation error story with accountCreationErrorCode set and no showProgress, following the existing initial setup flow error stories.
• Render the story with VIEW_CONTEXT_SETTINGS and give it a Backstop scenario.

In tests/phpunit/integration/Modules/Analytics_4Test.php.

• Add coverage for handle_provisioning_callback() that asserts the expected redirect to the settings page if setupFlowRefresh is enabled and the $this->is_connected() for both successes and failures. Assert that the redirect behaviour is unchanged if the module is not connected.

Update any failing VRT.

QA Brief

Setup

• Enable the setupFlowRefresh feature flag.
• Set up Site Kit with Analytics.
• Go to Site Kit Settings -> Analytics -> edit and 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 settings edit screen URL, e.g.:

…/wp-admin/admin.php?page=googlesitekit-settings&accountCreationErrorCode=max_accounts_reached#/connected-services/analytics-4/edit

Verify the error state on the Analytics settings edit screen

• The Analytics settings edit 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 error notice is shown above the form, according to the attached mock in the issue description.
• Clicking Retry triggers a fresh account creation attempt.
• Clicking Go to Analytics (on the user_cancel variant) navigates back to the Terms of Service screen.

Changelog entry

• Fix Analytics account creation errors to redirect back to the Settings screen when initiated from there.

[shervElmi]

Hi @techanvil!

I wasn't aware this ticket belonged to team Mario when I started. I added a draft IB to the task, hope it helps. I'm unassigning myself so team Mario can take it.

[techanvil]

Thanks @shervElmi!

[JakePT]

@techanvil @shervElmi I've updated the IB and am moving to IBR. I tweaked a couple of things about the original approach:

• It turns out that adding a from_settings parameter to the redirect URL that's sent with the account ticket request wouldn't work because the service rejects this as an invalid redirectUri. The service is pretty strict and would need to be updated to support any additional parameters on the redirect URL. So instead of passing through a parameter I'm saving a short-lived transient that remembers where account creation was started, which is a pattern this flow already uses. Props to @aaemnnosttv for catching this when we chatted.
• Instead of a boolean fromSettings parameter I'm using an accountCreatedFrom string that holds the view context when account creation is started, just so that we have the flexibility to handle account creation from other views if that ever becomes necessary.

[JakePT]

@techanvil A couple of things I'd be interested in feedback on from the IBR:

• I'm not being strict about the value of the transient and don't have any sanitisation because it's only ever being used to compare to an exact string. Would it be worth defining supported values in PHP and sanitising accordingly, even if it's not strictly necessary right now?
• I only bother checking for setupFlowRefresh when getting the redirect URLs based on the transient, which is the only place the effect of the change is actually felt. So the transient is saved even if the flag is not enabled, it just doesn't do anything. Is this ok or would we prefer to avoid all side effects if the flag is not enabled?
• The transient is a single global value, but I'm wondering if it should be scoped to the current user's ID, the way the account ID transient is?