Feature Description

Implement the unhappy paths for the Setup CTA Banner, making use of the Error Modal to display them. This includes handling errors returned by the OAuth flow.

See setup CTA banner > setup logic, OAuth errors and error modal 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 Setup CTA Banner, 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 (see Update the Modal Dialog component for error and confirmation actions (Storybook) #8110).
  • 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

Update the enableAudienceGroup action in assets/js/modules/analytics-4/datastore/actions.js:

• Update Function (Action) Signature
  • Modify the enableAudienceGroup action to accept an object parameter that includes failedSiteKitAudienceResourceNames - A list of audiences that failed to be created by Site Kit.
• Return Error Objects
  • Identify all the places in the action where there are TODO comments for error handling.
  • Replace each TODO comment with a return statement that returns an error object. For example, if there is an error in synchronizing available audiences, return the error object immediately.
• Handle Site Kit-Created Audience Failures
  • Add a conditional check at the beginning of the audience creation logic to see if failedSiteKitAudienceResourceNames is provided.
  • If failedSiteKitAudienceResourceNames is provided, skip the creation of new audiences and proceed with the logic.
• Update Audience Creation Logic
  • Modify the existing audience creation logic to handle retries by using the failedSiteKitAudienceResourceNames parameter.
  • Define the audiences to be created based on whether failedSiteKitAudienceResourceNames is provided or use the default list of audiences to create.
• Handle Creation Results
  • After attempting to create the audiences, track which audiences need to be retried if their creation fails.
  • Use an array (e.g., needsRetry) to store the slugs of the audiences that failed to be created.
  • If any audiences need to be retried, return an object with failedSiteKitAudienceResourceNames containing the slugs of the failed audiences.
• Syncing the available audiences, updating the configured audiences, and saving the audience settings should be kept as is.
• Check this commit for reference on a POC branch as a starting point.

Update the ModalDialog component in assets/js/components/ModalDialog.js:

• Add a new prop buttonLink to handle opening a link in a new tab.
• If buttonLink is provided, update the SpinnerButton component props to include href and target attributes with the buttonLink and _blank values, respectively.

Create AudienceErrorModal component in assets/js/modules/analytics-4/components/audience-segmentation/dashboard:

• It should receive hasOAuthError, apiErrors and onRetry as props. Prop names can be adjusted as needed during implementation.
• Use the ModalDialog component to render the error modal.
• Pass the buttonLink prop to the ModalDialog component for OAuth and insufficient permissions errors and other appropriate props.
• OAuth error variant:
  • If hasOAuthError is true, render the OAuth error variant of the Error Modal. See the Figma design for details.
  • Reuse the same callback logic to retry the setup from the OAuth flow, which is being implemented in Implement the OAuth flow for the Setup CTA Banner #8132. Potentially, create a reusable action for this.
• Insufficient permissions error variant:
  • If apiErrors contains an insufficient permissions error, render the insufficient permissions error variant of the Error Modal. See the Figma design for details.
• Generic error variant:
  • If apiErrors contains any other error, render the generic error variant of the Error Modal. See the Figma design for details.
  • Call the onRetry prop when the Retry button is clicked within a callback function. The parent component should pass the appropriate retry function (i.e., enableAudienceGroup action with the failedSiteKitAudienceResourceNames parameter).
• See ReportErrorActions for an example of how to determine the insufficient permissions error and generic error variants.
• Figma designs should be the source of truth for copy and design details.

Update the AudienceSegmentationSetupCTAWidget component in assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSegmentationSetupCTAWidget.js:

• Create a component state to store the API errors.
• Create a component state to store the failed Site Kit audience resource names from the enableAudienceGroup action response.
• Get the { error, response } object from the enableAudienceGroup action response within the onEnableGroups callback function.
• Set the error state based on the response from the enableAudienceGroup action.
• Set the failed Site Kit audience resource names state based on the response from the enableAudienceGroup action.
• Check if there is an OAuth error using the getSetupErrorCode selector.
• If there is an OAuth error or API error, render the AudienceErrorModal component with the appropriate props.
• Pass a callback function to the onRetry prop of the AudienceErrorModal component to retry the enableAudienceGroup action with the failed audience resource names.
• Set Skip Error Notification Flag:
  • When triggering the OAuth flow, pass skipDefaultErrorNotifications to true while dispatching the setPermissionScopeError action.

Prevent Rendering Other Setup Errors in assets/js/components/notifications/ErrorNotifications.js and assets/js/components/notifications/SetupErrorNotification.js:

• Modify the ErrorNotifications and SetupErrorNotification components to check if temporaryPersistedPermissionsError?.data?.skipDefaultErrorNotifications is set.
• If skipDefaultErrorNotifications is set, do not render the error notifications. i.e., return null.
• See how the temporary persisted permissions error is retrieved in the ErrorNotifications:
  

  site-kit-wp/assets/js/components/notifications/ErrorNotifications.js

  Lines 56 to 61 in 17215a0

  	const temporaryPersistedPermissionsError = useSelect( ( select ) =>
  	select( CORE_FORMS ).getValue(
  	FORM_TEMPORARY_PERSIST_PERMISSION_ERROR,
  	'permissionsError'
  	)
  	);

Test Coverage

• Add storybook stories for all the error variants for the AudienceErrorModal component.
• Add test coverage for all the error variants for the AudienceErrorModal component.
• Add test coverage for the changes made to the enableAudienceGroup action.
• Fix any broken stories in the AudienceSegmentationSetupCTAWidget component.
• Fix any failing tests.

QA Brief

Prerequisites

1. Setup Analytics and enable the audienceSegmentation feature flag.
2. Ensure no audiences have been created or configured.
3. Verify the Audience Segmentation setup CTA banner is displayed.

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 Audience Segmentation setup CTA banner.
   • 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.

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 Audience Segmentation setup CTA banner.
   • 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 Audience Segmentation setup CTA banner.
     • 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.

2. Audience Creation Failure:

* Simulate Audience Creation Failure:
- Manually create new-visitors and returning-visitors audiences in the Analytics console.
- Click on the Enable groups button in the Audience Segmentation setup CTA banner.
- Ensure the Generic error variant of the Error Modal is displayed.
- Delete the new-visitors and returning-visitors audiences in the Analytics console.
- Click the Retry button to ensure the setup continues successfully.

Changelog entry

• Handle errors in the Audience Segmentation setup flow, showing an error modal allowing the setup to be retried, or relevant permissions to be requested.