Implement the “Top content” metric handling for missing custom dimension

[techanvil]

Feature Description

Implement the ability to create the custom dimension from the "Top content" metric section if it's missing (e.g. the user has archived it in Analytics).

This includes the happy and unhappy paths, excluding those related to redirecting to OAuth if necessary which will be handled separately via #8154.

See audience tiles > "Top content" states 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

• In the case where the googlesitekit_post_type doesn't exist (e.g. the user has archived it in Analytics), the "Top content" metric area in an Audience Tile should be displayed in a zero data state which includes an Update CTA.
• Clicking Update should create the custom dimension. The CTA should show a spinner in the button while the API request is in flight.
• This should be implemented as per the Figma design.
• The Error Modal should be displayed if the API request returns an error.
  • If the request returns a permissions error, the insufficient permissions modal variant should be displayed.
    • Its Get help link will open the Analytics insufficient permissions support document.
    • The Request access button will open the URL for the connected web data stream in the Analytics UI, allowing the user to request access.
  • Otherwise, the catch-all modal variant will be shown which just includes the Retry button.
    • Note that the copy should be slightly different to that seen on Figma:
      • The title should be: Failed to enable metric
      • The description should be: Oops! Something went wrong. Retry enabling the metric.
    • Clicking the Retry button will retry creating the custom dimension.
• The Dashboard Sharing and User Menu buttons should be disabled while the custom dimension is being created in order to help avoid attempting to show multiple modals at once, which could result in modal conflicts.

Implementation Brief

Note: Depending on which issue is implemented first, it could be worth taking a look at the error handling introduced via #8134 to see if can be refactored for reuse.

Note 16 May 2024: Working on #8484 first because the getReportForAllAudiences will be refactored out making the Error selectors simpler.

Create a AudienceTilePagesMetricContent Component in assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTile:

• Define a new component AudienceTilePagesMetricContent that will be used to render the content of the "Top content" metric area.
• This component should encapsulate all the logic for displaying:
  • Custom dimension missing content with a message and SpinnerButton.
  • Link component for valid dimension values.
  • No data state using AudienceTileNoData.
  • Partial data notice for mobile breakpoints.
• It should receive the following props:
  • topContentTitles: PropTypes.object.isRequired,
  • topContent: PropTypes.object.isRequired,
  • isTopContentPartialData: PropTypes.bool.isRequired,
  • hasCustomDimension: PropTypes.bool.isRequired,
  • onCreateCustomDimension: PropTypes.func.isRequired,
  • isSaving: PropTypes.bool.isRequired,
• Check the valid dimension values within the component to avoid passing unnecessary props.
• Extract the logic for displaying the content based on the presence of custom dimensions and valid dimension values from AudienceTilePagesMetric.
• Implement the following functionalities:
  • If custom dimensions are missing, display a message indicating “No data to show” and “Update Analytics to track metric” along with a SpinnerButton with the text “Update”.
  • The SpinnerButton should be disabled if the isSaving prop is true.
  • Pass the onCreateCustomDimension callback function to the onClick prop of the SpinnerButton.
  • If custom dimensions exist but there are no valid dimension values, display the AudienceTileNoData component.
  • If there are valid dimension values, map through them and render the ContentLinkComponent component as per the current implementation in AudienceTilePagesMetric.
  • For mobile breakpoints, display a partial data notice if applicable as per the current implementation in AudienceTilePagesMetric.
  • The Update button styles should match the Figma design.
• Necessary tweaks for the extraction and refactoring can be addressed during the implementation phase.

Update the AudienceTilePagesMetric Component:

• Check if the custom dimension exists for the googlesitekit_post_type using the hasCustomDimensions selector.
• Check if the user has Analytics https://www.googleapis.com/auth/analytics.edit scope using the hasScope selector.
• Define a handleCreateCustomDimension callback function with the following logic:
  • Set the autoSubmit state to true in the CORE_FORMS store with the key AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE.
  • If the user doesn't have the edit scope, dispatch the setPermissionScopeError action with the code set to ERROR_CODE_MISSING_REQUIRED_SCOPE.
• Render the AudienceTilePagesMetricContent component with the following props:
  • topContentTitles - topContentTitles prop.
  • topContent - topContent prop.
  • isTopContentPartialData - isTopContentPartialData prop.
  • hasCustomDimension - hasCustomDimension prop.
  • onCreateCustomDimension - handleCreateCustomDimension callback function.
  • isSaving - Determine this using the isCreatingCustomDimension and isSyncingAvailableCustomDimensions selectors OR the autoSubmit state of the AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE form.
• Check if there are custom dimension errors for insufficient permissions if the getCreateCustomDimensionError selector returns an error.
• If there are errors, render the AudienceErrorModal component which is being implemented in #8134.
• Pass the title with the value Failed to enable metric and the description with the value Oops! Something went wrong. Retry enabling the metric. to the AudienceErrorModal component.
• Pass the handleCreateCustomDimension callback function to the onRetry prop of the AudienceErrorModal component.

Update the DashboardMainApp component to create the custom dimension:

• Retrieve the AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE form state.
• Create a callback function with the following:
  • Dispatch the fetchCreateCustomDimension action property ID and the googlesitekit_post_type.
  • If the custom dimension was created successfully, mark it as gathering data using the receiveIsCustomDimensionGatheringData action.
  • Resync available custom dimensions to ensure the newly created custom dimension is available using the fetchSyncAvailableCustomDimensions action.
  • Potentially, extract this logic from the enableAudienceGroup action into a separate action that does the above steps.
• Implement an useEffect hook if the autoSubmit state is true with the following:
  • Set the autoSubmit state of the AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE form to false.
  • Call the callback function created above.
• Add a TODO comment to refactor the above effect logic in Decouple module-specific effects from core components #8211.

Update the AudienceErrorModal component:

• Add new title and description props to the AudienceErrorModal component.
• If the title prop is set, render it in the modal. Otherwise, render the default title.
• If the description prop is set, render it in the modal. Otherwise, render the default description.

Disable the Dashboard Sharing and User Menu buttons:

• In the DashboardMainApp component, disable the Button component if the autoSubmit state is true for the AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE form.
• In the UserMenu/index.js component, disable the Button component if the autoSubmit state is true for the AUDIENCE_TILE_CUSTOM_DIMENSION_CREATE form.

Test Coverage

• Fix any existing stories that are broken due to the changes.
• Add stories for the AudienceTile component with the custom dimension missing content.
• Add stories for the AudienceTilesWidget component with the custom dimension missing content.
• Fix any existing tests that are broken due to the changes.

QA Brief

Prerequisites

1. Set up Analytics and enable the audienceSegmentation feature flag.
2. Ensure the audiences are enabled and available in the Audience widget area.
3. Ensure the audiences have data (i.e., not in the zero or partial data state).
4. Ensure the googlesitekit_post_type custom dimension is missing in Analytics. It can be archived or deleted in the Analytics UI.
5. Whenever you delete the custom dimension, ensure to sync the available custom dimensions by running the following command in the browser console:

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

Testing the Custom Dimension Missing Content

1. Verify the Audience Tile displays the "Top content" metric area in a zero data state:
   • The "Top content" metric area should include a message indicating "No data to show" and "Update Analytics to track metric". Note that the Figma design has a bold text for "No data to show". However, I have implemented it to be consistent with "No data to show yet". If the design needs to be updated, both copies should be updated in a separate issue.
   • The "Update" button should be displayed with a spinner while the API request is in flight.
   • Clicking the "Update" button should create the custom dimension.
   • Verify the "Update" button is disabled while creating the custom dimension. Note that the Figma design doesn't show the button disabled state. However, it should be disabled to avoid multiple triggers.
   • Verify the custom dimension is created successfully and the "Top content" metric area is updated with the valid dimension values.

Testing the Error Modal

There are two error variants to test:

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

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-custom-dimension request:
     • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/create-custom-dimension*
     • 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": {
              "propertyID": "property-id", // repalce with the actual property ID
              "customDimension": {
                "parameterName": "googlesitekit_post_type",
                "displayName": "WordPress Post Type",
                "description": "Created by Site Kit: Content type of a post",
                "scope": "EVENT"
          }
          }
          }

2. Trigger the Insufficient Permissions Error:

   • Click on the Update button in the Audience Tile.
   • 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:

1. API Errors:

   • Simulate a 500 error:

     • Add a new rule to block the create-custom-dimension request:
     • URL: .*/wp-json/google-site-kit/v1/modules/analytics-4/data/create-custom-dimension*
     • 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": {
              "propertyID": "property-id", // repalce with the actual property ID
              "customDimension": {
                "parameterName": "googlesitekit_post_type",
                "displayName": "WordPress Post Type",
                "description": "Created by Site Kit: Content type of a post",
                "scope": "EVENT"
          }
          }
          }

   • Trigger the Generic Error:

     • Click on the Update button in the Audience Tile.
     • 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 and verify the custom dimension is created successfully.

Changelog entry

• Provide the ability to create a required custom dimension in the "Top content" metric section if it's missing.

[techanvil]

Hey @hussain-t, nice work so far on the IB here. A few thoughts:

• I can understand why you've taken the approach with the withAudienceTileCustomDimension() HOC, as it somewhat mirrors the existing withCustomDimensions() HOC. However, while withCustomDimensions() is used for multiple components and thus makes sense as an HOC, withAudienceTileCustomDimension() would only be used with a single component. As such I don't see we need a HOC here, and would instead suggest a more straightforward approach keeping the logic within regular components. We already have an inline ContentLinkComponent within AudienceTilePagesMetric. I would suggest we refactor AudienceTilePagesMetric, creating a module for it, and extracting the main content section and the ContentLinkComponent component to simplify it. We could then include the custom dimension related logic directly in AudienceTilePagesMetric.

---

* [ ] If there are report errors, render the `AudienceErrorModal` component with the appropriate error prop.

• This point doesn't seem needed. If, having created the custom dimension, there is a report error, the Audience Tile should itself be displayed in an error state (handled via a separate issue), we won't show the Error Modal in this case.

---

• The AudienceTileNoData component renders the text "No data to show yet", but in the missing custom dimension scenario the text should be "No data to show", and the descriptive text "Update Analytics to track metric" should also be displayed. As a result, we should not try to reuse AudienceTileNoData in this scenario and should render some completely new content.

• Lastly, just as a note, I see that you have specced some of the OAuth flow that is covered in Implement the “Top content” metric handling OAuth flow #8154, but this does make sense to do here seeing as we'll be triggering the CD creation from the autoSubmit state. On a related note we might want to refactor the CD creation logic for KM and AS to combine them at some point, but this can be considered at a later date. This issue will also add more setup code to DashboardMainApp which again we'll want to refactor at some point; we already have the issue Decouple module-specific effects from core components #8211 which covers that to some extent.

[hussain-t]

Thanks for the valuable feedback, @techanvil. I have updated the IB accordingly. The refactoring of the DashboardMainApp can be handled separately in #8211, and I’ve added a note about this in the IB.

[techanvil]

Thanks @hussain-t! One thing - I've removed the point about report errors which was missed from the previous review. All looks good now, this IB LGTM. ✅

[hussain-t]

Sorry for the oversight, and thanks for updating it, @techanvil 👍

[techanvil]

Hi @hussain-t, as you'll have seen I've left some comments on the PR.

One more thing, with regard to the QAB - it would be worth providing this snippet as a tip for syncing the available custom dimensions after deleting the googlesitekit_post_type custom dimension:

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

[hussain-t]

Thanks, @techanvil. I've updated the QAB.

[kelvinballoo]

QA Update ⚠️

Hi @hussain-t I am having some issues to simulate the first error.
I've sent a video through to your slack as it was too big to attach here.

Let me know if you prefer to have a call to go through my potential issue.

[kelvinballoo]

QA Update ⚠️

Tested this and it's looking good.
One small clarification ⚠️

• In the AC, for the catch all error variant, it says: "Otherwise, the catch-all modal variant will be shown which just includes the Retry button."

  • From the way it's worded ("just includes the Retry button"), it feels there there should be only the 'Retry' button but we also have the 'Cancel' button.

  • My gut feel is that the 'Cancel' button is fine to be there but just to clarify in case the expectation is otherwise.

    

Other than that, the core functionality is working as expected:

• When the googlesitekit_post_type doesn't exist, the "Top content" metric area in an Audience Tile includes an Update CTA. ✅

  

• If the request returns a permissions error, the insufficient permissions modal variant displays accordingly. ✅

  • Get help link opens the Analytics insufficient permissions support document.
  • The Request access button opens the URL for the connected web data stream in the Analytics UI, allowing the user to request access.
  Error.variant.1.request.access.mov

• The catch-all modal variant was triggered and it included the Retry button. ✅

  • The copy is as expected:
    • The title is: Failed to enable metric
    • The description is: Oops! Something went wrong. Retry enabling the metric.
  • Clicking the Retry button created the custom dimension successfully
  • While the audience is being created, the CTA should shows a spinner in the button while the API request is in flight.
  Variant is as expected:

  error.variant.2.success.mov

  Recreating the custom dimension is successful:

  recreating.the.custom.dimension.success.mov

[hussain-t]

@kelvinballoo, it means to display the "Retry" button instead of "Request access". Cancel should be available regardless.

[kelvinballoo]

QA Update ✅

Thanks for confirming @hussain-t

This is working as expected:

• When the googlesitekit_post_type doesn't exist, the "Top content" metric area in an Audience Tile includes an Update CTA. ✅

  

• If the request returns a permissions error, the insufficient permissions modal variant displays accordingly. ✅

  • Get help link opens the Analytics insufficient permissions support document.
  • The Request access button opens the URL for the connected web data stream in the Analytics UI, allowing the user to request access.
  Error.variant.1.request.access.mov

• The catch-all modal variant was triggered and it included the Retry button. ✅

  • The copy is as expected:
    • The title is: Failed to enable metric
    • The description is: Oops! Something went wrong. Retry enabling the metric.
  • Clicking the Retry button created the custom dimension successfully
  • While the audience is being created, the CTA should shows a spinner in the button while the API request is in flight.
  Variant is as expected:

  error.variant.2.success.mov

  Recreating the custom dimension is successful:

  recreating.the.custom.dimension.success.mov

Moving ticket to approval