analytics-ingestion-ga4-gsc

Analytics Ingestion — GA4 + Search Console

When to Use This Skill

Load this skill when:

• Wiring a client's GA4 and Search Console connectors into the app
• Building the analytics/traffic section of a local SEO report
• Diagnosing "traffic is up but the phone isn't ringing" (attribution gap)
• Feeding real behavioral data into local-seo-action-prioritizer (CTR, conversions, landing-page performance)

This is the connector that closes the loop: rankings and geo-grid tell you visibility; GA4/GSC tell you whether that visibility turns into sessions, then leads. Without it, the report scores fixes on visibility alone and misses "already ranking, not converting."

Doctrine Base

Obeys local-seo-app-orchestrator and the connector security model:

• Read-only scopes only. GA4 analytics.readonly, GSC webmasters.readonly. Never request write.
• OAuth, not scraping. Client authorizes once; tokens live in the vault (auto-refresh), never pasted into app code or URLs.
• No PII in URLs or logs. Aggregate metrics only.
• Every ingested pull normalizes to canonical client + location IDs and writes to the Corpus Engine so signal compounds month over month.
• Direct-response voice in any client-facing output; banned words apply.

What It Pulls

GA4 (Data API v1):

• Organic sessions, users, engaged sessions, engagement rate — segmented to sessionDefaultChannelGroup = Organic Search
• Conversions / key events (calls, form submits, bookings) by landing page
• Top landing pages by organic sessions + conversion rate
• Geo (city/region) to confirm traffic is local, not noise
• Device split (mobile matters for local + CRO)

Search Console (Search Analytics API):

• Query-level: clicks, impressions, CTR, average position
• Page-level performance for the money keyword and service pages
• Query → page mapping (which page Google ranks for which term)
• Movement vs prior period

Attribution Model

The point is to connect the chain, not report four disconnected dashboards:

GSC query → ranked page → GA4 landing-page sessions → GA4 conversion → CallRail call

• If GSC shows impressions but low CTR → title/meta or SERP-feature problem (feeds an on-page fix action)
• If CTR is fine but GA4 sessions don't convert → CRO/click-to-call problem (feeds a CRO action)
• If GA4 converts but CallRail shows no calls → attribution/DNI break (feeds an attribution fix)
• Each break becomes a scored action in local-seo-action-prioritizer

Default Workflow Shape

1. Connect — client OAuth for GA4 + GSC; store tokens in vault
2. Ingest — pull the metric/dimension sets above for the reporting window + prior period
3. Normalize — map to canonical client/location; align GSC pages to GA4 landing pages
4. Diagnose — run the attribution-chain checks; flag the break point
5. Emit signals — write to Corpus Engine + hand candidate actions to the prioritizer
6. Report — analytics section + proof-ledger the deltas

Files in This Skill

References:

• references/ga4-metrics-and-dimensions.md — exact metric/dimension names, the organic segment, conversion mapping
• references/gsc-and-attribution-model.md — GSC query set + the query→page→session→conversion→call chain

Prompts:

• prompts/generate-traffic-insight.md — raw pulls in, plain-English diagnosis + candidate actions out

Templates:

• templates/analytics-snapshot.md — the report's traffic & conversion block

Success Criteria

• Read-only, tokens in vault, zero PII leakage
• Traffic is segmented to organic + local, not vanity totals
• Every analytics finding names the break point in the chain, not just a number
• Findings become scored actions, not a static dashboard
• Deltas write to the proof ledger so month-over-month is real, not screenshotted