Create the "Most popular products by pageviews" key metric widget tile

[jimmymadon]

Feature Description

• Refer to the widget tables in the design doc and the PRD explaining the sources of data and other details.
• Figma mock for all widgets

---

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

Acceptance criteria

• A new component should be created for the 'Most popular products by pageviews' Key metric widget and should be displayed within the Key Metrics widget area if it is selected (based on Improve fetching key metrics based on user selected metrics #6257 and Register the new key metric widgets #6313).
  • The component should reflect the screenshot supplied above, see the Figma link above for more detail.
• The titles of the top three most viewed product pages should be displayed from the Google Analytics Data API based on the following metric/dimension and the global date range selected on the Site Kit dashboard:
  • metric: screenPageViews
  • dimension: pagePathPlusQueryString
  • Existing GA4 datapoints and datastore infrastructure that is being added as part of the GA4 Reporting Epic should be used where available.
• Filter only those pages which have “product” as the post type.
• The total screenPageViews for the top 3 pages having a post type of "product" should be displayed next to their respective titles as per the Figma mock.
• Existing GA4 datapoints and datastore infrastructure that is being added as part of the GA4 Reporting Epic should be used where available.
• UPDATE: Format the numbers as per the site's locale in the page-views column. See Format numbers in Key Metric Widget tiles #7190.

Implementation Brief

• Wait for Create the "New visitors" key metric widget tile #6244 and Create the "Top performing keywords" key metric widget tile #6251 to be merged.

• In includes/Core/Assets/Assets.php

  • Create a new method get_product_base_paths().
  • This method should return an array of base paths.
  • Inside this method, verify pretty permalinks are used. If not, we don't have base paths, and can't filter by base paths. Return an empty array in this case.
  • Create an empty array $product_base_paths.
  • Verify product post type exists, that the post type is public and has with_front set to true.
    • If so, add the rewrite base of the product post type to the $product_base_paths array.
    • Get the post type metadata with get_post_type_object('product') which returns a [WP_Post_Type](https://developer.wordpress.org/reference/classes/wp_post_type/) | null
    • The class includes a public property which is true if the post type is public.
    • The class has a $rewrite property which is an array, that has all required info about the rewrite base. The $post_type->rewrite['with_front'] can be used to determine if the plugin has a "base path".
    • $post_type->rewrite['with_front'] can be used to get the "base path"
  • Return the $product_base_paths array, but pass it through a apply_filter so other e-commerce plugins can register their own product base path, even if their product post type is not product.
  • Inside get_inline_base_data() add new item productBasePaths to $inline_data use the new created method to get the value.

• In assets/js/googlesitekit/datastore/site/info.js

  • Add a new entry for productBasePaths to RECEIVE_SITE_INFO reducer.
  • Add a new entry for productBasePaths to *getSiteInfo() resolver.
  • Add a new selector getProductBasePaths, therefore duplicate the getPostTypes and change the name and property.

• Create assets/js/modules/analytics-4/components/widgets/AnalyticsMostPopularProductsByPageviewWidget which exports the AnalyticsMostPopularProductsByPageviewWidget functional component.

  • It should render the info as per the designs in Figma.

  • Use the MetricTileTable component created in Create the "Top performing keywords" key metric widget tile #6251 as a base.

  • All styles should live in the assets/sass/components/key-metrics folder.

  • Use the new select( CORE_SITE ).getProductBasePaths(); selector to get the product base paths.

  • If getProductBasePaths() returns an empty array, return null for the whole widget component, as the widget can't be used if we don't have products.

  • Query the GA4 data store via the getReport selector with the metric and dimension as per the AC.

    • To get the selected date range, query the core/user data store via the getDateRangeDates with compare set to true.
    • Parse the data coming from getReport to display the values as per the AC.
    • Use the getErrorForSelector to get error state.
    • Use the hasFinishedResolution to get the loading state.

    const options = {
      ...
      metrics: [
        'screenPageViews'
      ],
      dimensions: [
        'pagePathPlusQueryString'
      ]
      ...
    }
  

  • Parse the data coming from getReport to display the values as per the AC.
  • Extend the options from above and add dimensionFilters. (see docs, 2. code example from docs is similar to what is needed here.).
    • For each entry in the productBasePaths array, create one expression that
      • uses pagePathPlusQueryString as a fieldName.
      • uses a stringFilter with the basePath as a value and BEGINS_WITH as a matchType.
      • See Docs: Dimensions Filter, FilterExpression, String Filter
    • Use a an orGroup to wrap the filter expressions
    • The dimensions filter will look similar to this:

{
    ...
    metrics: [
      'screenPageViews'
    ],
    dimensions: [
      'pagePathPlusQueryString'
    ],
    dimensionsFilter: {
        orGroup: {
            expressions: [
              {
                filter: {
                  fieldName: "pagePathPlusQueryString",
                  stringFilter: {
                    matchType: 'BEGINS_WITH',
                    value: 'product',
                    caseSensitive: false
                  }
                }
              }
            ]
        }
    }
    ...
}

• Format the numbers as per the site's locale in the page-views column. See Format numbers in Key Metric Widget tiles #7190.

• Create assets/js/modules/analytics-4/components/widgets/AnalyticsMostPopularProductsByPageviewWidget.stories.js

  • Stories should cover following cases:
    • Loading
    • Zero Data
    • Error
    • Ready (data available and non-zero)

Test Coverage

• Add tests for get_product_base_paths(). Should cover test cases for
  • product post type not registered
  • product post type registered but not pretty permalinks activated
  • product post type registered but not public
  • product post type registered but no rewrite base
  • product post type registered, is public and with rewrite base
• Add unit tests for the new AnalyticsMostPopularProductsByPageviewWidget
• Add Storybook Stories to VRT scenarios and update VRT reference images.

QA Brief

• With the userInput feature flag enabled, answer the questionnaire.
• Install and activate Woocommerce.
• Go to the permalink settings page and enter /en/why-%product%/ as the custom permalink structure for products. This will make the widget use /en/why- prefix when it gets report data to let you see some data in the widget.
  
• Go to the dashboard page and check the Most popular products by pageviews widget, it should show the most viewed pages whom URLs start from /en/why-.
• Then disable the Woocommerce plugin and go back to the dashboard page. You should not see the widget anymore.

Changelog entry

• Add support for WooCommerce/Google Analytics with a key metric widget for "Most popular products by pageviews".

[tofumatt]

ACs are good here, moving to IB 👍🏻

[derweili]

After talking with @aaemnnosttv and @jimmymadon we decided to solve the  Filter only those pages which have “product” as the post type. requirement by looking for the products base path (e.g. /product*/) and using this base path as a dimensions filter in the getReports.

[derweili]

Set the Estimate to 30. We are making use of dimensionsFilter here for the first time, so I think this may take a bit longer as there are probably some challenges to overcome which we don't know yet.

[tofumatt]

What's the thinking in using the 'product' post type? I assume it's a default for WooCommerce, but there's nothing mentioning it by name here and the whole "product" post type feels a bit arbitrary here. Like I'm just not sure why we're picking that specific one and what plugins I should expect this to work with here. I didn't see any mention of this in the design doc or PRD either, so I'm just a bit unclear as to what this is expected to work with.

It'd be helpful to know that here, because otherwise this feels a bit disjointed in terms of the actual use-case and how we would test this out, even in development.

I see @derweili wrote the IB here but I know he won't be around to answer right away, so I'm assigning this to @jimmymadon as you wrote the ACs here and also the design doc.

---

I think otherwise this looks good, but it just feels a bit abstract right now and I think it'd be worth clarifying things, possibly in the ACs as well, before moving this into the backlog.

Sorry for not catching that in the ACs, to be fair. 😓

[aaemnnosttv]

What's the thinking in using the 'product' post type?

@tofumatt It is mentioned in the PRD where the metrics are listed.

However, given that a site may have products/ecommerce without using CPTs, I agree that it won't always make sense to look for a product post type. A post type is something we can look at on the backend though to analyze its permalink structure in order to identify its prefix (assuming the site is even using pretty permalinks! Most do). The PRD also goes on to provide a fallback, if we can't determine what a product is.

Ultimately, we need to identify something we can use in the Analytics query to filter with and that limits us to find something in the path. Ideally, we could provide the post type to Analytics as a custom dimension but that probably isn't something we can safely do (worth looking into as a future enhancement though).

The implementation should be flexible so that it isn't specific to a plugin or post type but it's reasonable to use something generic as a starting point. From this perspective, perhaps maybe we should use a /product/ URL prefix segment (which could be filterable to support multiple) and would be decoupled from what type it relates to?

cc @marrrmarrr @felixarntz

[tofumatt]

I noticed it mentioned in the PRD—I was actually asking where that came from, sorry that wasn't clear. My thinking was the PRD seems to assume that 'products' as a post type always assumes ecommerce, and also doesn't cover any other Custom Post Type being the product a user would want to measure on their site.

If we're looking to start with something very generic I suppose these URLs and CPTs are something, but they just seem to invite a lot of confusion and support requests around the many cases I can see them not working.

Just from my own experience shopping on WordPress/WooCommerce sites, it does seem that /product/ is a common URL prefix—I'm guessing it's the default. That could be a good starting point, but I wonder if we should add a note/info text to this widget stating where the data comes from? Just to pre-empt any confusion around the data it's fetching.

What do you think about adding a little "Info" note or "Learn more" link here to a help doc explaining how we determine products here, @aaemnnosttv/@felixarntz/@marrrmarrr?

[aaemnnosttv]

One thing I noticed while testing here is that for a site with WooCommerce but no products that have been recorded in GA, it shows as if GA is in a gathering state. We may want to modify the wording here to be more clear.

[wpdarren]

QA Update: ⚠️

@jimmymadon I have two questions:

1. The links on other tiles point to Analytics, but this one points to the post. Is that expected?
2. As Evan mentioned above, if you have no products (but WooCommerce installed) the message is confusing. Feel it should say that you do not have any products, or, something along those lines. What do you think?

[jimmymadon]

@wpdarren

1. Yes - the popular content widget on the dashboard also links to Analytics. So while this is not clear from Figma or the AC, we should link to analytics.
2. Yes - I believe such a website will not have "other pages" - so falling back on to the popular content widget is not a good idea here anyways. We can simply have a message that says "Your site doesn't have any products."

c.c. @marrrmarrr Does the above sound good to you?

[marrrmarrr]

@jimmymadon this SG, I'd just slightly change the message to say "Site Kit hasn't detected any products on your site yet"

[aaemnnosttv]

The links on other tiles point to Analytics, but this one points to the post. Is that expected?

Yes - the popular content widget on the dashboard also links to Analytics. So while this is not clear from Figma or the AC, we should link to analytics.

We should link to Analytics.

if you have no products (but WooCommerce installed) the message is confusing. Feel it should say that you do not have any products, or, something along those lines. What do you think?

Yes - I believe such a website will not have "other pages" - so falling back on to the popular content widget is not a good idea here anyways. We can simply have a message that says "Your site doesn't have any products."

Regarding the wording here, I think it's important to note that this is based on nothing coming back from GA – we shouldn't make statements about there being no products on the site. It would be more accurate to say that we're "gathering data for products" or something like that. I'll defer to @marrrmarrr for the language to use but there's a key distinction to make that should help avoid confusion while remaining accurate if someone just added WC to their site or hasn't added any products yet, or products don't have any GA pageviews measured yet for whatever other reason 😄

[marrrmarrr]

@aaemnnosttv "gathering data" seems to imply that there are products and the user should just wait a bit to see the data, whereas in fact there is no data in GA (whether there are products or not, it seems like we can't establish with absolute certainty). So I'd suggest something like "Analytics has no data yet for products on your site" or similar.

[aaemnnosttv]

Back to you for another pass @wpdarren 👍

[wpdarren]

QA Update: ⚠️

@jimmymadon an observation I would like to share with you.

I answered the user input questions and selected Sell products or services for question 1. I had installed WooCommerce and also added the /en/why-%product%/ permalink as per the QAB.

According to the QAB:

Then disable the Woocommerce plugin and go back to the dashboard page. You should not see the widget anymore.

When the site has products this worked as expected, but when the site doesn't have any products the tile still appears when you disable WooCommerce. Is this expected?

[wpdarren]

QA Update ✅

Update on my comment above. I have had a conversation with @jimmymadon about this on Slack and we have agreed that a ticket needs to be created for the scenario I mention above where for a site that has no products, the tile does not disappear when WooCommerce (or any product post type) is disabled. Jimmy is going to create a ticket, and then it will be added to the bug bash board as a known issue. We need to think about the best way to implement this and don't have to do that now.

Verified:

• The tile matches what I see on the figma designs.
• The top 3 products are listed and are now linking to the Analytics page.
• The text for a site with no products is altered to Analytics doesn’t have data for your site’s products yet
• The data on the tile matches Analytics. Tested, 7,14,28 and 90 days reporting periods.

Screenshots