Implement the happy path for creating audiences and the custom dimension via the Setup CTA Banner

[techanvil]

Feature Description

Add the Setup CTA Banner to the dashboard, implement the happy path setup logic, and show the success state.

Note that this issue does not include redirecting to OAuth if necessary, this will be implemented separately via #8132.

Additionally, the success state can reuse the component introduced in #8238.

See setup CTA banner in the design doc.

---

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

Acceptance criteria

• If GA4 is connected and has non-zero data over the past 90 days (Site Kit’s maximum date range), then the Setup CTA banner created in Add the Setup CTA Banner initial view (Storybook) #8109 should be displayed directly below the Navigation Bar.
• Assuming the Analytics Edit scope is already granted, clicking on Enable groups should:
  • Display the "in progress" state with a spinner icon on the CTA button.
  • Sync the cached list of audiences (see Add REST and datastore APIs for audience caching #8486).
  • Check for any existing "User audiences" (audiences not created by default by Google Analytics nor those created by Site Kit) which have a non-zero user count over the past 90 days.
    • If one or more such User Audiences do exist, they should populate the list of configuredAudiences, ordered by user count over the past 90 days, to a maximum selection of two audiences.
    • Following this, if there are less than two audiences in the selection, and one or more of the Site Kit-created "new visitors" and "returning visitors" audiences already exist, they should be added to the list of configuredAudiences, to a total maximum selection of two audiences.
    • If the selection is still empty, the "new visitors" and "returning visitors" audiences should be created (using the details below) and added to the list of configuredAudiences.

      - displayName: “New visitors”
      - description: “People who visited the site for the first time”
      - membershipDurationDays: -1      // The longest duration, 540 days.
      - filterClauses<Array>:
        - clauseType: “INCLUDE”
        - simpleFilter:
          - scope: “AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS”
          - filterExpression:
            - andGroup:
              - filterExpressions<Array>:
                - orGroup:
                  - filterExpressions<Array>:
                    - dimensionOrMetricFilter:
                      - fieldName: “newVsReturning”
                      - stringFilter:
                        - matchType: “EXACT”
                        - value: “new”
                - orGroup:
                  - filterExpressions<Array>:
                    - notExpression:
                      - dimensionOrMetricFilter:
                        - fieldName: “groupId”
                        - stringFilter:
                          - matchType: “EXACT”
                          - value: “created_by_googlesitekit:new_visitors”
      
      // The "returning visitors" audience should be configured as above with the following differences.
      
      - displayName: “Returning visitors”
      - description: “People who have visited your site at least once before”
      - filterClauses<Array>:
          - ...
            - stringFilter:
                - value: “returning”
          - ...
            - stringFilter:
                - value: “created_by_googlesitekit:returning_visitors”

  • Check if the googlesitekit_post_type custom dimension is already created for the property, and if not, then create this custom dimension as per the definition already in the plugin:

    googlesitekit_post_type: {
        parameterName: 'googlesitekit_post_type',
        displayName: 'WordPress Post Type',
        description: 'Created by Site Kit: Content type of a post',
        scope: 'EVENT',
    }

  • The Setup CTA component should disappear.
  • The Setup Success Notice component should be displayed as per the Figma mock.
    • Clicking on the Got it button should dismiss the notice.
    • Clicking on the Show me button should do nothing for now but will eventually scroll to the new widget area.

Implementation Brief

• In includes/Modules/Analytics_4/Audience_Settings.php

  • Change the default value of configuredAudiences to null.

• The isPropertyPartialData and isAudiencePartialData selectors implemented in Add “partial data” states infrastructure #8141 determines whether the property has been in partial data state for the currently selected date range. This cannot be used directly here, as we need to know this for the "last-90-days".

  • A new set of selectors that computes essentially the same thing with a max range can be created for determining this, with essentially the same logic for isResourcePartialData the following alteration.
  • Instead of Getting the startDate from getDateRangeDates, get the referenceDate using getReferenceData selector, and calculate the start date using getPreviousDate function, with 91 days (90 days + one day offset).

• In assets/js/modules/analytics-4/datastore/audiences.js file, create enableAudienceGroup action.

  • Use syncAvailableAudiences to sync the list of available audience.
  • Get list of cached audiences using the getAvailableAudiences selector.
  • Filter the availableAudiences by USER_AUDIENCE type and perform the same partial data for 90-days check using the newly introduced selector. ie. userCreatedAudiencesWithData
  • Create a report request using getReport selector using the following args.
    • startDate: property creation time.
    • endDate: reference date.
    • dimensions: [ "audienceResourceName" ]
    • metrics: [ "totalUsers" ]
    • dimensionFilters: userCreatedAudiencesWithData
  • If there is no error and the report succeeds, take the dimensions with most total users.
  • If there are one or more audiences, add to a temporary audiencesToConfigure, up to two audience, ordered by the user count.
  • If the audiencesToConfigure is less than two, check if there are SITE_KIT_AUDIENCE type of audiences, and add them to the list up to two in the following priority order new-visitors, returning-visitors.
  • If audienceToConfigure is empty at this point, create the audiences defined in AC using the createAudience action and added to audienceToConfigure.
  • Check if the googlesitekit_post_type custom dimension already exists in the current property using the hasCustomDimensions selector.
  • If It doesn't exist, create it using createCustomDimensions action.
  • Finally, Set the audienceToConfigure as configuredAudiences using the setConfiguredAudiences and save the Settings by saveConfiguredAudiences.

• In the AudienceSegmentationSetupCTAWidget component:

  • Remove the title and description prop and inline the copy passed from the AudienceSegmentationSetupCTAWidget.stories to the component itself.
  • Get current property ID using getPropertyID selector.
  • Determine if the property is in partial data state for 90day range using the newly introduced selector.
  • Determine whether current user has analytics EDIT_SCOPE using the hasScope selector.
  • Get the currently configured audiences using getConfiguredAudiences selector.
  • Update the onEnableGroups callback to handle creating audience and custom dimensions.
    • call await enableAudienceGroup action here when ANALYTICS_EDIT_SCOPE is available after setting isSaving to true, so the CTA changes to Enabling groups with a spinner on the right of it. (already implemented).
  • If configuredAudiences has been set or isPropertyPartialData90Days is true, return null from the component.

• Create AudienceSegmentationSetupSuccessSubtleNotification in assets/js/modules/analytics-4/components/audience-segmentation/dashboard folder.

  • It should be similar to GA4AdSenseLinkedNotification. Make any additional CSS changes to match the look in Figma as needed using a new class. ie. googlesitekit-subtle-notification--audience-setup-success
  • It should be displayed when configuredAudiences is set and this notification has not been dismissed.

• Render the AudienceSegmentationSetupCTAWidget in DashboardMainApp when audienceSegmentation feature flag is enabled.

• Render the AudienceSegmentationSetupSuccessSubtleNotification in SubtleNotifications when audienceSegmentation feature flag is enabled.

Test Coverage

• Add test coverage for the newly introduced selectors.
• Add test coverage for enableAudienceGroupaction.
• Update any failing tests.

QA Brief

Prerequisites

In order to fully test this issue from a user's perspective, you will need the following:

• An Analytics property which does not have data over the past 90 days.
• Multiple Analytics properties which do have data over the past 90 days:
  • A property which has no user-defined audiences set up.
  • A property which has one user-defined audience set up which has data over the past 90 days, and any number of additional user-defined audiences which don't have data over the past 90 days.
  • A property similar to the one in the point above but which has two user-defined audiences which have data.
  • A property similar to the one in the point above but which has three user-defined audiences which have data.

Refer to the set up via the Analytics UI section in the design doc for some pointers on audience creation - note that these instructions are for manually creating the "new visitors" and "returning visitors" audiences, but they can be tweaked for creating other audiences with arbitrary criteria which will be needed for testing here. Once these audiences are created they will need to be populated by some site traffic which meets their criteria. For more info see the linked Google support page, and also the testing plan considerations section in the design doc for additional info on how to examine audiences in reports in the Analytics UI, so as to verify that the audiences are being populated with data (their total user counts can be examined to help verify audiences are sorted correctly).

Testing

• Set up Site Kit.
• Connect the Analytics property which does not have data over the past 90 days to verify the Setup CTA Banner is not displayed in this scenario.
• For the Analytics properties which do have data over the past 90 days:
  • Reset Site Kit, set it up again and connect the given property.
  • Verify the Setup CTA Banner is displayed on the main dashboard (please note the banner has already been tested in Storybook via Add the Setup CTA Banner initial view (Storybook) #8109 so we shouldn't need to get into any minor differences with the Figma design here).
  • Click the Enable groups CTA; the spinner should appear in the button while the setup flow continues.
  • Use the property which has no user-defined audiences to verify the flow where the "new visitors" and "returning visitors" audiences are created and added to the audience selection.
  • Use the property which has one user-defined audience with data to verify the flows where:
    • The single user-defined audience is added to the selection.
    • The "new visitors" or "returning visitors" audience is also added to selection when these exist (follow the set up via the Analytics UI to manually create these for testing this point).
  • Use the property which has two user-defined audiences with data to verify the flow where the audiences are added to the selection, ordered by total user count.
  • Use the property which has three user-defined audiences with data to verify the flow where the top two audiences are added to the selection, ordered by total user count.
  • Verify the googlesitekit_post_type custom dimension is created if it doesn't already exist (custom dimensions can be viewed for a given Analytics property under Admin > Property settings > Data display > Custom definitions, and see this Google support page for an entry point on custom dimension documentation).
  • Note that the SK-created audiences and custom dimensions can be archived via the Analytics UI in order to re-test their creation.
• Upon completion of each setup flow:
  • Verify the Setup CTA Banner disappears.
  • Verify the Setup Success Notice is displayed. This should broadly follow the Figma design, but should more closely align with the existing implementation for other banners of this style, for example see the Setup Success Subtle Notification (Ads) component in Storybook.

To verify the synced audiences and the resulting audience selections, run the following snippets in the JS console once the setup flow is complete for each scenario:

• Examine the synced audiences, these are returned by the getAvailableAudiences() selector:

googlesitekit.data.select("modules/analytics-4").getAvailableAudiences();

Example output:

• Examine the audience selection, this is returned by the getConfiguredAudiences() selector:

googlesitekit.data.select("modules/analytics-4").getConfiguredAudiences();

Example output:

• Cross-reference the values from getConfiguredAudiences() with the name property in the values returned by getAvailableAudiences() to determine which audiences are selected. This snippet can automate this process:

// Store the list of available audiences in a variable:
availableAudiences = googlesitekit.data
  .select("modules/analytics-4")
  .getAvailableAudiences();

// Look up the `displayName` for each audience in the audience selection:
googlesitekit.data
  .select("modules/analytics-4")
  .getConfiguredAudiences()
  .map(
    (name) =>
      availableAudiences.find((audience) => audience.name === name).displayName
  );

Example output:

Changelog entry

[jimmymadon]

@techanvil Just wanted to check if this issue deals with adding the fetched User Audiences or the newly created Site Kit audiences to the list of configuredAudiences. If so, then this issue will depend on the issue that saves the configuredAudiences in settings.

[jimmymadon]

@sigal-teller @marrrmarrr Since this issue is adding the new Success Notice component, I wanted to flag this as another component that is similar in looks to our existing SettingsNotice components (also used in other places on the dashboard like here) and similar in behaviour to our Setup Success Banner Notifications. However, our decision here is summarised by Sigal's comment in slack where we intend to create this new component for now and reuse it in other places in the Site Kit plugin where applicable in the future.

[sigal-teller]

@jimmymadon The new success notification I designed for Audience segmentation is intended to replace all successful setup notifications. We would like to keep consistent but I assume we’ll implement it gradually. This one should be replacing the large white banner that we have now. The other one you mentioned (the yellow one) is a warning notification and should be used for other purposes. I updated its design as well in recent designs.

[techanvil]

@techanvil Just wanted to check if this issue deals with adding the fetched User Audiences or the newly created Site Kit audiences to the list of configuredAudiences. If so, then this issue will depend on the issue that saves the configuredAudiences in settings.

Hi @jimmymadon - yes, this issue should deal with setting configuredAudiences as you've described. I've updated the dependencies for this and other affected issues (basically changing dependencies from #8130 to #8176 across the board). Thanks for the heads up.

[jimmymadon]

@bethanylang Should we create a separate issue to convert all the Setup Success banner components? This would be a super low P5 for now 😄

[jimmymadon]

@marrrmarrr @sigal-teller I had two small comments on the copy of the Setup Success Notice:

• It could use an additional article “an/the”.
  "We’ve added the audiences section to your dashboard! Get to know ..."
• Secondly, the script assumes that the audiences configured would be the New and Returning visitors that Site Kit created (which would be true in most cases). In the rare instance that users already have some random audiences, then these could vary and not necessarily be ones which tell them what attracts visitors to their site and what content helps bring them back. So are we happy to keep this wording as is?

[marrrmarrr]

@jimmymadon good catch, we can definitely update this a bit.
First of all, we should remove the mention of "audiences", as everywhere else we talk about visitor groups.
For the second part, let's focus on what the new panels actually show.
So I'd suggest:
"Success! You can now see how your site's traffic breaks down by different visitor groups"
"Get to know how different types of visitors interact with your site: where they come from, how long they stay, what content is most relevant to them, and much more."

[sigal-teller]

@jimmymadon Thanks for catching that. @marrrmarrr I think it's a bit too long for success notification text. we need to keep in mind that the user has just seen the CTA banner, we don't need to repeat the messages. The success notification purpose should mainly informing the user that the setup was successful and what are the next steps - there's a new section where he can see this data and we can point him there with "shoe me".
Maybe we can use your suggestion to update the CTA banner copy to be more general (we also use the same terminology that Jimmy spotted for the new and returning in the banner).

[techanvil]

Hi @jimmymadon, this AC is almost there, however, and with apologies for the moving target, the design doc has or may change a bit in a couple of relevant areas, which means the AC will need an update, but it will need to wait until these changes are finalised.

The current AC is slightly off with regard to what is now the old setup logic because it focuses on checking user-created audiences, thus missing the edge case where the new/returning visitors audiences are already created and should be considered for inclusion in the initial audience selection, plus the potential to include the "Purchasers" audience if it's "active".

However, this focus on the user-created audiences has made me realise that we should update the setup logic to raise the priority of user-created audiences for inclusion. As a result, I've proposed a refinement to the setup logic in the design doc. This needs to be approved by Mariya and Evan, who I've tagged on a comment thread.

Beyond this, there are a couple of points with regard to the audience configuration:

• We have that open thread on the design doc where we are considering appending a string along the lines of "Created by Google Site Kit - do not edit" to the descriptions.
• It's a small point, but it would be worth pointing out that the "Returning visitors" definition is only a diff of the "New visitors" definition and not the whole thing.

Lastly, we might want to hold off until the copy for the Setup Success Notice has been updated in Figma before moving this to IB (or, leave a note in the AC or IB section to bring attention to the fact that it's liable to change).

[zutigrm]

Hi @techanvil @jimmymadon just to note for the configureAudience object in AC, we need to have orGroup in andGroup before applying the dimensionOrMetricFilter filter in order for create-aduience endpoint to work. Also Value should be value, and adsPersonalizationEnabled is output only field, computed by Analytics, same like name parameter, so it isn't included in audience object when creating audience.

Found this out while working on #8108 . I added suggestion in design doc as well

- displayName: “New visitors”
- description: “People who visited the site for the first time”
- membershipDurationDays: -1      // The longest duration, 540 days.
- filterClauses:
    - clauseType: “INCLUDE”
    - simpleFilter:
        - scope: “AUDIENCE_FILTER_SCOPE_ACROSS_ALL_SESSIONS”
        - filterExpression:
            - andGroup:
                - filterExpressions<Array>:
                    - orGroup:
                        - filterExpressions<Array>:
                            - dimensionOrMetricFilter:
                                - fieldName: “newVsReturning”
                                - stringFilter:
                                    - matchType: “EXACT”
                                    - value: “new”

[techanvil]

Thanks for the spot(s) @zutigrm! I've accepted your suggested changes in the design doc, and tweaked it a little further.

[techanvil]

@jimmymadon I'm moving this to the Backlog to help clarify which issues still need to be finalised in the design doc.

[marrrmarrr]

@jimmymadon regarding the UI copy, let's shorten it like this:
Title remains unchanged: "Success! Visitor groups added to your dashboard"
Text below: "Get to know how different types of visitors interact with your site, e.g. which pages they visit and for how long."

[techanvil]

@jimmymadon, just a heads up that I have made this issue dependent on #8238 as we can reuse the component introduced there for the success banner (I also added a note about this in the Feature Description).

[jimmymadon]

Unassigning myself due to my break. c.c. @ivonac4 @bethanylang @techanvil

[techanvil]

The design doc has progressed to a point where this is now unblocked, so I've moved it out of the Backlog and will continue working on the AC myself.

[techanvil]

Hi @kuasha420, thanks for drafting this IB. A few points:

• It's worth a mention of the user count ordering when initially populating audiencesToConfigure.
• Also, we should only be creating the new/returning visitors audiences if there are no selectable user audiences - if the user has already created their own audience, we take it as an indicator that they've already engaged with the Audiences feature and don't need additional audiences at this point. They will still be able to create the new/returning audiences in the Selection Panel later on if they want to.
• So, in essence the first and third of the following points should be updated along these lines:

• If there are one or more audiences, add to a temporary audiencesToConfigure, up to two audience, ordered by the user count.
• If the audiencesToConfigure is less than two, check if there are SITE_KIT_AUDIENCE type of audiences, and add them to the list up to two in the following priority order new-visitors, returning-visitors.
• If audienceToConfigure is empty at this point, create the audiences defined in AC using the createAudience action and added to audienceToConfigure.

• Regarding these two points:

• If configuredAudiences is not empty or isPropertyPartialData90Days is true, return null from the component.
• ...
• It should be displayed when configuredAudiences is not empty this notification has not been dismissed.

• ... actually, configuredAudiences can be updated to be empty later down the line on a resync if the user has archived the configured audiences, and we want to avoid reshowing these banners in this scenario. I think we should update the default value of configuredAudiences to be null, and update the conditions to be "has been set (i.e. is an array)" rather than "is not empty".

site-kit-wp/includes/Modules/Analytics_4/Audience_Settings.php

Line 50 in 5ae9cc2

'configuredAudiences' => array(),

• It might be worth a mention of the in-progress state in the IB to make sure we capture it there and don't need to refer to the AC for that detail (we should show the spinner in the button).
• Please also complete the Test Coverage section.
• I wonder if it's worth increasing the estimate. Adding test coverage and actually testing the feature during development and QA could be fairly time consuming... I am somewhat on the fence here but we have gone over the estimate on a few of the more complex issues in this epic. Maybe this is a legitimate 19 that should be bumped to a 30... 🤔

[kuasha420]

@techanvil Thank you for the review. I've amended my IB to incorporate your feedback and bumped up the estimate.

The In Progress state for the spinner button is already implemented, in the component, did you mean the button should say In progress instead of current Enabling groups? In Figma, the copy is Enabling groups. Regardless, I've tweaked my IB to make it clearer.

Cheers.

[techanvil]

Thanks @kuasha420! Thanks for clarifying re. the in progress state. The copy Enabling groups is correct, we can keep that as it is.

I think this just needs the Test Coverage section to be added and it should be GTG.

[techanvil]

IB LGTM, thanks @kuasha420! ✅