Ensure the "Top content" CTA for creating the custom dimension appears when the corresponding report error shows the custom dimension is missing

[techanvil]

Feature Description

The Audience Tile's "Top content" metric area has a CTA for creating the googlesitekit_post_type custom dimension if it doesn't exist.

However, it doesn't have logic in place to determine if the custom dimension doesn't exist when requesting the report for the metric. At present it's reliant on the list of available custom dimensions being synced somewhere, which only happens during Audience Segmentation setup, or in the Key Metrics feature.

We should ensure that, if the report for the "Top content" metric returns an error because the custom dimension doesn't exist, the list of custom dimensions is resynced so the tile will immediately know that the dimension is missing and show the CTA to create it.

---

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

Acceptance criteria

• If the reports for the Audience Tile's "Top content" metric return an error because the custom dimension doesn't exist:
  • For an authenticated user:
    • The list of available custom dimensions should be resynced.
    • The Audience Tiles should remain in the loading state while the resync is happening.
    • Once the resync has finished the populated tiles should show with the CTA for creating the googlesitekit_post_type present in the "Top content" metric area (already implemented via Implement the “Top content” metric handling for missing custom dimension #8153).
  • For a view-only user, the "Top content" metric area should not be displayed.
    • This is because a view-only user doesn't have permission to sync custom dimensions, and we are not going to show the "Top content" metric to them if the custom dimension doesn't exist (see Ensure the “Top content” metric doesn’t appear for view-only users if the custom dimension doesn’t exist #8175), so the logical thing to do here is not to display the metric area if the custom dimension state can't be determined.

Implementation Brief

Add Missing Custom Dimension to Top Content Report

• Add the googlesitekit_post_type dimension filter to the top content report options:

 dimensionFilters: { 
 	'customEvent:googlesitekit_post_type': { 
 		filterType: 'stringFilter', 
 		matchType: 'EXACT', 
 		value: 'post', 
 	}, 
 }, 

site-kit-wp/assets/js/modules/analytics-4/hooks/useAudienceTilesReports.js

Lines 322 to 329 in 119747b

	const topContentReportOptions = {
	startDate,
	endDate,
	dimensions: [ 'pagePath' ],
	metrics: [ { name: 'screenPageViews' } ],
	orderby: [ { metric: { metricName: 'screenPageViews' }, desc: true } ],
	limit: 3,
	};

site-kit-wp/assets/js/modules/analytics-4/hooks/useAudienceTilesReports.js

Lines 346 to 353 in 119747b

	const topContentPageTitlesReportOptions = {
	startDate,
	endDate,
	dimensions: [ 'pagePath', 'pageTitle' ],
	metrics: [ { name: 'screenPageViews' } ],
	orderby: [ { metric: { metricName: 'screenPageViews' }, desc: true } ],
	limit: 15,
	};

Authenticated User Context

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTiles.js (note the new useAudienceTilesReports custom hook merged in Handle the special case for “new visitors” and “returning visitors” to avoid the “partial data” state in the Audience Tile #8144):
  • Add a useEffect with topContentReportErrors as a dependency.
    • Check if the topContentReportErrors contains any invalid custom dimension errors using the .find prototype, and use the isInvalidCustomDimensionError util to identify this error type.
    • If an invalid custom dimension error exists, dispatch the action fetchSyncAvailableCustomDimensions.
  • Create a new boolean constant isSyncingAvailableCustomDimensions containing the value of the isFetchingSyncAvailableCustomDimensions selector:
    

    site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTile/AudienceTilePagesMetric.js

    Lines 94 to 96 in 56feb1f

    	const isSyncingAvailableCustomDimensions = useSelect( ( select ) =>
    	select( MODULES_ANALYTICS_4 ).isFetchingSyncAvailableCustomDimensions()
    	);

    • Update the loading statement to include isSyncingAvailableCustomDimensions :
      

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

      Lines 419 to 427 in 41f0bba

      	const loading =
      	widgetLoading ||
      	! reportLoaded ||
      	! siteKitAudiencesReportLoaded ||
      	! totalPageviewsReportLoaded ||
      	! topCitiesReportLoaded ||
      	! topContentReportLoaded ||
      	! topContentPageTitlesReportLoaded;

• Filter out invalid custom dimension errors from topContentReportErrors and topContentPageTitlesReportErrors here, using the isInvalidCustomDimensionError util, so that the Top Cities Audience Tile will be rendered if there is only an invalid custom dimension error:
  

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

  Lines 321 to 322 in b2d47c8

  	topContentReportErrors,
  	topContentPageTitlesReportErrors,

View-Only Context

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTile/index.js, use the getErrorForSelector selector to get any errors for the top content report for the audienceResourceName of the current tile.
  • Update this conditional block to not render the Top Cities metric if the user is in the view-only context and the there is a invalid custom dimension error for the Top Cities report:
    

    site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTile/index.js

    Line 261 in b2d47c8

    { ( ! isViewOnly || postTypeDimensionExists ) && (

Test Coverage

• Update the tests that fail due to the addition of the custom dimension filter for the Top Content queries.
• Create a VRT when the tile is in the view-only context with an invalid custom dimension error for the Top Content report.

QA Brief

Authenticated user

• Set up Site Kit with the audienceSegmentation feature flag enabled and Analytics connected to a property which is out of the "gathering data" state.
• Click on Enable groups to set up Audience Segmentation.
• Archive the googlesitekit_post_type custom dimension in Analytics.
• Return to Site Kit and clear session storage: sessionStorage.clear() in the JS console.
• Refresh the dashboard.
• Error messages including the phrase "Field customEvent:googlesitekit_post_type is not a valid dimension." will appear in the JS console, this is to be expected.
• A POST request to the sync-custom-dimensions endpoint should appear in the network devtools.
• The Update CTA should appear in the "Top content" metric area in the Audience Tiles.

View-only user

• Having run through the steps above, share Analytics and login as a view-only user with access to the module.
• The "Top content" metric area should not appear in the Audience Tiles.

Changelog entry

• Ensure the "Top content" CTA for creating the googlesitekit_post_type custom dimension appears in the main dashboard when the corresponding report error indicates the missing custom dimension.

[techanvil]

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

• Thinking about Ensure the “Top content” metric doesn’t appear for view-only users if the custom dimension doesn’t exist #8175, I've realised there's an edge case for view-only users that we should handle in this issue, although it wasn't explicitly captured in the AC. I hope you don't mind, but I've amended the AC to include this.

... selectors to monitor syncAvailableCustomDimensions selector/resolver like so:

• As we're dispatching the fetchSyncAvailableCustomDimensions() action, this doesn't seem right. We'll probably want to use isFetchingSyncAvailableCustomDimensions(), e.g.:

site-kit-wp/assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget/AudienceTile/AudienceTilePagesMetric.js

Lines 94 to 96 in 56feb1f

	const isSyncingAvailableCustomDimensions = useSelect( ( select ) =>
	select( MODULES_ANALYTICS_4 ).isFetchingSyncAvailableCustomDimensions()
	);

[techanvil]

Hi @benbowler, thanks for updating the IB. A few more points:

For the view-only context:

• We shouldn't need to check isSyncingAvailableCustomDimensions in the AudienceTile component because the AudienceTileLoading component will be rendered instead due to including this value in the loading condition.
• We need to filter out invalid custom dimension errors from the list that determines the individualTileErrors value, in order to avoid showing the whole tile in the error state, but still need to flag that there was an invalid custom dimension error to the AudienceTile so it can avoid rendering the "Top content" metric area.

More fundamentally, though - I've noticed the googlesitekit_post_type custom dimension is actually missing from the "Top content" report options:

site-kit-wp/assets/js/modules/analytics-4/hooks/useAudienceTilesReports.js

Lines 322 to 329 in 119747b

	const topContentReportOptions = {
	startDate,
	endDate,
	dimensions: [ 'pagePath' ],
	metrics: [ { name: 'screenPageViews' } ],
	orderby: [ { metric: { metricName: 'screenPageViews' }, desc: true } ],
	limit: 3,
	};

site-kit-wp/assets/js/modules/analytics-4/hooks/useAudienceTilesReports.js

Lines 346 to 353 in 119747b

	const topContentPageTitlesReportOptions = {
	startDate,
	endDate,
	dimensions: [ 'pagePath', 'pageTitle' ],
	metrics: [ { name: 'screenPageViews' } ],
	orderby: [ { metric: { metricName: 'screenPageViews' }, desc: true } ],
	limit: 15,
	};

It needs to be added as a dimension filter, like we do here, but with value: 'post':

site-kit-wp/assets/js/modules/analytics-4/components/widgets/PopularProductsWidget.js

Lines 79 to 85 in 119747b

	dimensionFilters: {
	'customEvent:googlesitekit_post_type': {
	filterType: 'stringFilter',
	matchType: 'EXACT',
	value: productPostType,
	},
	},

This will be needed for this issue to be complete and testable, so we should include the fix here too. There's likely to be a number of tests that need updating as a result which we should factor into the estimate.

[benbowler]

I chose to use the getErrorForSelector selector within the AudienceTile component instead of adding another new prop to this component, we could instead create a new prop such as hasTopContentCustomDimensionError instead if prefered.

I've increased the estimate a couple of bands because the scope has expanded slightly as we've discussed required fixes/additions to be able to work on this ticket.

[techanvil]

Thanks @benbowler. Using getErrorForSelector() SGTM.

A small point, you've referred/linked to topCitiesReportErrors with regard to filtering out the invalid custom dimension errors, in fact they should be filtered out from topContentReportErrors and topContentPageTitlesReportErrors. I've amended that to save a round trip.

IB ✅

[kelvinballoo]

QA Update ⚠️

Hi @techanvil , I followed the steps but it doesn't seem like it's working as expected.

• I've archived googlesitekit_post_type custom dimension in Analytics.

• I used the tester plugin with the following settings

  

• However, after running the clear session storage line and refreshing, nothing really changes.

• Video is attached for reference:

  9218.test.failed.mov

Let me know in case I missed any steps.

[techanvil]

Hey @kelvinballoo, maybe I should have mentioned this in the QAB, but you won't be able to test this issue with the Tester plugin configured to provide mock report data. This is because the underlying code relies on the error response returned by the real request for the "Top content" data once the custom dimension has been archived.

You should be able to test this with any property which is legitimately out of the gathering data state. Please give it another try and let me know if you run into any further problems.

[kelvinballoo]

QA Update ✅

Hi @techanvil , thanks.
I managed to test it with a site, despite having 0 data, it was out of the gathering state.
I was able to get the 'Update' button and in dashboard sharing view mode, the "Top content" metric area did not appear in the tiles. ✅

Clicking on 'Update' on the admin dashboard: ✅

• recreated the googlesitekit_post_type custom dimension in Analytics
• Update button no longer appears in admin dashboard
• Top content metric area re-appears on dashboard sharing

This is working as expected.
Moving ticket to approval.

9218.tested.good.mov

9218.tested.good.for.sharing.mov