`docs/ANALYTICS_CONNECTORS.md`

100 lines

# RENTV Advertiser Intelligence — Analytics Connectors

How GA4, Search Console, optional Google Ads, and the CSV fallbacks work — and exactly
how to go from **DEMO** (fixture-backed) to **LIVE**. All Google data is read through the
**official APIs only**; nothing is scraped.

## Current state: DEMO

With no Google service-account credentials configured, the analytics dashboards run on
the deterministic fixtures in `fixtures/` (e.g. `ga4-daily.json`, `ga4-landing.json`).
Everything derived from them is labeled **`DEMO DATA`** in the UI so no one mistakes a
fixture for a real audience number. This is by design — the app is fully demonstrable
offline.

## GA4 (§17) — official Google Analytics Data API

Imports (per day, aggregates only — **never** a user-level identifier):

- **Daily overview** — sessions, total users, new users, engaged sessions, engagement
rate, average engagement time, views, event count, key events/conversions.
- **Acquisition** — session default channel group, session source, session medium,
session campaign, first-user source/medium.
- **Content** — landing page + query string, page path, page title, with
sessions / users / views / engaged sessions / engagement rate / key events.
- **Geography** — country, region, city, rolled up into **California and Arizona market
views** (§7 priority order).

Stored in `ga4_daily_metrics`, `ga4_landing_page_metrics`, `ga4_acquisition_metrics`,
`ga4_geo_metrics`.

## Search Console (§18) — official Search Console API

Imports daily aggregates by query / page / country / device / date with clicks,
impressions, CTR, average position. Views: 28-day, 90-day, 12-month, and prior-period;
brand vs. non-brand classification; California / Arizona market clusters; property-type,
finance/lending, brokerage/deal, and conference/event clusters; rising queries; and
high-impression / low-CTR opportunities. This is **organic** search data — never labeled
as paid search. Stored in `gsc_query_metrics`, `gsc_page_metrics`.

## Optional Google Ads (§19)

Enabled only when credentials are configured (`GOOGLE_ADS_ENABLED="true"` plus the six
`GOOGLE_ADS_*` values). Imports aggregate campaign / ad-group / keyword / search-term /
cost / click / impression / conversion / geo metrics the account is authorized to see.
Kept **separate** from Search Console data; currency and date range always displayed.
Credentials never appear in client code or logs.

## CSV fallback (§20)

When an API is not connected, a guided field-mapping importer accepts CSV exports for
GA4, Search Console, Google Ads, Constant Contact, and legacy spreadsheets — with preview
before import, type validation, duplicate detection, dry run, an import summary, a
rejected-row file, a reversible batch, source + file checksum, and clear **DEMO vs
PRODUCTION** labeling.

## How to go from DEMO → LIVE

1. In Google Cloud, create a **service account** and download its JSON key.
2. Grant that service account **Viewer** on the GA4 property and **read** on the Search
Console property.
3. Base64-encode the JSON and set the three env vars (secrets are server-only, redacted
from logs):

```bash
GOOGLE_SERVICE_ACCOUNT_JSON_BASE64="$(base64 -i service-account.json)"
GA4_PROPERTY_ID="123456789" # numeric GA4 property id
GSC_SITE_URL="https://www.rentv.com/" # exact GSC property URL (with trailing slash)
```

4. Run the imports:

```bash
npm run analytics:ga4
npm run analytics:gsc
# optional, only if GOOGLE_ADS_ENABLED=true and the six GOOGLE_ADS_* vars are set:
npm run analytics:google-ads
```

5. The dashboards drop the `DEMO DATA` label once live rows exist and show the data date
+ source on every figure.

## Derived-insight formulas (§17 "Sales intelligence derived from GA4")

Every derived insight is documented and dated; user-level data is never exposed.

- **CA/AZ audience concentration** = sessions in a state's mapped markets ÷ total
sessions, over the selected window.
- **Top sections/landing pages by CRE category** = landing pages grouped by
advertiser-category tag, ranked by sessions.
- **Top referral domains** = sessions where channel = Referral, grouped by source domain.
- **Newsletter/eblast traffic** = sessions where `utm_medium ∈ {email, eblast,
newsletter}`, grouped by `utm_campaign`.
- **Conference / sponsor landing-page performance** = sessions + engagement rate + key
events for landing pages tagged as conference or sponsor/campaign pages.
- **Period-over-period / YoY** = metric(window) vs metric(prior equal-length window) and
vs the same window one year earlier; shown as delta + percent.

Search Console clusters use the same market/category tag maps applied to the query string
rather than the landing page.