Web Analytics Field Matrix¶

Purpose¶

The Web Analytics Field Matrix documents how fields exposed by the Google Analytics 4 (GA4) Data API map to the organization's canonical data model, across all six GA4 properties in scope.

It separates GA4's own representations from canonical organizational definitions, in particular where GA4 reuses terms — "engagement rate," "conversions," "retention" — that already mean something specific elsewhere in the data dictionary.

Property-Level Canonical Mapping¶

All six properties (Adanian Labs, AICE, Afyarekod, DataInViz, Conversational Engine, Caspre) expose the same GA4 Data API surface, so the mapping is one table rather than one per property, with property carried as a dimension on every row rather than repeated per site.

GA4 Field	Field Type	Canonical Definition	Mapping	Confidence	Reason
`activeUsers`	metric	`sales.web_users`	Direct	High	GA4's definition of "Users" in standard reports
`newUsers`	metric	`sales.web_new_users`	Direct	High	First-time users, distinct from returning users
`sessions`	metric	`sales.web_sessions`	Direct	High	Standard session count
`engagementRate`	metric	`sales.web_engagement_rate`	Direct	High	Native GA4 metric; see semantic distinction from `sales.engagement_rate` below
`userEngagementDuration`	metric	`sales.web_avg_engagement_time`	Semantic	Medium	Native field is a summed duration, not an average — see below
`screenPageViews`	metric	`sales.web_page_views`	Direct	High	Combined page (web) and screen (app) views
`conversions`	metric	`sales.web_key_event_count`	Direct	High	API field name is unchanged; GA4's interface now labels this "Key events"
`totalRevenue`	metric	`sales.web_revenue`	Direct	High	Expected to be sparse/zero for non-ecommerce properties
`ecommercePurchases`	metric	feeds `sales.web_revenue` context	Semantic	Medium	Transaction count, not a revenue figure itself
(cohort report) `cohortActiveUsers` / `cohortTotalUsers`	metric, cohort request only	`sales.web_retention_rate`	Conditional	Medium	Requires a distinct GA4 cohort report request, not a standard dimensions/metrics query — see note below
`sessionSource` / `sessionMedium`	dimension	attaches to `sales.web_sessions`	Direct	High	Session-level traffic source
`firstUserSource` / `firstUserMedium`	dimension	attaches to `sales.web_users`	Direct	High	Acquisition source at first visit, distinct from session-level source
`firstUserDefaultChannelGroup`	dimension	attaches to `sales.web_users`	Direct	High	GA4's own channel grouping (Organic Search, Paid Search, Direct, Referral, etc.)
`pageTitle` / `pagePath`	dimension	attaches to `sales.web_page_views`	Direct	High	Page-level breakdown
`audienceName`	dimension	attaches to real-time user counts only	Conditional	Medium	GA4-defined audience segments; not part of the standard lifecycle reports used for canonical metrics
`deviceCategory`, `country`	dimension	attaches to `sales.web_sessions` / `sales.web_users`	Direct	High	Standard breakdown dimensions
(none — Search Console) organic search query	—	unresolved	Unresolved	—	Not available from the GA4 Data API; requires linking a Search Console property and a separate API — see Source Mappings

Mapping Types¶

The matrix uses the following mapping classifications, consistent with the Social Media field matrix.

Direct¶

The source field and canonical definition have substantially the same meaning.

GA4 sessions
        ↓
sales.web_sessions

Semantic¶

The source field is mapped to a canonical concept whose meaning is sufficiently compatible, but whose native representation differs enough to need a transformation, not just a rename.

GA4 userEngagementDuration   (a summed duration across all sessions)
        ↓
sales.web_avg_engagement_time   (an average per session)

Semantic mappings should be reviewed whenever the underlying calculation changes.

Conditional¶

A mapping is valid only under defined conditions, or requires a materially different API request shape before it can be treated as equivalent to the rest of the domain's fields.

GA4 cohort report (cohortActiveUsers / cohortTotalUsers)
        ↓
sales.web_retention_rate

Retention is the clearest example in this domain: it cannot be obtained from the same standard runReport call used for every other metric here. It requires a dedicated cohort report request (cohortSpec), a different shape of query with its own date-range and cohort-window semantics. Anyone implementing this metric should treat it as a distinct ingestion path, not an additional field on the standard pull.

Canonical Metrics Identified¶

Grouped using GA4's own lifecycle stages, which already reflect a coherent way of organizing the visitor journey:

Acquisition¶

sales.web_users
sales.web_new_users
sales.web_sessions

Engagement¶

sales.web_engagement_rate
sales.web_avg_engagement_time
sales.web_page_views

Monetization¶

sales.web_revenue
sales.web_key_event_count

Retention¶

sales.web_retention_rate

These are canonical metrics, not automatically KPIs. A metric becomes a KPI only when the organization explicitly designates it as an important measure of performance against an objective or decision — see the four sales.web_* KPIs defined alongside these metrics.

Important Semantic Distinctions¶

`sales.web_engagement_rate` vs. `sales.engagement_rate`¶

sales.engagement_rate already exists for social media: interactions (likes, comments, shares, saves) divided by reach. GA4's engagementRate is a completely different calculation — the percentage of sessions that lasted longer than 10 seconds, had a key event, or had two or more page/screen views. These are not comparable numbers and must never be blended into one "engagement rate" figure across channels.

`sales.web_key_event_count` vs. `sales.conversion_rate`¶

sales.conversion_rate already exists for the CRM funnel: leads progressing to meetings, pilots, or signed contracts. GA4's conversions metric (labelled "Key events" in the current GA4 interface, following Google's 2024 terminology change) counts sessions that triggered any event the property owner has marked as a key event — which could be a form submission, a demo request, or a purchase, and is a website-behaviour signal, not a sales-pipeline stage. Kept as a separate metric rather than folded into the existing conversion metric.

`sales.web_retention_rate` vs. `sales.retention_rate`¶

sales.retention_rate already exists for customers and partners tracked in the CRM. GA4's retention concept is about anonymous or pseudonymous website visitors returning in a later cohort window, measured very differently (cohort-based, not account-based) and answering a different question (does the site bring people back, not does the customer relationship survive).

`activeUsers` vs. `newUsers` vs. `totalUsers`¶

GA4 exposes three related but distinct user-count fields. activeUsers (mapped to sales.web_users) is what GA4's own UI treats as the default "Users" figure. newUsers (mapped to sales.web_new_users) counts only first-time users. totalUsers is a third, broader count that is not currently mapped to a canonical metric — flagged here so it is not assumed to be redundant with activeUsers if it turns up in a future field audit.

Average engagement time is not a raw field¶

userEngagementDuration is a summed duration across all sessions in the reporting period. The "Average engagement time" figure shown in the GA4 interface is that sum divided by sessions or by users, depending on which report you are looking at. sales.web_avg_engagement_time should be defined with an explicit formula (userEngagementDuration / sessions), not treated as a pass-through of a single API field.

Measurement Considerations¶

Snapshot
    (none currently — GA4 has no snapshot-style metric in this domain)

Cumulative (period aggregate)
    sales.web_sessions
    sales.web_users
    sales.web_page_views
    sales.web_key_event_count
    sales.web_revenue

Rate (derived, non-additive)
    sales.web_engagement_rate
    sales.web_retention_rate

Derived Average
    sales.web_avg_engagement_time

Rate and average metrics must never be summed across time periods or across properties — a blended "engagement rate" across six sites has to be recomputed from the underlying counts (engaged sessions and sessions), not averaged from six already-computed percentages.