Implement the Audience Creation Notice OAuth flow

[techanvil]

Feature Description

Implement the redirection to OAuth to grant the edit scope for creating an audience via the Audience Creation Notice. This should only include the happy path, the unhappy path will be implemented separately via #8166.

See audience creation in the design doc.

---

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

Acceptance criteria

• When the Audience Creation Notice is displayed in the Selection Panel and the user doesn't have the analytics.edit OAuth scope granted:
  • An additional message should be displayed within the Audience Creation Notice, at the bottom.
    • The message should follow the Figma design.
    • Its copy should read: Creating these groups require more data tracking. You will be directed to update your Analytics property.
    • It should have a Got it button that will dismiss the message.
  • Upon clicking Create for an audience, the user will be redirected to the OAuth flow.
  • Upon successfully returning from the OAuth flow:
    • The Selection Panel will be automatically be reshown.
    • The Audience Creation Notice will be visible but the additional message will no longer be shown.
    • The creation of the audience will automatically continue, with the Create CTA for the audience shown in the in-progress state with a spinner showing as usual.
  • Note that errors returned from the OAuth flow will be handled in the separate issue Implement the unhappy paths for the Audience Creation Notice #8166.

---

• Note that all copy should be verified with Figma as the source of truth.

Implementation Brief

• In assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/constants.js, add two new constants:
  • AUDIENCE_CREATION_EDIT_SCOPE_NOTICE_SLUG with the value audience-creation-edit-scope-notice.
  • AUDIENCE_CREATION_FORM with the value audience-creation-form.

Notice and Send to OAuth Flow

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/AudienceCreationNotice.js:
  • Get the dismissed state for the key AUDIENCE_CREATION_EDIT_SCOPE_NOTICE_SLUG, using the isItemDismissed selector.
  • Use the hasScope selector to check if the user has access to the EDIT_SCOPE:
    

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

    Lines 99 to 101 in ef83c39

    	const hasAnalyticsEditScope = useSelect( ( select ) =>
    	select( CORE_USER ).hasScope( EDIT_SCOPE )
    	);

  • If the item is not dismissed and the user does not have the edit scope, render an InfoNotice component matching the FIGMA designs.
    • The onDismiss, function should dismiss the AUDIENCE_CREATION_EDIT_SCOPE_NOTICE_SLUG item using dismissItem action.
    • Update assets/sass/components/analytics-4/audience-segmentation/_googlesitekit-audience-selection-panel.scss adding CSS to color the info notice to match the FIGMA designs, the "Got it" button should implement the recently added callout button style (see comment below).
  • Update the handleCreateAudience function of the Create buttons to redirect to the OAuth URL to add the new edit scope, only if the user does not already have this scope, (using this method).
    • Use the CORE_FORMS store setting autoSubmit to true and audienceToCreate to the value of audienceSlug, for the key AUDIENCE_CREATION_FORM, to handle the OAuth response.
    • Dispatch setPermissionScopeError with skipModal: true.
  • Refactor the handleCreateAudience function, moving it (and any required state) to the parent component AudienceSelectionPanel/index.js so that it can be called by the useEffect on returning from the OAuth flow.

Return from OAuth Flow

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/index.js, add a useEffect, check for the autoSubmit value in the CORE_FORMS store with the key AUDIENCE_CREATION_FORM, (modelled on this method). If this is true, and the edit scope is now present:
  • Trigger the selection panel to open using setValue( AUDIENCE_SELECTION_PANEL_OPENED_KEY, true );.
  • Call handleCreateAudience with the value of audienceToCreate in the store.
  • Reset the values of autoSubmit and audienceToCreate in this store.

Test Coverage

• Add tests to assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/index.test.js to test that the new notice displays correctly if the edit scope is missing, and does not show if the edit scope is granted.
• Add a new story when there is no edit scope and the notice is shown in assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/index.stories.js.

QA Brief

Prerequisites

• Archive the "new-visitors" and "returning-visitors" audiences in the Analytics console.
• Sync the audiences in Site Kit by running the following command in the browser console:

googlesitekit.data.dispatch( 'modules/analytics-4' ).syncAvailableAudiences()

• Delete the wp_googlesitekit_additional_auth_scopes entry from the wp_usermeta table if it exists. This entry contains the https://www.googleapis.com/auth/analytics.edit scope.
• After completing the above steps, refresh the page.

OAuth Flow

• Verify that the Missing Scope notice is displayed within the Audience Creation notice in the Selection Panel.
• Create a new audience and verify that you are redirected to the OAuth flow.
• Returning from the OAuth flow, verify that the Selection Panel is automatically reshown and the Audience Creation notice is visible without the Missing Scope notice.
• Verify that the audience creation continues as expected.

Dismissal

• Follow the steps outlined in the prerequisites to ensure the Missing Scope notice appears.
• Click the Got it button and verify that the Missing Scope notice is dismissed.
• Ensure that the Missing Scope notice does not reappear, even if the required scope is still missing.
• Verify the OAuth flow continues as expected.

Changelog entry

• Show a notice in the Audience Creation Notice when the Analytics edit scope is missing, and proceed directly to the OAuth flow upon clicking a CTA to create an audience.

[techanvil]

Hey @benbowler, thanks for drafting this IB. A few points:

  * [ ] Update `assets/sass/components/analytics-4/audience-segmentation/_googlesitekit-audience-selection-panel.scss` adding css to color the info notice to match the [FIGMA designs](https://www.figma.com/design/7pSrkEy8t00BcYRAi9LjjH/Audience-Segmentation?node-id=1821-26283&t=4fIzgS441r3N2crX-0).

It's also worth highlighting that the "Got it" button should implement the recently added callout button style as seen here in Figma, with an example here of how to implement it (but using different colours, the example is the "success" variant). Note that we have a couple of issues (#9063, #9064) to provide reusable components for these buttons, so this may be an interim implementation although #9063 has already landed in the EB.

• Update the onClick function of the Create buttons to redirect to the OAuth URL to add the new edit scope using this method:
  ...
  • Set the redirectURL using addQueryArgs setting a query argument for panels which equals audience-selection.

I'm not sure if this simply a mistake with the lines selected for the code snippet, but the standard pattern for redirecting to the OAuth flow is to dispatch the setPermissionScopeError() action with skipModal: true. Also, we use a snapshotted CORE_FORMS store value, typically autoSubmit, to control the auto-continuation of the item creation on the way back from OAuth.

We should reuse this pattern here, certainly the use of setPermissionScopeError(), and also, although I do see a benefit of using a query param for the state (that being, it's only actually set on the return leg of the journey), I would say it's preferable to use the CORE_FORMS approach as well for the sake of consistency.

For reference here are the relevant lines in MetricsSelectionPanel/Footer:

site-kit-wp/assets/js/components/KeyMetrics/MetricsSelectionPanel/Footer.js

Lines 153 to 179 in 3cce2fa

	setValues( FORM_CUSTOM_DIMENSIONS_CREATE, {
	autoSubmit: true,
	} );
	if ( ! hasAnalytics4EditScope ) {
	// Let parent component know that the user is navigating to OAuth URL
	// so that the panel is kept open.
	onNavigationToOAuthURL();
	// Ensure the panel is closed, just in case the user navigates to
	// the OAuth URL before the function is fully executed.
	closePanel();
	setPermissionScopeError( {
	code: ERROR_CODE_MISSING_REQUIRED_SCOPE,
	message: __(
	'Additional permissions are required to create new Analytics custom dimensions',
	'google-site-kit'
	),
	data: {
	status: 403,
	scopes: [ EDIT_SCOPE ],
	skipModal: true,
	redirectURL,
	},
	} );
	}

And here's the entry point where it's handled upon return from OAuth. Note this uses a separate hook that's invoked in DashboardMainEffectComponent, but I think we can still take your suggested approach of adding a useEffect() directly to AudienceSelectionPanel, please see what you think when considering this example:

site-kit-wp/assets/js/modules/analytics-4/hooks/useCreateCustomDimensionsEffect.js

Lines 45 to 84 in 3cce2fa

	const hasAnalyticsEditScope = useSelect( ( select ) =>
	select( CORE_USER ).hasScope( EDIT_SCOPE )
	);
	const autoSubmit = useSelect( ( select ) =>
	select( CORE_FORMS ).getValue(
	FORM_CUSTOM_DIMENSIONS_CREATE,
	'autoSubmit'
	)
	);
	const { setValues } = useDispatch( CORE_FORMS );
	const { createCustomDimensions } = useDispatch( MODULES_ANALYTICS_4 );
	useEffect( () => {
	async function createDimensionsAndUpdateForm() {
	await createCustomDimensions();
	setValues( FORM_CUSTOM_DIMENSIONS_CREATE, {
	isAutoCreatingCustomDimensions: false,
	} );
	}
	if (
	isKeyMetricsSetupCompleted &&
	isGA4Connected &&
	hasAnalyticsEditScope &&
	autoSubmit
	) {
	setValues( FORM_CUSTOM_DIMENSIONS_CREATE, {
	autoSubmit: false,
	isAutoCreatingCustomDimensions: true,
	} );
	createDimensionsAndUpdateForm();
	}
	}, [
	autoSubmit,
	createCustomDimensions,
	hasAnalyticsEditScope,
	isKeyMetricsSetupCompleted,
	isGA4Connected,
	setValues,
	] );

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/index.js, add a useEffect, if the panels query argument is set to audience-selection, trigger the selection panel to open using setValue( AUDIENCE_SELECTION_PANEL_OPENED_KEY, true );, then remove this query argument from the current page URL.

This doesn't handle the auto-continuation of the audience creation, it's only specced to open the selection panel. We'll need to explicitly continue creating the audience as well.

[techanvil]

Thanks @benbowler, this IB is most of the way there. A few last points:

• In assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/constants.js, add a new constant AUDIENCE_SEGMENTATION_EDIT_SCOPE with the value, audience-creation-edit-scope.

A minor point, but I would suggest renaming this constant to, say, AUDIENCE_CREATION_FORM, to be more consistent with other similar scenarios and also to remove ambiguity - AUDIENCE_SEGMENTATION_EDIT_SCOPE sounds like it could be an OAuth scope value.

• Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceSelectionPanel/index.js, add a useEffect, check for the autoSubmit value in the CORE_FORMS store with the key AUDIENCE_SEGMENTATION_EDIT_SCOPE, (modelled on this method). If this is true:

This would come out in the wash during implementation, but we might as well be clear that the condition should be autoSubmit being set and the edit scope being present. Otherwise with just autoSubmit set the logic will run immediately when the flag is set on the way out to the OAuth flow.

• Call handleCreateAudience with the value of continueAudienceCreation in the store.

This needs a little more thought as handleCreateAudience() is defined in AudienceAudienceCreationNotice.js, not AudienceSelectionPanel/index.js. Although we could have an additional useEffect() in AudienceAudienceCreationNotice, I imagine the better course would be to lift handleCreateAudience() (and the state it uses) into AudienceSelectionPanel. WDYT?

[techanvil]

Thanks for updating the IB @benbowler. Looks good; I've made a small tweak to align the constant names with my previous comment, and also changed the name continueAudienceCreation, which sounds like a boolean, to audienceToCreate which seems less ambiguous.

The IB LGTM ✅

[kelvinballoo]

QA Update ✅

The following were verified good. Moving ticket to approval.

• When the Audience Creation Notice is displayed in the Selection Panel and the user doesn't have the analytics.edit OAuth scope granted:
  An additional message displays within the Audience Creation Notice, at the bottom.

  • The message follows the Figma design. ✅
  • Its copy reads: Creating these groups require more data tracking. You will be directed to update your Analytics property. ✅
  • It has a Got it button that will dismiss the message. ✅

• Upon clicking Create for an audience, the user is redirected to the OAuth flow. ✅

• Upon successfully returning from the OAuth flow:

  • The Selection Panel is automatically be reshown. ✅
  • The Audience Creation Notice is visible and the additional message is no longer shown. ✅
  • The creation of the audience continues automatically, with the Create CTA for the audience shown in the in-progress state with a spinner showing as usual. ✅

Create.new.audience.with.new.auth.flow.mov

2nd.audience.created.successfully.mov