Refactor the Audience Tiles to use new pivot report infrastructure

[benbowler]

Feature Description

As discussed on Slack, while we are initially implementing the Audience Tiles to use separate, per-audience reports to retrieve the cities and "top content" metrics (one report per audience per metric), we can reduce the number of reports needed by using pivot reports. This will allow us to retrieve metric data for all of the audiences in a single report (i.e., one report per metric).

We should add support for running pivot reports, and refactor the Audience Tiles to use them.

This is not critical to the release and can be done post-launch, hence the P2 priority.

Please also note this comment relating to the AudienceTile and AudienceTiles refactoring: https://github.com/google/site-kit-wp/issues/8484#issuecomment-2059400367

This ticket has been split from #8484, and only concerns updating the Audience Tiles to use the new pivot report infrastructure, which will be completed in that ticket.

---

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

Acceptance criteria

• The AudienceTiles component (introduced via https://github.com/google/site-kit-wp/issues/8136) should be refactored to use pivot reports for the "top cities" and "top content" metrics, thus reducing the corresponding request count by a factor of the number of selected audiences.
• The AudienceTiles and AudienceTile components should be further refactored so the reports that are retrieved in AudienceTiles are passed directly to AudienceTile, and the corresponding data parsing/extraction logic is moved from AudienceTiles to AudienceTile. Hopefully this logic can be simplified in the process.
• Additionally, refactor the AudienceTile stories to replace the hardwired mock data with generated mock report data.

Implementation Brief

Audience Segmentation Report Updates

• [ ] Update the assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTilesWidget.js component:

  • [ ] Update topCitiesReportOptions to the following report structure:

    startDate,
    endDate,
    dimensions: [ { name: 'city' }, { name: 'audienceResourceName' } ],
    dimensionFilters: {
        audienceResourceName: configuredAudiences,
    },
    metrics: [ { name: 'totalUsers' } ],
    pivots: [
        {
            fieldNames: [ 'city' ],
            orderby: [
                { metric: { metricName: 'totalUsers' }, desc: true },
            ],
            limit: 3,
        },
        {
            fieldNames: [ 'audienceResourceName' ],
        },
    ],

  • [ ] Update the topCitiesReport to use the new getPivotReport selector instead of getReportForAllAudiences, passing topCitiesReportOptions as the only prop.
  • [ ] Update topContentReportOptions to the following report structure:

    startDate,
    endDate,
    dimensions: [ { name: 'pagePath' }, { name: 'audienceResourceName' } ],
    dimensionFilters: {
        audienceResourceName: configuredAudiences,
    },
    metrics: [ { name: 'screenPageViews' } ],
    pivots: [
        {
            fieldNames: [ 'pagePath' ],
            orderby: [
                { metric: { metricName: 'screenPageViews' }, desc: true },
            ],
            limit: 3,
        },
        {
            fieldNames: [ 'audienceResourceName' ],
        },
    ],

  • [ ] Update the topContentReport to use the new getPivotReport selector instead of getReportForAllAudiences, passing topContentReportOptions as the only prop.
  • [ ] Update topContentPageTitlesReportOptions to the following report structure:

    startDate,
    endDate,
    dimensions: [ { name: 'pagePath' }, { name: 'pageTitle' }, { name: 'audienceResourceName' } ],
    dimensionFilters: {
        audienceResourceName: configuredAudiences,
    },
    metrics: [ { name: 'screenPageViews' } ],
    pivots: [
        {
            fieldNames: [ 'pagePath' , 'pageTitle' ],
            orderby: [
                { metric: { metricName: 'screenPageViews' }, desc: true },
            ],
            limit: 15,
        },
        {
            fieldNames: [ 'audienceResourceName' ],
        },
    ],

  • [ ] Update the topContentPageTitlesReport to use the new getPivotReport selector instead of getReportForAllAudiences, passing topContentPageTitlesReportOptions as the only prop.

• [ ] Remove the getReportForAllAudiences selector and all related code/tests.

• [ ] Update assets/js/modules/analytics-4/components/audience-segmentation/dashboard/AudienceTiles.js:

  • [ ] Replace all of the restructuring code with a single array filter, one for each report, that filters the report .rows, based on the dimensionValues[0].value === audienceResourceName, (audienceResourceName is from the parent map). This will return two rows per metric, one for each date range.
    • [ ] For topContentPageTitlesReport, filter the rows as in the previous bullet point, passing through all 15 top page titles and paths as the AudienceTilePagesMetric.js component will continue to do the selection of titles based on topContent and topContentTitles props.
  • [ ] Calculate the percentageOfTotalPageviews, by dividing the screenPageViews metric from the current date range, with the RESERVED_TOTAL of the screenPageViews metric over the same date range.
  • [ ] Pass the raw report rows array to each of the AudienceTile component props.

AudienceTile Updates

• [ ] Update AudienceTile to use the new prop structure defined above.
• [ ] Update AudienceTile stories to use this new pivot report data-mock functionality defined in #8484

Test Coverage

• Confirm existing tests pass, along with VRTs.

QA Brief

1. A round of smoke test to ensure that this feature has not changed anything in the Audience tiles widget. Also that data should be intact within those tiles.

2. Ensure that top cities are displaying in the widget. Verify the data from Google Analytics dashboard that it is displaying correctly.

3. Ensure that "Top content by pageviews" are displaying in the widget. Verify the data from Google Analytics dashboard that it is displaying correctly.

QA:Eng

In the browser dev tools check that pivot reports are loading and getting the response.

Changelog entry

• Refactor the Audience Tiles to use pivot reports, reducing the number of reports needed to retrieve the tile data.

[benbowler]

FYI, this ticket was split from #8484 on 17 May 2024. #8484 is a blocker.

[techanvil]

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

• The first report in AudienceTiles doesn't seem to need the update - it's already being retrieved via getReport() rather than getReportForAllAudiences(), and seems fine as it is AFAICT.
• The remaining reports should be updated to use the getPivotReport() selector in line with the proposed changes to https://github.com/google/site-kit-wp/issues/8484, assuming they have been made.
• The report with options topContentPageTitlesReportOptions should also be covered in the IB (including the refactoring of the restructuring code).
• A minor point but the report option code blocks are slightly misaligned in places.
• Another minor one, I think the point in Data Mock Updates about updating "AudienceTile stories to use this new data-mock functionality" should refer to "the new data-mock functionality introduced in #8484" for the sake of clarity.

[techanvil]

Thanks for the update @benbowler. It looks like these two points have been missed, though, please can you take a look?

• The report with options topContentPageTitlesReportOptions should also be covered in the IB (including the refactoring of the restructuring code).
• A minor point but the report option code blocks are slightly misaligned in places.

[techanvil]

Thanks Ben! This IB LGTM. :white_check_mark:

[ankitrox]

This is ticket is ready to be moved to CR, but it should be done once #8484 is merged and tested successfully as #8484 is the dependency for this and any changes in 8484 may lead to the changes in this task.

[techanvil]

Thanks @ankitrox - in cases like this, we don't tend to wait for the dependency to go through QA, simply having it merged is enough to move this to CR. Please remember to merge develop into this issue's branch, and retarget the PR first :)

[ankitrox]

Thanks @techanvil . I will move this to CR as soon as #8484 gets merged. I will also take care to update base branch and merge it to feature one.

Thank you.

[techanvil]

Hi @ankitrox, I have left a few comments on the PR, please take a look.

Additionally, reviewing the QAB I'd note that the code snippets aren't really needed - the feature is well enough integrated that it should be completely testable via the UI.

So, I'd suggest a bit of a rewrite with that in mind. Essentially it just needs a bit of a smoke test of the audience tiles to ensure that nothing has changed.

It would also be a useful to provide a brief QA:Eng section to verify that pivot reports can be seen in the devtools network tab.

[wpdarren]

@kelvinballoo as per our chat on Slack. I have assigned this to you. Once you have completed your testing please unassign yourself and we'll get an engineer to look over it for the QA:Eng part.

[kelvinballoo]

QA Update ⚠️

Despite being simple, this is a bit difficult to smoke test because a lot of things could be because of other tickets not deployed yet.

The tiles are appearing as how they were previously. ✅ That said, the tricky part is about verifying whether data is intact . Here are some observations to be reviewed. (For context, I used oi.ie property for testing)

ITEM 1: A round of smoke test to ensure that this feature has not changed anything in the Audience tiles widget. Also that data should be intact within those tiles.

• What are we actually meaning by intact data?
• Verifying the data from Analytics doesn't seem to correspond. Refer to the video attached.

https://github.com/google/site-kit-wp/assets/125576926/f9d8d6aa-59ba-4156-bc86-9a022e731367

---

ITEM 2: Ensure that top cities are displaying in the widget. Verify the data from Google Analytics dashboard that it is displaying correctly. The top cities are displaying but it's showing one of them as '(not set)'

The second city is (not set) On analytics, I could see the cities. Is it something to be set up in the BE?

---

ITEM 3:

Ensure that "Top content by pageviews" are displaying in the widget. Verify the data from Google Analytics dashboard that it is displaying correctly. I've verified the number from GA and the tile for the 'All visitors' at the 'Top content by pageviews' section and they matched for the first 2 but not the third.

The 3rd item is 245 on the tile. The 3rd item is 403 in Analytics

---

ITEM 4: I feel the results of the tiles are not properly matched.

Refer to the attached video for details

https://github.com/google/site-kit-wp/assets/125576926/e0a9b2d6-95a0-4813-8b8f-074075a04258

[techanvil]

Hey @kelvinballoo, what I'd suggest for the smoke test is to refer back to this comment I left on #8763 where I point out that we can see the same metrics elsewhere on the dashboard.

It's worth noting that all of the metrics for an audience are viewable elsewhere in Site Kit, so when viewing the "all visitors" audience, we can cross reference other widgets as a sanity check for the figures. To illustrate the point, here's a map of the metrics on the Audience Tile to the same metrics on Key Metric tiles and the All Traffic widget:

You can cross reference the metrics like this to check if anything has changed.

If the wider dashboard matches the All Visitors audience tile but you find discrepancies between the figures and what you see on Analytics, this can be raised as a separate issue for investigation.

[kelvinballoo]

QA Update ✅

Thanks @techanvil , that really helps.

I've verified this way and I can confirm that the tiles data is matching the data on the other part of the SK dashboard. Marking this as Pass but not moving this to approval yet since it's a 'QA Eng' ticket.

[techanvil]

QA:Eng :x:

While performing QA:Eng for this issue, I've had a horrible realisation that pivot reports aren't actually suitable for the audience tiles in the way we thought they were.

This has come to light while examining the report output for audiences which have visitors from different cities.

As can be seen in the current audience data for oi.ie, the "Mauritius users" audience has visitors from London:

While "Returning visitors" has visitors from Dublin, "(not set)", and Cork:

However when both of these audiences are visible, we only see Dublin, "(not set)", and Cork for both audiences, with no sign of London:

This was admittedly made harder to spot by the fact we have the open "2nd tile has no data" bug, https://github.com/google/site-kit-wp/issues/8921 which adds a bit of ambiguity. However the drilling into the actual reports as returned by the API indicates this is indeed the case and the reports are simply not returning the data in the way that we would like.

Essentially, each pivot in the report effectively results in a sub-query to retrieve all the values for that query similar to a regular report where the dimensionFilter and so forth come into play. It's then using the returned values as the values to pivot on. So when retrieving the top 3 cities while both audiences are included in the filter, it's always returning Dublin, "(not set)", and Cork, as these cities all have more totalUsers than London.

It's only when we remove "Returning visitors" from the query - meaning our report is filtering results for just the "Mauritius users" audience - that London is returned, because the other cities are being excluded - they are only associated with the other audience which is no longer included in the filter.

To help to understand this further here are some illustrative reports and their responses to compare:

Report request with a filter for the "Mauritius users" audience

```json { "dateRanges": [ { "endDate": "2024-07-04", "startDate": "2024-06-07" } ], "dimensionFilter": { "andGroup": { "expressions": [ { "filter": { "fieldName": "hostName", "inListFilter": { "values": ["oi.ie", "www.oi.ie"] } } }, { "filter": { "fieldName": "audienceResourceName", "inListFilter": { "values": ["properties/285794360/audiences/8278021604"] } } } ] } }, "dimensions": [ { "name": "city" }, { "name": "audienceResourceName" }, { "name": "hostName" } ], "keepEmptyRows": true, "metrics": [ { "name": "totalUsers" } ], "pivots": [ { "fieldNames": ["city"], "limit": "3", "orderBys": [ { "desc": "true", "metric": { "metricName": "totalUsers" } } ] }, { "fieldNames": ["audienceResourceName"], "limit": "2" } ], "property": "properties/285794360" } ```

Response for report filtered by the "Mauritius users" audience

```json { "pivotHeaders": [ { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "London" } ] } ], "rowCount": 1 }, { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "properties/285794360/audiences/8278021604" } ] } ], "rowCount": 1 } ], "dimensionHeaders": [ { "name": "city" }, { "name": "audienceResourceName" } ], "metricHeaders": [ { "name": "totalUsers", "type": "TYPE_INTEGER" } ], "rows": [ { "dimensionValues": [ { "value": "London" }, { "value": "properties/285794360/audiences/8278021604" } ], "metricValues": [ { "value": "1" } ] } ], "metadata": { "currencyCode": "USD", "timeZone": "America/Los_Angeles" }, "kind": "analyticsData#runPivotReport" } ```

Report request with a filter for the "Returning visitors" audience

```json { "dateRanges": [ { "endDate": "2024-07-04", "startDate": "2024-06-07" } ], "dimensionFilter": { "andGroup": { "expressions": [ { "filter": { "fieldName": "hostName", "inListFilter": { "values": ["oi.ie", "www.oi.ie"] } } }, { "filter": { "fieldName": "audienceResourceName", "inListFilter": { "values": ["properties/285794360/audiences/8281378703"] } } } ] } }, "dimensions": [ { "name": "city" }, { "name": "audienceResourceName" }, { "name": "hostName" } ], "keepEmptyRows": true, "metrics": [ { "name": "totalUsers" } ], "pivots": [ { "fieldNames": ["city"], "limit": "3", "orderBys": [ { "desc": "true", "metric": { "metricName": "totalUsers" } } ] }, { "fieldNames": ["audienceResourceName"], "limit": "2" } ], "property": "properties/285794360" } ```

Response for report filtered by the "Returning visitors" audience

```json { "pivotHeaders": [ { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "Dublin" } ] }, { "dimensionValues": [ { "value": "(not set)" } ] }, { "dimensionValues": [ { "value": "Cork" } ] } ], "rowCount": 151 }, { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "properties/285794360/audiences/8281378703" } ] } ], "rowCount": 1 } ], "dimensionHeaders": [ { "name": "city" }, { "name": "audienceResourceName" } ], "metricHeaders": [ { "name": "totalUsers", "type": "TYPE_INTEGER" } ], "rows": [ { "dimensionValues": [ { "value": "Dublin" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "139" } ] }, { "dimensionValues": [ { "value": "(not set)" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "59" } ] }, { "dimensionValues": [ { "value": "Cork" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "32" } ] } ], "metadata": { "currencyCode": "USD", "timeZone": "America/Los_Angeles" }, "kind": "analyticsData#runPivotReport" } ```

Report request with a filter for both audiences

```json { "dateRanges": [ { "endDate": "2024-07-04", "startDate": "2024-06-07" } ], "dimensionFilter": { "andGroup": { "expressions": [ { "filter": { "fieldName": "hostName", "inListFilter": { "values": ["oi.ie", "www.oi.ie"] } } }, { "filter": { "fieldName": "audienceResourceName", "inListFilter": { "values": [ "properties/285794360/audiences/8278021604", "properties/285794360/audiences/8281378703" ] } } } ] } }, "dimensions": [ { "name": "city" }, { "name": "audienceResourceName" }, { "name": "hostName" } ], "keepEmptyRows": true, "metrics": [ { "name": "totalUsers" } ], "pivots": [ { "fieldNames": ["city"], "limit": "3", "orderBys": [ { "desc": "true", "metric": { "metricName": "totalUsers" } } ] }, { "fieldNames": ["audienceResourceName"], "limit": "2" } ], "property": "properties/285794360" } ```

Response for report filtered by both audiences

```json { "pivotHeaders": [ { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "Dublin" } ] }, { "dimensionValues": [ { "value": "(not set)" } ] }, { "dimensionValues": [ { "value": "Cork" } ] } ], "rowCount": 151 }, { "pivotDimensionHeaders": [ { "dimensionValues": [ { "value": "properties/285794360/audiences/8281378703" } ] }, { "dimensionValues": [ { "value": "properties/285794360/audiences/8278021604" } ] } ], "rowCount": 2 } ], "dimensionHeaders": [ { "name": "city" }, { "name": "audienceResourceName" } ], "metricHeaders": [ { "name": "totalUsers", "type": "TYPE_INTEGER" } ], "rows": [ { "dimensionValues": [ { "value": "Dublin" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "139" } ] }, { "dimensionValues": [ { "value": "(not set)" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "59" } ] }, { "dimensionValues": [ { "value": "Cork" }, { "value": "properties/285794360/audiences/8281378703" } ], "metricValues": [ { "value": "32" } ] }, { "dimensionValues": [ { "value": "(not set)" }, { "value": "properties/285794360/audiences/8278021604" } ], "metricValues": [ { "value": "0" } ] }, { "dimensionValues": [ { "value": "Cork" }, { "value": "properties/285794360/audiences/8278021604" } ], "metricValues": [ { "value": "0" } ] }, { "dimensionValues": [ { "value": "Dublin" }, { "value": "properties/285794360/audiences/8278021604" } ], "metricValues": [ { "value": "0" } ] } ], "metadata": { "currencyCode": "USD", "timeZone": "America/Los_Angeles" }, "kind": "analyticsData#runPivotReport" } ```

As can be seen, when just "Mauritius users" is included in the filter, the cities pivot values are as follows:

    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "London"
            }
          ]
        }
      ],
      "rowCount": 1
    },

When just "Returning visitors" is included in the filter, the values are as follows:

    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Dublin"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "(not set)"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Cork"
            }
          ]
        }
      ],
      "rowCount": 151
    },

When both audiences are included in the filter, the values are again as follows, because they are the top 3 cities that are associated with either of the audiences.

    {
      "pivotDimensionHeaders": [
        {
          "dimensionValues": [
            {
              "value": "Dublin"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "(not set)"
            }
          ]
        },
        {
          "dimensionValues": [
            {
              "value": "Cork"
            }
          ]
        }
      ],
      "rowCount": 151
    },

Note that event if we completely remove audienceResourceName from dimensionFilter, the same three cities are returned - these are the top cities across all audiences.

The "cities" case has been illustrated but the general principle applies to the "top content" metric as well.

From what I've seen so far it doesn't seem possible to use a pivot report in the way we'd like to, returning a different selection of pivot values for each audience.

It could the case that I've missed something and there is some way to achieve this, and we can investigate this further at a later date, but for now we need to revert the changes in this issue.

[techanvil]

Note that due to the above, this issue will be closed as "not planned" and not included in the forthcoming release.

[nfmohit]

The PR #8969 that reverts all changes made by this issue has been merged. As discussed above, I'm closing this issue as not planned.