Implement the unhappy paths for the Audience Creation Notice

[techanvil]

Feature Description

Implement the unhappy paths for creating an audience via the Audience Creation Notice. This does include showing an error from the OAuth flow.

See audience creation > error states 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 Create for an audience in the Audience Creation Notice, if an error occurs, whether it's an error returned from the OAuth flow, or from an API call made to create the audience, an error notice should be displayed within the Audience Creation Notice at the bottom.
  • If an error is returned from the OAuth flow:
    • The OAuth error variant of the error notice should be displayed.
    • It should follow the Figma design, with the following copy:
      • Setup was interrupted because you didn't grant the necessary permissions. Click on Create again to retry. If that doesn't work, get help
    • 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 the API call to create the audience:
    • The "insufficient permissions" variant of the error notice should be displayed.
    • It should follow the Figma design, with the following copy:
      • Title: Insufficient permissions
      • Description: 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.
  • If any other error is returned by the API call to create the audience:
    • The generic error variant of the error notice should be displayed.
    • It should follow the Figma design, with the following copy:
      • Title: Analytics update failed
      • Description: Click on Create to try again.
• 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

Create the AudienceCreationErrorNotice component in assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel:

• It can take most of the logic to determine the error variant from the AudienceErrorModal component.
• It should receive apiErrors and hasOAuthError as props. It doesn't need other props from the AudienceErrorModal component as it will be scoped to the AudienceCreationNotice component.
• It should render the error variant (copy and the CTA) based on the determined error variant.
• The design should match the Figma designs for the error variants mentioned in the AC.

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

• Create a component state to store the API errors.
• Store the { error } object returned from the createAudience action within the handleCreateAudience callback function in the component state.
• Get the error setup code using the getSetupErrorCode selector of the CORE_SITE store.
• Create a boolean variable hasOAuthError that checks if autoSubmit is true and the setup error code equals 'access_denied'.
• If there is an OAuth error or API error, render the AudienceCreationErrorNotice component with the appropriate props.
• For example, review the implementation in AudienceSegmentationSetupCTAWidget.

Test Coverage

• Add stories for the AudienceCreationErrorNotice component to cover the error variants.
• Add stories for the AudienceSelectionPanel component to cover the possible error variants.
• Add tests for the AudienceSelectionPanel component to cover the error variants.

QA Brief

Prerequisites

• Setup the Analytics module and enable the Audience Segmentation.
• 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.
• Delete the new-visitors and returning-visitors audiences in the Analytics console.
• Run the following command in the browser console to sync the custom dimensions:

  googlesitekit.data.dispatch( 'modules/analytics-4' ).syncAvailableAudiences()

• Refresh the page if necessary.
• Always try creating the "new-visitors" audience since the request payload provided below is for this audience.
• To try the "returning-visitors" audience, open the developer tools and go to the "Network" tab. Click on the "Create" button in the Audience Segmentation selection panel audience creation notice. Find the create-audience request in the network tab and copy the request payload. Use this payload in the Tweak extension to simulate the errors. Ensure the Tweak extension is disabled to make a successful request.

Testing the Error Notice Variants

There are three Error Notice 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 Create button in the Audience Segmentation selection panel audience creation notice.
   • In the OAuth flow, when prompted to grant permissions, cancel the flow.
   • Ensure the OAuth error notice is displayed.
   • Complete the OAuth flow and grant permissions.
   • Ensure the audience creation 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 create-audience request:
     • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/create-audience*
     • 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"
        }
       }

       • Request payload:

          {
              "data": {
                  "audience": {
                      "description": "People who visited the site for the first time",
                      "displayName": "New visitors",
                      "membershipDurationDays": -1,
                      "filterClauses": [
                          {
                              "clauseType": "INCLUDE",
                              "simpleFilter": {
                                  "scope": "AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
                                  "filterExpression": {
                                      "andGroup": {
                                          "filterExpressions": [
                                              {
                                                  "orGroup": {
                                                      "filterExpressions": [
                                                          {
                                                              "dimensionOrMetricFilter": {
                                                                  "fieldName": "newVsReturning",
                                                                  "stringFilter": {
                                                                      "matchType": "EXACT",
                                                                      "value": "new"
                                                                  }
                                                              }
                                                          }
                                                      ]
                                                  }
                                              },
                                              {
                                                  "orGroup": {
                                                      "filterExpressions": [
                                                          {
                                                              "notExpression": {
                                                                  "dimensionOrMetricFilter": {
                                                                      "fieldName": "groupId",
                                                                      "stringFilter": {
                                                                          "matchType": "EXACT",
                                                                          "value": "created_by_googlesitekit:new_visitors"
                                                                      }
                                                                  }
                                                              }
                                                          }
                                                      ]
                                                  }
                                              }
                                          ]
                                      }
                                  }
                              }
                          }
                      ]
                  }
              }
          }

2. Trigger the Insufficient Permissions Error:
   • Click on the Create button in the Audience Segmentation selection panel audience creation notice.
   • Ensure the Insufficient Permissions error notice 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:

1. API Errors:

   • Simulate a 500 error:
     • Add a new rule to block the create-audience request:
     • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/create-audience*
     • 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
        }
        }

       • Request payload:

          {
              "data": {
                  "audience": {
                      "description": "People who visited the site for the first time",
                      "displayName": "New visitors",
                      "membershipDurationDays": -1,
                      "filterClauses": [
                          {
                              "clauseType": "INCLUDE",
                              "simpleFilter": {
                                  "scope": "AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS",
                                  "filterExpression": {
                                      "andGroup": {
                                          "filterExpressions": [
                                              {
                                                  "orGroup": {
                                                      "filterExpressions": [
                                                          {
                                                              "dimensionOrMetricFilter": {
                                                                  "fieldName": "newVsReturning",
                                                                  "stringFilter": {
                                                                      "matchType": "EXACT",
                                                                      "value": "new"
                                                                  }
                                                              }
                                                          }
                                                      ]
                                                  }
                                              },
                                              {
                                                  "orGroup": {
                                                      "filterExpressions": [
                                                          {
                                                              "notExpression": {
                                                                  "dimensionOrMetricFilter": {
                                                                      "fieldName": "groupId",
                                                                      "stringFilter": {
                                                                          "matchType": "EXACT",
                                                                          "value": "created_by_googlesitekit:new_visitors"
                                                                      }
                                                                  }
                                                              }
                                                          }
                                                      ]
                                                  }
                                              }
                                          ]
                                      }
                                  }
                              }
                          }
                      ]
                  }
              }
          }

   • Trigger the Generic Error:
     • Click on the Create button in the Audience Segmentation selection panel audience creation notice.
     • Ensure the Generic error notice is displayed.
     • Disable the rule to unblock the request in the Tweak extension.
     • Click the Create button and verify the audience is created successfully.

Changelog entry

[techanvil]

I've moved this back to Backlog as the final in-progress changes to the design doc, relating to audience caching, will probably affect the AC for this one

[techanvil]

The audience caching aspect of the design doc has been sufficiently finalised, and I've moved this back to AC.

[techanvil]

Hi @hussain-t, thanks for drafting this IB. The production code side looks good. My only hesitation is that the amount of testing looks a bit excessive. It suggests we'll effectively be providing stories and tests that cover the same thing multiple times - the AudienceSelectionPanel stories/tests would be things in their fully integrated form, so maybe we don't actually need the explicit AudienceCreationNotice coverage as well. Incidentally I'm guessing the last line of the Test Coverage section is intended to refer to the AudienceSelectionPanel component?

[hussain-t]

Thanks, @techanvil. I've updated the test coverage as suggested. However, retaining the AudienceCreationErrorNotice stories is important to ensure all error variants are captured. Specifically, scenarios like insufficient permissions and generic errors might be challenging to cover within the AudienceSelectionPanel stories, as these depend on the component state.

[techanvil]

Thanks @hussain-t. Agreed, keeping the AudienceCreationErrorNotice stories makes sense and will be useful during development too.

IB ✅

[nfmohit]

@techanvil Temporarily co-assigning this to you for visibility as I have a question regarding the ACs in the PR here. Thanks!

CC: @hussain-t