VCST-5337: GA reports support

Directory.Build.props

@@ -2,7 +2,7 @@
 <Project>
   <!-- These properties will be shared for all projects -->
   <PropertyGroup>
-    <VersionPrefix>4.1003.0</VersionPrefix>
+    <VersionPrefix>4.1004.0</VersionPrefix>
     <VersionSuffix></VersionSuffix>
     <VersionSuffix Condition=" '$(VersionSuffix)' != '' AND '$(BuildNumber)' != '' ">$(VersionSuffix)-$(BuildNumber)</VersionSuffix>
   </PropertyGroup>

README.md

@@ -3,12 +3,16 @@ Google Analytics 4 module allows you to assign Google Analytics Measurement Id a
 
 The module supports both direct GA4 integration and advanced Google Tag Manager integration for centralized tag management.
 
+It also **reads back** from GA4 through the Data API, so other modules can ask what the collected events say — see [Reading analytics data](#reading-analytics-data).
+
 ## Key Features
 1. Store Configuration.
 1. Measure ecommerce with Vue B2B Theme and Virto Storefront.
 1. Google Tag Manager integration for advanced tracking and tag management.
 1. Ready for integration with other sales channels.
 1. Application menu.
+1. Reporting API: read collected events back from GA4 (`IAnalyticsService`) for other modules to build on.
+1. Staged connection diagnostics for the reporting setup.
 
 ## Screenshots
 ![Google Analytics 4](docs/media/ga4-realtime.png)
@@ -107,6 +111,23 @@ The module adds `Google Analytics` link into Application menu. It redirects to G
 
 ![Google Analytics 4 App Menu](docs/media/app-menu.png)
 
+## Reading analytics data
+
+Besides tagging, the module can **read** GA4 through the Data API (`runReport`) and expose the result in-process as
+`IAnalyticsService` — events, dimensions, filters and date ranges, with no domain concepts of its own. It has no
+GraphQL surface; consumers build their own fields on top of it (the first is
+[VirtoCommerce.SalesRep](https://github.com/VirtoCommerce/vc-module-sales-rep), which turns it into rep-facing
+customer insights).
+
+Reporting needs two extra store settings — the numeric **GA4 property id** and a report cache lifetime — plus
+**Application Default Credentials** with the `analytics.readonly` scope and Viewer on the property. There is
+deliberately no credential *setting*, so no key material is stored in the platform database.
+`POST api/googleanalytics/{storeId}/diagnostics` runs a staged checklist that names exactly what is missing.
+
+Two limits are properties of the source rather than of this module: GA4 takes up to **24-48 hours** to process
+events, and reports are **aggregates** whose finest time dimension is the hour. Setup steps, the settings, the
+credential prerequisites and the diagnostics payload are documented in [docs/index.md](docs/index.md).
+
 ## Documentation
 * [Google Analytics 4](https://developers.google.com/analytics/devguides/collection/ga4)
 * [Google Tag Manager](https://developers.google.com/tag-platform/tag-manager)

docs/index.md

@@ -68,6 +68,59 @@ Google Analytics 4 module defines the following store settings:
 1. **GoogleAnalytics4.MeasurementId** - Google Analytics 4 Measurement ID (e.g., `G-XXXXXXXXXX`)
 1. **GoogleAnalytics4.GTMContainerId** - Google Tag Manager Container ID (e.g., `GTM-XXXXXXX`)
 
+### Reporting (Data API) settings
+
+These settings are **not public** — they are never returned by the anonymous `GET /api/googleanalytics/{storeId}`
+endpoint. They configure *reading* from GA4 (see [Reading analytics data](#reading-analytics-data)), and are only
+needed if another module consumes `IAnalyticsService`.
+
+1. **GoogleAnalytics4.DataApi.PropertyId** - the **numeric** GA4 property id to report on (GA4 Admin > Property
+   Settings > Property Details), e.g. `123456789`. This is *not* the `G-XXXXXXXXXX` measurement id.
+1. **GoogleAnalytics4.DataApi.CacheTtlMinutes** - how long a successful report is cached per store and query
+   (default `60`). Data API tokens are metered per property per day, so caching is a quota requirement rather than
+   tuning; failed reports are cached for a fixed 60 seconds so a misconfiguration cannot burn quota. Set it to
+   **`0`** to read Google on every call, and note that the platform's own `Caching:CacheEnabled=false` is honoured
+   here too - both are for diagnosing stale reporting data, not for normal operation. The cache key is the store
+   plus the query's *dates*, so two reads differing only in time of day share one entry.
+
+## Reading analytics data
+
+Besides tagging, the module can **read** GA4 through the Data API (`runReport`) and expose the result in-process as
+`IAnalyticsService` (events, dimensions, filters and date ranges — no domain concepts). It has no GraphQL surface;
+consumers build their own fields on top of it.
+
+### Prerequisites
+
+1. Set **GoogleAnalytics4.DataApi.PropertyId** for the store.
+1. Enable the **Google Analytics Data API** (`analyticsdata.googleapis.com`) in the Google Cloud project the
+   credential belongs to.
+1. Provide credentials through **Application Default Credentials** — there is no credential setting. In a cluster
+   this is workload identity or the metadata server; with a key file it is `GOOGLE_APPLICATION_CREDENTIALS`. For
+   local development, the login must include the analytics scope (a plain `gcloud auth application-default login`
+   does **not**, and every call then fails with `PermissionDenied`):
+
+   ```sh
+   gcloud auth application-default login --scopes="https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid"
+   gcloud auth application-default set-quota-project <your-gcp-project>
+   ```
+
+1. Grant the credential's principal the **Viewer** role on the GA4 property (GA4 Admin > Property access management).
+1. Register any **user-scoped custom dimensions** a consumer filters on in GA4 Admin > Custom definitions.
+   Registration is **not retroactive** — only events collected after it are reportable.
+
+### What this source can and cannot answer
+
+* GA4 processes events for up to **24-48 hours** before `runReport` can see them. "No rows" right after tagging is
+  the expected state, not a fault.
+* Reports are **aggregates**: the finest time dimension is `dateHour`, so every timestamp is an hour-bucket start,
+  never an event time. GA4 reports those buckets in the **property's** reporting timezone; the module converts them
+  to UTC using the zone GA returns with each response, so `OccurredAt` is a real UTC instant. The `from`/`to` bounds
+  of a query are still sent as UTC dates, so a range *edge* can differ by up to a day from the property's calendar.
+* Coverage is a **sample**, not a record — ad blockers and consent mode mean GA sees a subset of real activity.
+* GA4 suppresses rows for small cohorts when **Google Signals** is enabled, which is exactly the shape of a
+  single-customer query. A property used for per-customer reporting typically needs Signals off.
+
+
 ## Rest API
 
 ### Get Google Analytics Settings 
@@ -91,5 +144,41 @@ Response:
 ### Update Google Analytics Settings
 Use Store API to provide management above Google Analytics Settings. 
 
+### Run connection diagnostics
+
+Endpoint: `/api/googleanalytics/{storeId}/diagnostics`
+
+Method: `POST`, permission: `googleanalytics:access`
+
+Runs a staged check of the reporting setup and returns one row per stage — `configuration`, `credentials`,
+`apiAccess`, `customDimensions`, `reportCompatibility`, `realtime`, `processedData` — each with a `status` of
+`Passed`, `Warning`, `Failed` or `Skipped`, a message naming the fix, and an optional `detail`. A failure in one of
+the first three stages marks the rest `Skipped`, so the response shape never varies. Diagnostics bypasses the
+response cache and reads Google directly.
+
+Key material never reaches the response: the `credentials` stage reports only the *kind* of credential in use.
+`detail`, however, forwards the underlying error verbatim, and Google's own messages can name the environment
+around the credential — the path in `GOOGLE_APPLICATION_CREDENTIALS`, or the Cloud project behind a disabled
+API. The endpoint is gated on `googleanalytics:access` for that reason.
+
+The request body is optional; every field defaults, so `{}` runs a bare connectivity check:
+
+```jsonc
+{
+  // user-scoped custom dimensions to verify, WITHOUT the customUser: prefix
+  "userDimensionNames": ["contact_id", "organization_id", "session_kind"],
+  "eventNames": ["search", "view_item", "login"],   // events you expect to be collected
+  "reports": [{                                     // report shapes to compatibility-check
+    "name": "searchTerms",
+    "dimensionNames": ["eventName", "dateHour", "searchTerm"],
+    "metricName": "eventCount",
+    "eventNames": ["search", "view_search_results"]
+  }],
+  "includeLiveData": true                           // false skips the two data stages, saving Data API quota
+}
+```
+
+Empty results are reported as `Warning`, not `Failed` — "no data yet" is a state, not a fault.
+
 ## Troubleshoting 
 [Enable debug mode](https://support.google.com/analytics/answer/7201382) so you can see events in realtime and more easily troubleshoot issues.

module.ignore

@@ -1 +1,15 @@
+Microsoft.Bcl.AsyncInterfaces.dll
+Newtonsoft.Json.dll
+Serilog.dll
+System.CodeDom.dll
+System.IO.Abstractions.dll
+System.Management.dll
+Testably.Abstractions.FileSystem.Interface.dll
+TestableIO.System.IO.Abstractions.dll
+TestableIO.System.IO.Abstractions.Wrappers.dll
 TimeZoneConverter.dll
+VirtoCommerce.CoreModule.Core.dll
+VirtoCommerce.NotificationsModule.Core.dll
+VirtoCommerce.Platform.Core.dll
+VirtoCommerce.Seo.Core.dll
+VirtoCommerce.StoreModule.Core.dll

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsDiagnosticsCheck.cs

@@ -0,0 +1,12 @@
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsDiagnosticsCheck
+{
+    public string Stage { get; set; }
+
+    public string Status { get; set; }
+
+    public string Message { get; set; }
+
+    public string Detail { get; set; }
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsDiagnosticsReportShape.cs

@@ -0,0 +1,14 @@
+using System.Collections.Generic;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsDiagnosticsReportShape
+{
+    public string Name { get; set; }
+
+    public IList<string> DimensionNames { get; set; } = [];
+
+    public string MetricName { get; set; }
+
+    public IList<string> EventNames { get; set; } = [];
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsDiagnosticsRequest.cs

@@ -0,0 +1,14 @@
+using System.Collections.Generic;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsDiagnosticsRequest
+{
+    public IList<string> UserDimensionNames { get; set; } = [];
+
+    public IList<string> EventNames { get; set; } = [];
+
+    public IList<AnalyticsDiagnosticsReportShape> Reports { get; set; } = [];
+
+    public bool IncludeLiveData { get; set; } = true;
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsDiagnosticsResult.cs

@@ -0,0 +1,8 @@
+using System.Collections.Generic;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsDiagnosticsResult
+{
+    public IList<AnalyticsDiagnosticsCheck> Checks { get; set; } = [];
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsDimensionFilter.cs

@@ -0,0 +1,11 @@
+using System.Collections.Generic;
+using VirtoCommerce.Platform.Core.Common;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsDimensionFilter : ValueObject
+{
+    public string DimensionName { get; set; }
+
+    public IList<string> Values { get; set; } = [];
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEvent.cs

@@ -0,0 +1,22 @@
+using System;
+using System.Collections.Generic;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsEvent : ICloneable
+{
+    public string EventName { get; set; }
+
+    public DateTime? OccurredAt { get; set; }
+
+    public int Count { get; set; }
+
+    public IDictionary<string, string> Dimensions { get; set; } = new Dictionary<string, string>();
+
+    public virtual object Clone()
+    {
+        var result = (AnalyticsEvent)MemberwiseClone();
+        result.Dimensions = Dimensions != null ? new Dictionary<string, string>(Dimensions) : null;
+        return result;
+    }
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEventCriteriaBase.cs

@@ -0,0 +1,21 @@
+using System;
+using System.Collections.Generic;
+using VirtoCommerce.Platform.Core.Common;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public abstract class AnalyticsEventCriteriaBase : SearchCriteriaBase
+{
+    public string StoreId { get; set; }
+
+    public IList<string> EventNames { get; set; } = [];
+
+    public IList<AnalyticsDimensionFilter> DimensionFilters { get; set; } = [];
+
+    public DateTime? From { get; set; }
+
+    public DateTime? To { get; set; }
+
+    // For a diagnostics probe: a feature read must not set it, since the cache is what protects the quota.
+    public bool BypassCache { get; set; }
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEventSearchCriteria.cs

@@ -0,0 +1,10 @@
+using System.Collections.Generic;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsEventSearchCriteria : AnalyticsEventCriteriaBase
+{
+    public IList<string> DimensionNames { get; set; } = [];
+
+    public string SortBy { get; set; } = ModuleConstants.SortBy.Date;
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEventSearchResult.cs

@@ -0,0 +1,20 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using VirtoCommerce.Platform.Core.Common;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsEventSearchResult : ICloneable
+{
+    public int TotalCount { get; set; }
+
+    public IList<AnalyticsEvent> Events { get; set; } = [];
+
+    public virtual object Clone()
+    {
+        var result = (AnalyticsEventSearchResult)MemberwiseClone();
+        result.Events = Events?.Select(x => x.CloneTyped()).ToList();
+        return result;
+    }
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEventSummary.cs

@@ -0,0 +1,17 @@
+using System;
+
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsEventSummary : ICloneable
+{
+    public string EventName { get; set; }
+
+    public int TotalCount { get; set; }
+
+    public DateTime? LastOccurredAt { get; set; }
+
+    public virtual object Clone()
+    {
+        return MemberwiseClone();
+    }
+}

src/VirtoCommerce.GoogleEcommerceAnalyticsModule.Core/Models/AnalyticsEventSummaryCriteria.cs

@@ -0,0 +1,5 @@
+namespace VirtoCommerce.GoogleEcommerceAnalyticsModule.Core.Models;
+
+public class AnalyticsEventSummaryCriteria : AnalyticsEventCriteriaBase
+{
+}