Implement the Settings Section unhappy setup path

[techanvil]

Feature Description

Implement the Settings Section unhappy setup path, including errors returned from the OAuth flow.

See Settings section > setup CTA and
OAuth errors in the design doc.

---

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

Acceptance criteria

• Having clicked on Enable groups in the Settings section, if an error occurs, whether it's an error returned from the OAuth flow, or from an API call made to create the audiences and/or custom dimension, the Error Modal should be displayed on the Settings screen.
  • If an error is returned from the OAuth flow:
    • The OAuth error variant of the Error Modal should be displayed.
    • It should follow the Figma design, with the following copy:
      • Title: Analytics update failed
      • Description: Setup was interrupted because you did not grant the necessary permissions. Get help
    • The Retry button should take the user back to the OAuth flow to retry the setup from that point.
    • The Cancel button should close the modal.
    • The default OAuth error notice that Site Kit usually displays when the OAuth flow returns an error should not be shown.
  • If a permission error is returned by one of the API calls:
    • The "insufficient permissions" variant of the Error Modal should be displayed.
    • It should follow the Figma design, with the following copy:
      • Title: Insufficient permissions
      • Description: You’ll need to contact your administrator. Trouble getting access? Get help
    • The Request access button should open the URL for the currently connected web data stream in the Analytics UI, allowing the user to request access.
    • The Cancel button should close the modal.
  • If any other error is returned by one of the API calls:
    • The generic error variant of the Error Modal should be displayed.
    • It should follow the Figma design, with the following copy:
      • Title: Failed to set up visitor groups
      • Description: Oops! Something went wrong. Retry enabling groups.
    • The Retry button should close the modal, retry the failed API call(s) and continue setup from that point.
    • The Cancel button should close the modal.
• The Get help links should open the Analytics support page in a new tab, scrolled to the insufficient permissions section.

---

• Note that all copy should be verified with Figma as the source of truth.

Implementation Brief

Note that the AC are mostly identical to #8134 and the implementation reuses much of this tickets approach as well as the AudienceErrorModal component.

• Update assets/js/modules/analytics-4/components/audience-segmentation/settings/SettingsCardVisitorGroups/SetupCTA.js:
  • Add new boolean component state showErrorModal.
  • Update the use of the useEnableAudienceGroup hook to match the AudienceSegmentationSetupCTAWidget component, by destructuring the new props apiErrors and failedAudiences, and adding the new onError callback, setting showErrorModal to true:
    

    site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSegmentationSetupCTAWidget.js

    Lines 106 to 117 in 41f0bba

    	const { apiErrors, failedAudiences, isSaving, onEnableGroups } =
    	useEnableAudienceGroup( {
    	onSuccess: () => {
    	// Dismiss success notification in settings.
    	dismissItem(
    	SETTINGS_VISITOR_GROUPS_SETUP_SUCCESS_NOTIFICATION
    	);
    	},
    	onError: () => {
    	setShowErrorModal( true );
    	},
    	} );

  • Conditionally render AudienceErrorModal in this component, like so:
    

    site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSegmentationSetupCTAWidget.js

    Lines 296 to 308 in 41f0bba

    	{ ( showErrorModal || hasOAuthError ) && (
    	<AudienceErrorModal
    	hasOAuthError={ hasOAuthError }
    	apiErrors={ apiErrors.length ? apiErrors : failedAudiences }
    	onRetry={ onEnableGroups }
    	inProgress={ isSaving }
    	onCancel={
    	hasOAuthError
    	? onCancel
    	: () => setShowErrorModal( false )
    	}
    	/>
    	) }

    • Add the required onCancel callback, like so:
      

      site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSegmentationSetupCTAWidget.js

      Lines 147 to 154 in 41f0bba

      	const onCancel = useCallback( () => {
      	setValues( AUDIENCE_SEGMENTATION_SETUP_FORM, {
      	autoSubmit: false,
      	} );
      	clearPermissionScopeError();
      	setSetupErrorCode( null );
      	setShowErrorModal( false );
      	}, [ clearPermissionScopeError, setSetupErrorCode, setValues ] );

    • Get any error codes to pass to the error modal, like so:
      

      site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSegmentationSetupCTAWidget.js

      Lines 156 to 160 in 41f0bba

      	const setupErrorCode = useSelect( ( select ) =>
      	select( CORE_SITE ).getSetupErrorCode()
      	);
      	const hasOAuthError = autoSubmit && setupErrorCode === 'access_denied';

• Update OAuth error function to support a custom error redirect URL (based on this draft PR: POC: Provide a redirect URL for OAuth errors #9298), to redirect back to the Visitor Groups settings panel if the OAuth flow was triggered from this component.

Test Coverage

• Add tests for the SetupCTA component testing it's rendering conditions as well as each error condition above (you can use these tests as a guide).
• Add new tests for the error redirect URL functionality of the OAuth infrastructure.

QA Brief

Prerequisites

1. Setup Analytics and enable the audienceSegmentation feature flag.
2. Ensure no audiences have been created or configured.
3. Navigate to Settings > Admin Settings, and complete the testing here using the Setup CTA in settings:

Testing the Audience Error Modal Variants

There are three Audience Error Modal variants to test:

1. OAuth error variant.
2. Insufficient permissions error variant.
3. Generic error variant.

OAuth Error Variant

To simulate the OAuth error variant:

1. Prepare the Environment:

   • Delete the wp_googlesitekit_additional_auth_scopes entry from the wp_usermeta table if it exists. This entry contains the https://www.googleapis.com/auth/analytics.edit scope.

2. Trigger the OAuth Error:

   • Click on the Enable groups button in the Admin Settings, Visitor Groups CTA panel.
   • In the OAuth flow, when prompted to grant permissions, cancel the flow.
   • Ensure the OAuth error variant of the Error Modal is displayed.
   • Click the Retry button to trigger the OAuth flow again.
   • Complete the OAuth flow and grant permissions.
   • Ensure the setup continues successfully after granting permissions.

Note: this update introduces changes which could effect other OAuth error flows, so it's worth spending QA time reviewing other OAuth error flows to confirm there are no regressions caused by this work.

Insufficient Permissions Error Variant

To simulate the Insufficient Permissions error variant:

1. Install and Configure Tweak Extension:

   • Install the Tweak Chrome extension.
   • Add a new rule to block the sync-audiences request:
     • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/sync-audiences*
     • Enable the use of regular expression (.*)
     • HTTP Method: POST
     • Status code: 403
     • Response payload:

       {
         "code": 403,
         "message": "Insufficient Permissions Test Error",
         "data": {
           "status": 403,
           "reason": "insufficientPermissions"
         }
       }

2. Trigger the Insufficient Permissions Error:

   • Click on the Enable groups button in the Admin Settings, Visitor Groups CTA panel.
   • Ensure the Insufficient Permissions error variant of the Error Modal is displayed.
   • Click on the Request access button and verify the Analytics console opens in a new tab.

Generic Error Variant

To simulate the Generic Error variant, there are two scenarios:

1. Other API Errors:

   • Simulate Sync Available Audiences API Error:

     • Add a new rule in the Tweak extension to block the sync-audiences request:
       • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/sync-audiences*
       • Enable the use of regular expression (.*)
       • HTTP Method: POST
       • Status code: 500
       • Response payload:

         {
           "code": "internal_server_error",
           "message": "Internal server error",
           "data": { "status": 500 }
         }

   • Trigger the Generic Error:

     • Click on the Enable groups button in the Admin Settings, Visitor Groups CTA panel.
     • Ensure the Generic error variant of the Error Modal is displayed.
     • Disable the rule to unblock the request in the Tweak extension.
     • Click the Retry button to ensure the setup continues successfully.

Changelog entry

• Implement the unhappy path for the Settings Section Audience Segmentation setup flow, handling OAuth and API errors by displaying an Error Modal with options to retry, request access, or get help.

[benbowler]

Reducing the estimate as this ticket makes use of much of the work in #8134, and it mostly applying this proven approach to a new component.

[techanvil]

Hi @benbowler, thanks for drafting the IB. A couple of points:

• There is some additional work required in order to allow the Settings page to be navigated back to in response to an OAuth error. At the moment the error handling is hard baked to redirect to the dashboard or splash screen:
  

  site-kit-wp/includes/Core/Authentication/Clients/OAuth_Client.php

  Lines 651 to 655 in 0e32045

  	private function authorize_user_redirect_url() {
  	return current_user_can( Permissions::VIEW_DASHBOARD )
  	? $this->context->admin_url( 'dashboard' )
  	: $this->context->admin_url( 'splash' );
  	}

  • I've put a PoC together of how we could address this: POC: Provide a redirect URL for OAuth errors #9298
• We'll also want some test coverage, both for the OAuth related changes, and it would be good to provide test coverage on the JS side too, we do have test coverage relating to the error modal in the tests for AudienceSegmentationSetupCTAWidget which we're using as a guide.

[techanvil]

Thanks @benbowler. The IB LGTM, I've bumped the estimate up to reflect the additional work needed here w/re the OAuth error redirect, and the tests which could get a bit fiddly in places.

IB ✅

[mohitwp]

QA Update ✅

• Tested on dev environment.
• Tested using Tweak extension.

OAuth Error Variant

• If an error is returned from the OAuth flow:

• Verified that

• • Verified that The OAuth error variant of the Error Modal gets display.
• • Verified it is same as [Figma design} with the following copy:
• • Title: Analytics update failed
• • Description: Setup was interrupted because you did not grant the necessary permissions. Get help.
• • The Retry button take the user back to the OAuth flow to retry the setup from that point.
• • The Cancel button close the modal.
• • The default OAuth error notice that Site Kit usually displays when the OAuth flow returns an error not be shown.
• • Also, verified the OAuth flow error flow for all modules.
• • Clicking on 'Get help' link opens Analytics support page in a new tab,

Recording.1427.mp4

Recording.1430.mp4

Insufficient Permissions Error Variant

• If a permission error is returned by one of the API calls:

• Verified that -

• • The "insufficient permissions" variant of the Error Modal gets display.
• • It follow the [Figma design], with the following copy:
• • Title: Insufficient permissions
• • Description: You’ll need to contact your administrator. Trouble getting access? Get help
• • The Request access button open the URL for the currently connected web data stream in the Analytics UI, allowing the user to request access.
• • The Cancel button close the modal.
• • The Get help link open the Analytics support page in a new tab, scrolled to the insufficient permissions section.

Recording.1431.mp4

Recording.1433.mp4

Generic Error Variant

• If any other error is returned by one of the API calls:
• Verified that
• • The generic error variant of the Error Modal gets display.
• • It follow the [Figma design] with the following copy:
• • Title: Failed to set up visitor groups
• • Description: Oops! Something went wrong. Retry enabling groups.
• • The Retry button close the modal, retry the failed API call(s) and continue setup from that point.
• • The Cancel button close the modal.
• • Disabling the rule to unblock the request in the Tweak extension and Clicking the Retry button continues complete the setup successfully.

Recording.1432.mp4

Recording.1434.mp4