Implement Analytics snippet toggle(s) in setup flow if there is an existing tag

As part of the existing tag simplification, we are removing the enforcement of any property selection or tag placement. However, it is still crucial that we avoid placing the exact same tag twice on the page. To make this behavior more transparent to the user, and to allow them to still control / override it in these more complicated situations right away, the Analytics setup flow should start showing the toggle(s) to control the snippet placement if there is an existing tag.

In case of no existing tag, the snippet toggles should not be displayed similar to today, since at that point the snippet needs to be placed and there is no point in allowing the user to remove that, it would only break Analytics tracking.

---

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

Acceptance criteria

High-level summary: If there is an existing UA and/or GA4 tag on the site, the Analytics setup flow should render the corresponding toggle(s) to control tag placement, below the respective dropdown, as seen in this Figma design.

Wording and appearance

UA UseSnippetSwitch

• Appearance: See Figma, wording is specified below though. The design needs to support both versions, either it’s displayed as usual (before white background), or in the blue notice (e.g. needs to use blue text).
• Label: Place Universal Analytics code (like today)
• Note below if selected UA property is the same that the existing UA tag is for (i.e. toggle is off by default): A tag {existingTagID} for the selected property already exists on the site. 
Make sure you remove it if you want to place the same UA tag via Site Kit, otherwise they will be duplicated. (where {existingTagID} is the existing tag UA-..., which should match the selected property ID)
• Note below if selected UA property is different from what the existing UA tag is for (i.e. toggle is on by default): An existing tag {existingTagID} was found on the page. If you prefer to collect data using that existing UA tag, please select the corresponding account and property above. (where {existingTagID} is the existing tag UA-..., which should differ from the selected property ID)

GA4 UseSnippetSwitch

• Appearance: See Figma, wording is specified below though. The design needs to support both versions, either it’s displayed as usual (before white background), or in the blue notice (e.g. needs to use blue text).
• Label: Place Google Analytics 4 code (like today)
• Note below if selected GA4 property (or more precisely its web data stream’s measurement ID) is the same that the existing GA4 tag is for (i.e. toggle is off by default): A tag {existingTagID} for the selected property already exists on the site. Make sure you remove it if you decide to place the same GA4 tag via Site Kit, otherwise they will be duplicated. (where {existingTagID} is the existing tag G-..., which should match the selected property’s web data stream measurement ID)
• Note below if selected GA4 property (or more precisely its web data stream’s measurement ID) is different from what the existing GA4 tag is for (i.e. toggle is on by default): An existing tag {existingTagID} was found on the page. If you prefer to collect data using that existing GA4 tag, please select the corresponding account and property above. (where {existingTagID} is the existing tag G-..., which should differ from the selected property’s web data stream measurement ID)

Precise conditions

• If there is an existing UA tag and the primary property dropdown is for UA properties (or has a UA property selected, in case of a dropdown for both UA+GA4 properties), the UA UseSnippetSwitch should be shown below the three dropdowns.
  • It must be ensured that, if the user selects the same UA property that the existing UA tag is for, the UA UseSnippetSwitch is toggled off. If any other UA property is selected, it should be toggled on. The useExistingTagEffect should be relied on/enhanced as needed for that.
• If there is an existing GA4 tag and the primary property dropdown is for GA4 properties (or has a GA4 property selected, in case of a dropdown for both UA+GA4 properties), the GA4 UseSnippetSwitch should be shown below the two dropdowns.
  • It must be ensured that, if the user selects the same GA4 property that the existing GA4 tag is for (web data stream needs to be checked for that), the GA4 UseSnippetSwitch is toggled off. If any other GA4 property is selected, it should be toggled on. A GA4-specific useExistingTagEffect should be introduced for that, following similar behavior to the existing UA equivalent.
• If there is an existing UA tag and the blue notice with the UA properties dropdown is shown (i.e. the primary property is a GA4 property and the selected account also has UA properties), the UA UseSnippetSwitch should be shown below those two dropdowns in the notice.
  • If the blue notice is just for the “A UA property will be created” information (i.e. no dropdown), the toggle should not be present.
  • It must be ensured that, if the user selects the same UA property that the existing UA tag is for, the UA UseSnippetSwitch is toggled off. If any other UA property is selected, it should be toggled on. The useExistingTagEffect should be relied on/enhanced as needed for that.
• If there is an existing GA4 tag and the blue notice with the GA4 properties dropdown is shown (i.e. the primary property is a UA property and the selected account also has GA4 properties), the GA4 UseSnippetSwitch should be shown below that dropdown in the notice.
  • If the blue notice is just for the “A GA4 property will be created” information (i.e. no dropdown), the toggle should not be present.
  • It must be ensured that, if the user selects the same GA4 property that the existing GA4 tag is for (web data stream needs to be checked for that), the GA4 UseSnippetSwitch is toggled off. If any other GA4 property is selected, it should be toggled on. A GA4-specific useExistingTagEffect should be introduced for that, following similar behavior to the existing UA equivalent.
• To summarize the above logic: The UseSnippetSwitch should only appear if there is an existing tag for the property type (UA or GA4), and it should always appear below the relevant dropdown. In the case that the primary dropdown has both UA and GA4 properties, that means that depending on whether the user selects a UA or GA4 property there, the UseSnippetSwitch displayed below would be exchanged to reflect that selection. The most complex possible scenario here is that the selected Analytics account has UA and GA4 properties and there would be an existing UA tag and an existing GA4 tag - in that situation it would mean that both toggles will need to be displayed in the UI.

Notes on setting up new properties

• If the UA or GA4 property dropdown is displayed and there is an existing tag, the corresponding toggle below should always be shown. That is regardless of what is selected in the property dropdown.
• If the same property that matches the existing tag is selected, the toggle should be off by default (see above).
• If another property (or “Set up a new property”) is selected, the toggle should be on by default (see above).
• For now, no special copy should be used for the “Set up a new property” special case, that may be refined separately.

The PR for this issue should target the feature/existing-tag-simplification branch

Implementation Brief

Create and use GA4 useExistingTagEffect hook

• Create the hook in assets/js/modules/analytics-4/hooks/useExistingTagEffect.js
• The hook should be based on the existing UA useExistingTagEffect in assets/js/modules/analytics/hooks/useExistingTagEffect.js, with the code mostly the same.
• Select values from the MODULES_ANALYTICS_4 store, instead of MODULES_ANALYTICS.
• The GA4 measurement ID, retrieved via getMeasurementID, should be used in place of propertyID.
• Add a call to the new hook at the same point where the UA version is already called in SetupMain. https://github.com/google/site-kit-wp/blob/c701eeccfb058c225f1f31f74e776875ed9af4ba/assets/js/modules/analytics/components/setup/SetupMain.js#L94

Create and render UseSnippetSwitch component variants

As the text for UseSnippetSwitch needs to be changed for the usage in the Setup flow, but remain the same for the current usage in the Settings flow, we are going to create two variants, SetupUseSnippetSwitch and SettingsUseSnippetSwitch for use in each case.

In each of the following scenarios, to check for an existing tag:

• If the getExistingTag selector is being used, check the return value according to the logic seen in hasExistingTag to check if there is an existing tag.
• Otherwise, use the hasExistingTag selector to check if there is an existing tag.
• Select from the MODULES_ANALYTICS store for a UA tag, or the MODULES_ANALYTICS_4 store for a GA4 tag.

Create the new components

For the UA UseSnippetSwitch component:

• Refactor UseSnippetSwitch, removing the logic to display the text, with the text passed in as a prop instead.
• Create SettingsUseSnippetSwitch in the same folder, with the text logic extracted from UseSnippetSwitch. Render UseSnippetSwitch and pass the text in as a prop.
• Replace the existing use of UseSnippetSwitch with SettingsUseSnippetSwitch.
• Create SetupUseSnippetSwitch in the same folder. Refer to the AC for the text to be displayed depending on whether the selected property ID matches the existing tag property ID. Render UseSnippetSwitch and pass the text in as a prop.
  • Use getPropertyID and getExistingTag to select the appropriate values from the MODULES_ANALYTICS store.

Repeat the above for the GA4 UseSnippetSwitch, substituting MODULES_ANALYTICS_4 for MODULES_ANALYTICS and measurement ID for property ID.

Render Switches in Setup flow

The UA and/or GA4 SetupUseSnippetSwitch components need to be rendered in four different components: SetupFormLegacy, SetupFormUA, SetupFormGA4, SetupFormGA4Transitional: https://github.com/google/site-kit-wp/blob/c701eeccfb058c225f1f31f74e776875ed9af4ba/assets/js/modules/analytics/components/setup/SetupForm.js#L97-L102

SetupFormLegacy

• If there is an existing UA tag, render the UA SetupUseSnippetSwitch component after the existing controls.

SetupFormUA

• If there is an existing UA tag, render the UA SetupUseSnippetSwitch component after the existing controls, before the conditional block that renders the GA4PropertyNotice component.

SetupFormGA4

• If there is an existing GA4 tag, render the GA4 SetupUseSnippetSwitch component after the existing controls, before the conditional block that renders the GA4PropertyNotice component.

SetupFormGA4Transitional

• If the selected property type is UA (propertyType === PROPERTY_TYPE_UA) and there is an existing UA tag, render the UA SetupUseSnippetSwitch component above the conditional block that renders the GA4PropertyNotice component.
• Otherwise, if the selected property type is GA4 (propertyType === PROPERTY_TYPE_GA4) and there is an existing GA4 tag, render the GA4 SetupUseSnippetSwitch component at the same point.
• Within the GA4PropertyNotice block:
  • If the selected property type is GA4 and there is an existing UA tag, render the UA SetupUseSnippetSwitch component at the end of the fragment that’s conditionally rendered based on propertyType === PROPERTY_TYPE_GA4.
  • Otherwise, if the selected property type is UA and there is an existing GA4 tag, render the GA4 SetupUseSnippetSwitch component at the end of the fragment that’s conditionally rendered based on propertyType === PROPERTY_TYPE_UA.
• Remove the useEffect hook that sets the useSnippet values, as these values will now be managed by the SetupUseSnippetSwitch components in conjunction with useExistingTagEffect.

https://github.com/google/site-kit-wp/blob/0e8ad77fbf805bb76f306d4a55845bd06bad22e3/assets/js/modules/analytics/components/setup/SetupFormGA4Transitional.js#L95-L98

Storybook

• Update the corresponding “with tag” stories for the SetupForm* components to ensure they work properly and show the switches. This may be a bit time consuming, as some of the stories appear to no longer be working correctly.

Test Coverage

• Fix any broken tests. No new tests needed.

QA Brief

Please QA this issue on the feature/existing-tag-simplification branch; this is not yet merged into develop or main.

• Manually add UA and GA4 tag snippets to the site’s header.php.
• Start the Analytics Setup flow.

Note: Ensure the stream URL matches the site’s domain for GA4 tags, otherwise Site Kit won’t recognise the tag’s measurement ID.

UA-only flow

• Select an account with only UA properties.
• Verify that the snippet switch appears below the dropdowns as per the AC.
• Ensure the snippet switch toggles off when selecting a property which does match the existing tag.
• Ensure the snippet switch toggles on when selecting a property which does not match the existing tag.
• Ensure the snippet switch can still be toggled manually.
• Verify the snippet text conforms to the AC.

Example:

GA4-only flow

• Select an account with only GA4 properties.
• Verify that the snippet switch appears below the dropdowns as per the AC.
• Ensure the snippet switch toggles off when selecting a property which does match the existing tag.
• Ensure the snippet switch toggles on when selecting a property which does not match the existing tag.
• Ensure the snippet switch can still be toggled manually.
• Verify the snippet text conforms to the AC.

Example:

Combined UA and GA4 flow

• Select an account with both UA and GA4 properties.
• Verify that the snippet switches appear below the dropdowns as per the AC.
• Ensure the snippet switches toggle off when selecting a property which does match the existing tag.
• Ensure the snippet switches toggle on when selecting a property which does not match the existing tag.
• Ensure the snippet switches can still be toggled manually.
• Verify the snippet text conforms to the AC.

Example:

Storybook

• Check the “with tag” stories for the SetupForm* components to ensure they work properly and show the switches.

Changelog entry

• Include snippet toggle in Analytics setup flow whenever there is an existing tag.

[wpdarren]

Thanks @techanvil 👍

QA Update: ✅

Verified:

• Checked the “with tag” stories for the SetupForm components and they work properly and show the switches.

UA-only flow

• The snippet switches appear below the dropdowns as per the AC.
• The snippet switches toggle off when selecting a property which does match the existing tag.
• The snippet switches toggle on when selecting a property which does not match the existing tag.
• Confirmed that the snippet switches can still be toggled manually.
• The snippet text conforms to the AC.

Screenshots

GA4-only flow

• The snippet switches appear below the dropdowns as per the AC.
• The snippet switches toggle off when selecting a property which does match the existing tag.
• The snippet switches toggle on when selecting a property which does not match the existing tag.
• Confirmed that the snippet switches can still be toggled manually.
• The snippet text conforms to the AC.

Screenshots

Combined UA and GA4 flow

• Snippet switches appear below the dropdowns as per the AC.
• The snippet switches toggle off when selecting a property which does match the existing tag.
• The snippet switches toggle on when selecting a property which does not match the existing tag.
• Confirmed that the snippet switches can still be toggled manually.
• The snippet text conforms to the AC.

Screenshots

[felixarntz]

@techanvil

Seeing as hasExistingTag exists, unless the idea is to actually deprecate/remove it, I do think it’s still an appropriate choice if getExistingTag does not need to be used within the same scope.

Definitely, if you don’t need to use getExistingTag in a component, using hasExistingTag makes sense for just a bool check. But if you’re already using getExistingTag, it’s technically unnecessary to also use hasExistingTag. Either way it’s not a big deal.

However, I do believe it’s the correct approach to render the GA4 switch below the primary dropdown in that case, as the primary dropdown will have a GA4 property selected

Correct, my feedback was based on your copy/paste error version. Now that you’ve clarified, that sounds right.

At present, as far as I can tell, the useEffect in SetupFormGA4Transitional appears to be redundant anyway, as the useSnippet value will be true, unless there is an existing tag, in which case it will be managed by useExistingTagEffect (in conjunction with UseSnippetSwitch once this is implemented). It’s worth noting that the other related SetupForm* components don’t have a similar useEffect.

Correct. All your reasoning here makes sense, maybe my original comment on this wasn’t phrased correctly. My point was that that useEffect is more covered by what useExistingTagEffect than by what UseSnippetSwitch does. So yes, it is redundant based on useExistingTagEffect and should be removed.

IB ✅