Google Analytics Integration

Tag Management

GA4 is deployed through Google Tag Manager (GTM), which loads on every page via the root layout. GTM acts as a container for all analytics tags, allowing us to manage tracking without modifying application code. The GA4 measurement ID is configured inside the GTM container, not hardcoded in the site source.

Privacy & Consent

A cookie consent banner gates all analytics tracking. When a visitor first arrives, GTM loads but analytics tags are suppressed until the visitor grants consent. If consent is granted, a consent_update event is pushed to window.dataLayer, enabling GA4, Microsoft Clarity, and Meta Pixel. If consent is declined, no tracking cookies are set and no analytics data is collected.

This approach respects visitor privacy while providing aggregate, anonymized insights for measuring research impact.

Data API & Service Account

To programmatically access GA4 data, we use the Google Analytics Data API v1. A service account authenticates with a private key stored as a GitHub Actions secret in the google-prod environment. The service account has read-only access to the GA4 property — it cannot modify tracking configuration or delete data.

The Problem: Inflated Numbers

When we first displayed analytics on the site, we showed Page Views (65,930) as a measure of engagement. This number seemed impressive but didn't feel right — the project was relatively new and hadn't received that level of organic attention.

Switching to Active Users (23,766) didn't help — the number was still far too high. The question was: where was all this traffic coming from?

Root Cause: Automated Testing Traffic

Investigation via the GA4 Data API revealed the answer. By breaking down active users by hostName, we discovered:

99.6% of all recorded traffic came from localhost. This traffic was generated by:

• Playwright E2E tests — The CI/CD pipeline runs full end-to-end tests using real Chromium browsers against a local preview server. Because the tests execute in real browsers, GTM and GA4 tags fire normally, creating real GA4 sessions.
• AI coding agents — Multiple AI tools use Playwright to browse and validate the site during development, each generating distinct browser sessions.
• Local development — Developer sessions on localhost:3000 also trigger GA4 tracking.

The Solution: Hostname Filtering

The fix is straightforward: filter by hostname. Since all legitimate visitor traffic arrives at technologyadoptionbarriers.org, we extract only the production hostname row from the GA4 hostname breakdown.

Why Not Use GA4 Filters?

GA4 offers both property-level data filters and API-level dimensionFilter parameters. We attempted three different approaches to filter at the API level:

1. dimensionFilter with inListFilter on hostName — filter was silently ignored
2. dimensionFilter with stringFilter on hostName — filter was silently ignored
3. Adding hostName as a dimension alongside the filter — still returned localhost rows

The GA4 Data API's dimensionFilter does not reliably apply when using metricAggregations: TOTAL without row-level dimensions. Rather than continue debugging an opaque API behavior, we adopted the pragmatic approach: fetch the breakdown, filter in JavaScript.

A property-level filter in the GA4 admin console could also work, but would permanently exclude localhost data from all reports, which is undesirable for debugging and development monitoring.

What "Verified Visitors" Means

The Verified Visitors metric represents:

• Active users as defined by GA4 (users who had an engaged session or first visit within the reporting period)
• On the production hostname only (technologyadoptionbarriers.org)
• 28-day rolling window (matching the report period)

It explicitly excludes:

• localhost traffic (Playwright tests, AI agents, local dev)
• Staging or preview deployment traffic
• Any other non-production hostname

1. Automated Tests Create Real Analytics

If your CI/CD pipeline runs E2E tests in real browsers (Playwright, Cypress, Selenium) against a site that has analytics tags, those tests will generate real analytics data. This is not a bug — it's expected behavior. Plan for it from day one by either excluding localhost at the property level or filtering in your reporting pipeline.

2. GA4 API Filters Have Quirks

The GA4 Data API's dimensionFilter parameter does not always behave as documented, especially when combined with metricAggregations and no row-level dimensions. If you encounter filter issues, fetch the full breakdown and filter in your application code. It's more explicit and debuggable.

3. Always Show Your Methodology

Raw analytics numbers without context are meaningless at best, misleading at worst. This page exists because we believe in transparency — if we display a number on the site, we should explain exactly how it was derived and what it does and does not represent.