Create the "Loyal visitors" 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 'Loyal visitors' 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 following data should be fetched from the Google Analytics Data API for the global date range selected on the Site Kit dashboard:
  • metric: activeUsers
  • dimension: newVsReturning
• Values should be calculated as follows:
  • (returning * 100) / (new + returning) % of (new + returning) total visitors.
• The percentage change figure (with a red for negative or green for positive highlight) should be calculated based on the 'previous' period before the selected date range.
• Existing GA4 datapoints and datastore infrastructure that is being added as part of the GA4 Reporting Epic should be used where available.

Implementation Brief

• Wait for Create the "New visitors" key metric widget tile #6244 to be merged.
• Create assets/js/modules/analytics-4/components/widgets/AnalyticsLoyalVisitorsWidget which exports the AnalyticsLoyalVisitorsWidget functional component.
• 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.
• It should render the info as per the designs in Figma.
  • Generic CSS class names (no "Loyal visitors" specific class names should be used since the styles will be reused by other components).
    • For e.g the "googlesitekit-key-metrics__title" class name can be used for the title.
  • Use the MetricTileNumeric.js component created in Create the "New visitors" key metric widget tile #6244 as a base.
  • Use the ChangeBadge.js component created in Create the "New visitors" key metric widget tile #6244 to show the +7.2% change value.
• Create assets/js/modules/analytics-4/components/widgets/AnalyticsLoyalVisitorsWidget.stories.js
  • Stories should cover following cases:
    • Loading
    • Zero Data
    • Error
    • Ready (data available and non-zero)
• All styles should live in the assets/sass/components/key-metrics folder.

Test Coverage

• Add tests for the AnalyticsLoyalVisitorsWidget component
• Add stories as VRT scenarios.

QA Brief

• QA is pretty much the same as for Create the "New visitors" key metric widget tile #6244:
  • With the userInput feature flag enabled, answer the questionnaire. For now, all widgets are displayed on the dashboard (which will change which future commits). As part of this issue, test the design and metric values of the New Visitors widget rendered in the Key Metrics section.
  • Test the generic Loyal Visitors stories within the Key Metrics widget section in Storybook.
  • Note 1: The mobile version currently does not display Key Metric tiles in a single column. A new issue should be created for this.
  • Note 2: There is no design for the loading state - we need to speak to UX and finalise a design and implement loading states for all widgets.
  • Note 3: Designing the error state for widget tiles is out of the scope of this issue. A new issue should be created for this.

Changelog entry

• Add "Loyal visitors" key metric widget tile.

[tofumatt]

ACs 👍🏻

[tofumatt]

IB ✅

[wpdarren]

QA Update: ⚠️

@eugene-manuilov You have included in the QAB that new tickets should be created for the three scenarios, have these been created or are you wanting QA to create them? Happy to do so. There are sections in the IB/AC that suggest we should be able to test the loading, zero data etc, so I am confused why we are creating new tickets to be honest.

Can I also clarify the calculation for the Loyal visitors key metric tile.

(returning * 100) / (new + returning) % of (new + returning) total visitors.

• Returning users from Google Analytics (for 28 days)
• New visitors from Site Kit dashboard (for 28 days) although there's a difference to what I see in Analytics (1.5K vs 1.6K)

Going on the formula in the AC.

141 (returning users) * 100 / 1500 (new visitors) + 141 (returning users) = 8.59% but on my site I see 8.1%

Update: I do not think the correct New visitors is appearing on the Site Kit dashboard.

I ran through the calculation again:

141 (returning users) * 100 / 1600 (new visitors from GA) + 141 (returning users) = 8.1%

What do you think?

Verified:

I have focused on the design with actual data on UA and GA4 dashboard view of the Loyal Visitors metric tile. This is because zero, gathering, loading, error states are not included in the engineering of this ticket as per the details in the QAB.

Note: there are some design issues on mobile which make the whole widget unreadable. Mentioned in the QAB.

• The Loyal Visitors metric tile matches that of the figma designs for desktop viewports.
• Tested the generic Loyal Visitors stories within the Key Metrics widget section in Storybook.

Screenshots

[wpdarren]

So, you see difference between what you see in Analytics and in the widget, right? When you check the Analytics console, do you select the same dates that are currently selected in the plugin?

@eugene-manuilov here's a screencast of what I am comparing between Analytics and the widget tile.

As you can see the difference is shown.

New visitors on SK is 1.5K whereas on Analytics it's 1.6K.

Loyal visitors calculation is incorrect for 1.5K, but if you calculate it on the Google Analytics at 1.6K the loyal visitors percentage is correct on the SK tile.

kmw.mp4

We can highlight this as an issue on #6244 and approve this ticket, but I would like to get at least confirmation that what I am seeing is a bug and needs fixing.

[eugene-manuilov]

Thanks, @wpdarren. I think there is an error. I'll create a follow up PR.

[eugene-manuilov]

@aaemnnosttv, could you please review #7173?

[aaemnnosttv]

@wpdarren back to you for another pass please 👍

[wpdarren]

@eugene-manuilov I still do not get the correct loyal visitors based on the calculation.

I am looking at the GA4 property for oi.ie

(returning * 100) / (new + returning) % of (new + returning) total visitors.

124 returning visitors in the last 28 days according to Analytics.

Here's my calculation:

124 * 100 / 1624 (124 + 1500) = 7.63%

As you can tell from the screenshot below, the percentage on the tile is 7.3%

I decided to look at Analytics and the new visitors (see first screenshot above) is 1.6K.

Here's my calculation:

124 * 100 / 1724 (124 + 1600) = 7.19%

So, even this calculation does not come to the 7.3% loyal visitors on the tile.

Can I assume that the calculation on the AC is correct?

[eugene-manuilov]

@wpdarren , ok, here is what we have in report rows:

So, for the current period we have: 1529 new users + 122 returning users + 16 and 11 users with unclear type. In total it is 1678 users, 122 of which are returning users that is 7.270560190703218% of the total number. That's how we get 7.3% in the plugin.

There is one weird thing in the report response though. There is the totals section that shows the exact numbers for all users in the current period and in the previous one:

For some reason the API returns completely incorrect total number of users in the totals section 🤔. Not sure how it calculates the Analytics server.

[wpdarren]

QA Update: ✅

Due to time and the fact that this is behind a feature flag, I am going to move this to approval. I think there's some investigation that needs to take place relating to the loyal visitors, total number of users and visitors. I will discuss with Eugene and Jimmy, and create a ticket if necessary.

• With the userInput feature flag enabled, answer the questionnaire.. As part of this issue, I tested the design and metric values of the New Visitors widget rendered in the Key Metrics section.
• Tested the generic Loyal Visitors stories within the Key Metrics widget section in Storybook.