Show button & tooltip to complete GA4 setup in Settings > Connected Services

[techanvil]

Feature Description

Following on from #5620, when the Analytics module is connected but GA4 is not setup, the “Analytics is connected” text should be replaced with the CTA button as implemented in #5620, but the button text will be “Connect Google Analytics 4” and clicking on the button will open the settings in edit mode.

Additionally, with the Analytics settings open in edit mode, the GA4 Property dropdown should have a blue callout displayed next to it containing explanatory text and a link to documentation.

• Design Doc: https://docs.google.com/document/d/1DeWo38lcV7lvLFfcmt-mQ0iaxzB4qfiPArs_yZzYkIM/edit?pli=1#heading=h.17l5a6ww33og
• Figma: https://www.figma.com/file/vMaCWwr6lpk4PrJWb7jIpz/GA4-Banner-Input?node-id=1285%3A2032

---

Acceptance criteria

• When the Analytics module is connected but GA4 is not setup:
  • The Analytics module on the Settings > Connected Services tab should no longer show the "Analytics is connected" text.
  • In its place, the CTA button as implemented in Update module headers in Settings > Connected Services #5620 should be displayed, but with the text “Connect Google Analytics 4”.
  • Clicking on the button should navigate to the Setup page for the module (this point will be implemented in Update module headers in Settings > Connected Services #5620).
  • On the Analytics Setup page, the GA4 Property dropdown should have a blue callout displayed next to it containing explanatory text and a link to documentation.
    • Explanatory text: Set up your Google Analytics 4 property here
    • Link text: Learn more
    • Link URL: {proxy}/support/?doc=ga4
      • Note, this should be the URL returned by select( CORE_SITE ).getDocumentationLinkURL( 'ga4' ).

Implementation Brief

• In assets/js/components/settings/SettingsActiveModule/Header.js:
  • Create a new variable named isGA4Connected which uses the useSelect hook to run the isModuleConnected() selector with analytics-4 passed as the property from the core/modules store (CORE_MODULES constant).
  • Locate the <p> tag responsible for displaying the Connected text (being updated in Update module headers in Settings > Connected Services #5620).
    • Besides the current conditions, do not display this <p> tag if:
      • The slug of the module is analytics. AND
      • isGA4Connected is falsey.
  • Locate the <Button /> component with the text Complete setup for { module_name } (being added in Update module headers in Settings > Connected Services #5620).
    • Display this button only if:
      • The module is not connected (accessible via ! connected) (Already implemented in Update module headers in Settings > Connected Services #5620). OR
      • The module is connected (accessible via connected). AND
        • The slug of the module is analytics. AND
        • isGA4Connected is falsey.
    • If the above new conditions are met (i.e. analytics module is connected but isGA4Connected is falsey), update the contents of the button with the string Connect Google Analytics 4 (translatable).
• In assets/js/modules/analytics-4/components/common/PropertySelect.js:
  • Extend the <PropertySelect /> component to accept a new className prop.
  • Update both instances of the select.googlesitekit-analytics__select-property element to have the className prop as an additional class if available, using the classnames library.
• In assets/js/components/JoyrideTooltip.js:
  • Extend the <JoyrideTooltip /> component to accept two new props:
    • className.
    • cta with the default as false.
    • onShow with the default as an empty function.
  • Pass the className and cta props as properties to the object in the steps array.
    

    site-kit-wp/assets/js/components/JoyrideTooltip.js

    Lines 38 to 47 in 856bf8b

    	const steps = [
    	{
    	title,
    	target,
    	content,
    	disableBeacon: true,
    	isFixed: true,
    	placement: 'auto',
    	},
    	];

  • Inside function of the callback prop of the <Joyride /> component, and call the onShow() function if the type (current state) is EVENTS.TOUR_START.
  • Make the content and dismissLabel as not required so that the tooltip component works without them if necessary.
• In assets/js/components/TourTooltip.js:
  • Update the div.googlesitekit-tour-tooltip element to have step.className as an additional class if available, using the classnames library.
  • Inside div.googlesitekit-tooltip-buttons:
    • Between the two buttons, render step.cta.
    • Make the last button only show up if primaryProps.title is truthy.
• In assets/js/modules/analytics/datastore/constants.js:
  • Export a new constant named HIDE_GA4_PROPERTY_SELECT_TOOLTIP with the value hideGA4PropertySelectTooltip (or something more relevant).
• In assets/js/modules/analytics/components/setup/SetupFormGA4Transitional.js:
  • Use the useSelect hook to run the getDocumentationLinkURL() selector from the core/site store with ga4 string passed as the selector parameter, and assign it to a variable named documentationURL.
  • Create a new function using the useCallback hook named markTooltipAsDisplayed which uses the useDispatch hook to dispatch the setValue action with the HIDE_GA4_PROPERTY_SELECT_TOOLTIP constant and true (boolean) as the properties.
  • Use the useSelect hook to run the getValue() selector from the core/ui store with the HIDE_GA4_PROPERTY_SELECT_TOOLTIP constant passed as the selector parameter, and assign it to a variable named hideGA4Tooltip.
  • Use the useSelect hook to run the isModueConnected() selector from the core/modules store with analytics string passed as the selector parameter, and assign it to a variable named isAnalyticsConnected.
  • Locate the <GA4PropertySelect /> component and pass a unique CSS class so that our callout/tooltip can target them.
  • Adjacent to the <GA4PropertySelect /> component, render a <JoyrideTooltip /> component:
    • Have Learn more string (translatable) as the content.
    • It should have the following props:
      • title: Set up a new GA4 property from here. string (translatable).
      • target: The CSS selector (class) that we passed onto the property selector above.
      • cta: A <Button /> component with:
        • googlesitekit-tooltip-button as className prop.
        • documentationURL as href prop.
        • _blank as target prop.
        • text prop.
      • className: A relevant CSS class. Add styles for this class to style the tooltip according to the Figma designs.
      • onShow: markTooltipAsDisplayed function.
    • Only display this component if isAnalyticsConnected is truthy and hideGA4Tooltip is falsey.

Test Coverage

• No tests need to be added/updated.
• Update VRT images if required.

QA Brief

This change is not affected by the ga4ActivationBanner feature flag

• Set up Analytics in Site Kit.
• We need to model the scenario where GA4 is not setup, so once Analytics is setup, delete the googlesitekit_analytics-4_settings option in WordPress. This can be done in a number of ways, for example:
  • Using the WP CLI with wp option delete googlesitekit_analytics-4_settings.
  • Running the DB query DELETE FROM wp_options WHERE option_name = 'googlesitekit_analytics-4_settings';
  • Installing the WP Console plugin and running delete_option( 'googlesitekit_analytics-4_settings' ); in the console.
• Go to Site Kit -> Settings -> Connected Services.
• Verify that the Analytics module displays a button that says Connect Google Analytics 4.
• Verify that clicking on it opens the Analytics settings edit view.
• The GA4 property select should not be disabled and there should be no toggle to "Activate" GA4
• The "Place Google Analytics 4 Code" switch should be enabled.
• If there is an available GA4 property in the account with a web data stream that matches the site URL, the GA4 property dropdown should preselect it.
• Beside the GA4 property dropdown, verify that a callout shows up that matches the text in the ACs.
• Verify that this callout matches the Figma designs. However, do note that the typography and text size is intentionally not same to keep it consistent with other callouts/tooltips.
• Verify that clicking on the "X" icon dismissed the callout.
• Verify that clicking on Learn More opens the appropriate documentation page in a new tab.

Changelog entry

• Show button to complete Google Analytics 4 setup in settings.

[tofumatt]

@techanvil Shouldn't the URL used be select( CORE_SITE ).getDocumentationLinkURL( 'ga4' )?

It looks like maybe this URL was used before the issue to consolidate the help links was merged.

Otherwise this looks good; if that's the only change needed feel free to update the URL required to just be select( CORE_SITE ).getDocumentationLinkURL( 'ga4' ) and then move this to IB 🙂

[techanvil]

Thanks @tofumatt, good shout. I've updated the AC to mention the selector 👍

[eugene-manuilov]

• Create a new variable named isGA4Setup which uses the useSelect hook to run the getPropertyID() selector from the modules/analytics-4 store (MODULES_ANALYTICS_4 constant). Use the double exclamation operator (!!) to get a boolean value returned from the selector.

@nfmohit, we can use isModuleConnected selector to understand whether the Analytics-4 module is connected. No need to get the propertyID value.

• Before displaying this <p> tag, display a <Button /> component with:

  • secondary as a prop (variation being introduced in Update module headers in Settings > Connected Services #5620) passed to it.
  • Connect Google Analytics 4 (translatable) text as content.

• Wrap the <Button /> component with a <Link /> component with a to prop with the value of /connected-services/analytics/edit string, so that it opens the edit view of the module.

• The <Link /> component containing the <Button /> component should be displayed only if all of the following conditions are met:

  • The slug of the module is analytics.
  • The module is connected (accessible via connected).
  • isGA4Setup is falsey.

• Only display this <p> tag if the above mentioned conditions are not met, i.e. for the analytics module, it should only show up if the module is connected and isGA4Setup is truthy.

This will be done in #5620, no need to re-post it here. What we need to mention here is that we need to change the module name from Analytics to Analytics 4 when GA4 is not connected and the header component renders settings header for the analytics module.

In assets/js/modules/analytics/components/settings/GA4SettingsControls.js:

• Use the useSelect hook to run the getDocumentationLinkURL() selector from the core/site store with ga4 string passed as the selector parameter, and assign it to a variable named documentationURL.
• ...

We have changed the the button works in 5620, now it sends users to the setup form instead of opening the settings form. We need to update IB to reflect this change.

@techanvil I think we also need to update AC for this ticket, right? If so, can you do it since you wrote it originally?

[techanvil]

Thanks for pointing this out, @eugene-manuilov. I had originally anticipated that we'd still be opening the edit view here but having read through the comments on #5620 I can see that we do need to update this issue too. As such, I have updated the AC, making the changes as follows:

• Clicking on the button should expand the module settings in edit mode.
• With the Analytics settings open in edit mode, the GA4 Property dropdown should have a blue callout displayed next to it containing explanatory text and a link to documentation.
• Clicking on the button should navigate to the Setup page for the module (this point will be implemented in Update module headers in Settings > Connected Services #5620).
• On the Analytics Setup page, the GA4 Property dropdown should have a blue callout displayed next to it containing explanatory text and a link to documentation.

@nfmohit apologies for not making this change earlier, but please could you go ahead and update the IB accordingly? Bear in mind the behaviour for navigating to the Setup page will be implemented in #5620, we just need to change the button text here and show the callout on the Setup page.

[nfmohit]

Thank you, @eugene-manuilov and @techanvil! I have updated the IB addressing the suggestions and the updates. Please take a look now.

[eugene-manuilov]

• In both assets/js/modules/analytics/components/setup/SetupFormGA4.js and assets/js/modules/analytics/components/setup/SetupFormGA4Transitional.js:

@nfmohit the SetupFormGA4 form will appear only when there are only GA4 properties for the selected account and no UA properties at all. This case is impossible because the Analytics module is already configured thus there are UA properties. So, we should show the tooltip on SetupFormGA4Transitional and SetupFormUA forms because they are displayed when there are UA properties.

• Locate the <GA4PropertySelect /> component and pass a unique CSS class so that our callout/tooltip can target them.
• Adjacent to the <GA4PropertySelect /> component, render a <JoyrideTooltip /> component having the props:

Perhaps it would be better to use a dedicated property to determine whether we need to render a tooltip or not? We can add something like tooltip={ true } to indicate that tooltip is needed and only then render a <JoyrideTooltip /> element within the <GA4PropertySelect /> component.

Also we need to make sure that we display the tooltip only once per page view. In other words, the user should see the tooltip only for the first time when they lend on the setup page and shouldn't see it again when they change the select account.

Last but not least, we need to make sure that we display the tooltip only when the Analytics module is already connected and not show it during the standard setup flow.

[nfmohit]

I've updated the IB according to the suggestions. Thank you, @eugene-manuilov!

[eugene-manuilov]

Thanks, @nfmohit. IB ✔️

[wpdarren]

QA Update: ❌

@techanvil @aaemnnosttv afraid I have found two issues while running through this:

1. Site has only a UA property set up on the site, but has a GA4 property within Analytics account. When I go to Settings, and click on the 'Connect Google Analytics 4' button, I am sent to the settings in edit mode as expected. The GA4 property on the account appears in the dropdown, but the confirm changes button is deactivated, so I am unable to save the change. You can see it in action on the screencast below.

ga-b1.mp4

2. Site has only a UA property set up on the site, and has no GA4 property within Analytics account. When I go to Settings, and click on the 'Connect Google Analytics 4' button, I am sent to the settings in edit mode as expected. Since there is no GA4 property, I click the dropdown to create a new property, and the process goes through and a GA4 property is created. On completion though the 'Connect Google Analytics 4' button still appears, rather than 'Connected' status. When I refresh though the 'Connected' status does appear. Felt this was a little confusing.

ga-b2.mp4

[wpdarren]

QA Update: ⚠️

@techanvil All my tests have passed but I have two small observations. We might want to create tickets and fix in the next release but I will leave this up to you to decide. You can see both issues in the screencast below.

1. Site has only a UA property set up on the site, but has a GA4 property within Analytics account. When I go to Settings, and click on the 'Connect Google Analytics 4' button, I am sent to the settings in edit mode as expected. The GA4 property on the account appears in the dropdown. The tooltip appears, but rather than closing it, I save the change. Analytics goes through the process and is connected. The issue is when you go back into edit Analytics settings, the tooltip appears against the GA4 property. I am assuming that this is because I didn't close it.

2. As you can see from my screencast, when editing the Analytics settings, the GA4 tool tip initially loads at the side of the property dropdown, and then a second later jumps to the top, and then when I scroll down, it jumps back to the side. Not a huge issue but a bit of an odd UX/UI experience I feel.

Would you like me to create tickets for these?

ga-b3.mp4

[techanvil]

Hi @wpdarren, good observations there. I do think we should fix these in the next release as they are fairly benign yet may require a bit of digging to fix, and it doesn't seem worth delaying this release further to fix them. Please can you go ahead and create tickets for them?

[wpdarren]

QA Update: ✅

Verified:

This latest round of testing was completed with the ga4ActivationBanner feature flag disabled.

• The Analytics module displays a button that says Connect Google Analytics 4.
• When clicking on the button it opens the Analytics settings edit view.
• The GA4 property select is not disabled and there should be no toggle to "Activate" GA4
• The "Place Google Analytics 4 Code" switch is enabled.
• If there is an available GA4 property in the account with a web data stream that matches the site URL, the GA4 property dropdown preselects it.
• Beside the GA4 property dropdown, a callout shows up that matches the text in the ACs.
  • This callout matches the Figma designs.
  • Clicking on the "X" icon dismissed the callout.
  • Clicking on Learn More opens the documentation page in a new tab.

Note: there are two observations which I highlighted above. These will have new tickets created for them.

Screencasts

ga4-qa2.mp4

ga4-qa1.mp4

[aaemnnosttv]

Great, thanks @techanvil and @wpdarren !