Create the "New 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 'New 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 displayed as:
  • new 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

• Create assets/js/modules/analytics-4/components/widgets/AnalyticsNewVisitorsWidget which exports the AnalyticsNewVisitorsWidget functional component.
• It should render the info as per the designs in Figma.
  • Generic CSS class names (nothing "New 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.
• 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.
• To get the % change, compare the values from totals for the current and previous date range. See below for the Change component.
• Create assets/js/modules/analytics-4/components/common/Change.js which exports the Change functional component.
  • It accepts the following props:
    • previousValue: number
    • currentValue: number
  • Based on the previousValue and currentValue props, it should calculate the percentage change using the calculateChange function (found in assets/js/util/index.js) and render the change using the numFmt function (found in assets/js/util/i18n.js).
  • It should render the change "badge", for e.g + 10.5% with the appropriate styles when the change is positive or negative. Refer to the Figma designs for the styles.
• Parse the data coming from getReport to display the values as per the AC.
• Look into the possibility to having a assets/js/modules/analytics-4/components/common/MetricWidget.js component which accepts title and children as props which can be re used by other components. The MetricWidget component will be responsible to generate the widget markup and the title along with the rounded corners styles, and then children will be rendered below the title.
• Create assets/js/modules/analytics-4/components/widgets/AnalyticsNewVisitorsWidget.stories.js which contains the stories for the component.
• All styles should live in the assets/sass/components/key-metrics folder.

Test Coverage

• Add tests for the Change and AnalyticsNewVisitorsWidget components.

QA Brief

• With the userInput feature flag enabled, answer the questionnaire. For now, all widgets are displayed on the dashboard (which will change with 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 Metric Tile Numeric and the specific New 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

• Implement the New visitors key metric widget.

[tofumatt]

ACs here are good 👍🏻

[tofumatt]

IB ✅

I like the child component idea. We might want to call it something less generic, like MetricWidget or something, but looks good 👍🏻

[asvinb]

Thanks @tofumatt , I've tweaked the IB by replacing Widget by MetricWidget 👍

[hussain-t]

Key Metric widget components (skeleton) are created in #6313. So we don't have to create the AnalyticsNewVisitorsWidget component.

[hussain-t]

@asvinb @tofumatt, according to the AC, the criteria to render the widget tile is missing in the IB:

A new component should be created for the 'New visitors' Key metric widget and should be displayed within the Key Metrics widget area if it is selected (based on #6257

It should check if the selected metric depends on GA4 using the getKeyMetrics selector and render the elements.

[jimmymadon]

@marrrmarrr I did write the ACs here but I'm a bit confused as to how we should calculate the change percentage! 😄 Should this be:

1. Calculate percentage of new visitors vs total visitors for both date ranges and compare these percentages? E.g. if there were 50% new visitors in current date range and 25% new visitors in previous date range, the change would be +100%.
2. Simply use the new visitors figures for both date ranges?
3. Simply use the total visitors figures for both date ranges?

I believe we probably should be going for 1 here. The IB is suggesting we do 3 but that does not seem to be the purpose of this widget.

[marrrmarrr]

Hi @jimmymadon, I was more thinking of option (2), as I don't know if most users would understand the comparison of percentages very easily. We're mostly aiming to give them an idea of whether the portion of new visitors is increasing or decreasing, whereas option (1) would be more about whether the rate of growth of new visitors.

[mohitwp]

QA Update ⚠️

• Tested on dev environemt.
• Also, tested storybook story for NewVisitors.
• Note** - Mobile version of widget is not showing correctly. As per QAB mobile design is not part of this ticket annd we will create separate ticket for the issue.

@jimmymadon

Question 1) Is there any functional by which I can determine that value showing under "NewVisitors" widget is correct or not ?

Question 2) In Storybook for zero visitors we are not showing any percentage but on actual we are showing '0%". Which is correct ?

[jimmymadon]

@mohitwp

Question 1:
You can just compare the KMW data in Site Kit using GA4 Admin console for the exact same property and date range. In Analytics console, in the side panel, see Reports -> Audience -> Users -> New vs Returning.

Question 2:
I believe we should be showing a grey 0% badge here - this is what I had in my testing. There has been some change here and I will create a follow up PR to make sure this is what is shown:

[techanvil]

@mohitwp @jimmymadon as discussed on Slack I've created a followup issue to address Question 2: #7172, which can therefore be identified as a known issue here.

[mohitwp]

QA Update ⚠️

@jimmymadon @eugene-manuilov

1 > I'm not able to found any data as you mentioned in the comment.

You can just compare the KMW data in Site Kit using GA4 Admin console for the exact same property and date range. In Analytics console, in the side panel, see Reports -> Audience -> Users -> New vs Returning.

2> In QAB it is mentioned that dimension: newVsReturning. But I'm not getting this dimension under dimension list.

3> I found one matching value under Monetization>Retention. If we consider it values then as per formula `new of (new + returning) total visitors`` current value we are showing in widget is not correct.

4> Also, can we display abbreviation of numbers in small letters. k instead of K.

[mohitwp]

QA Update ✅

@jimmymadon

• Tested on main environment.
• Tested on dev environment.
• Also, tested storybook story for NewVisitors.
• Verified title design with Figma.

Note

1. Mobile version of widget is not showing correctly. As per QAB mobile design is not part of this ticket annd we will create separate ticket for the issue.
2. We have created 2 separate issue for the observations found in this ticket - #7172, and #7185.
3. Notice some data discrepancies between the values and asked few questions above related to it. As discussed in retro we will check and validate data in a separate ticket.

cc @wpdarren