Docs / Publishing & integrations / Google Analytics 4
Connect Google Analytics 4
Search Console tells you what people search on Google. Analytics tells you what they did once they arrived. Connect a Google Analytics 4 property and AEO Spotlight adds on-site sessions and conversions per landing page, shown beside Google Search demand and beside our own AI-visibility measurement.
1 · What this integration does
This integration imports Google Analytics 4 page metrics over a rolling 28-day window and places them on the Search demand page, in the page-level table:
| Field | What it is | Notes |
|---|---|---|
sessions | Visits to the landing page over the window. | All channels — not search-only. |
engagedSessions | Sessions that were meaningfully engaged. | Useful for separating bounces from real visits. |
totalUsers | Distinct users, as GA4 reports them. | GA4's own definition, not a unique-visitor count. |
keyEvents | Conversions/events your property marks as key. | Whatever you have configured as a key event in GA4. |
The page table is a juxtaposition, not a merge: the row is a landing page URL, and the Google Search columns sit beside the GA4 columns with a clear separator between them. The two are different instruments and are never added together.
2 · Before you start
- You must have a Google Analytics 4 property that is collecting data for the site you care about.
- Sign in with a Google account that can access that property. AEO Spotlight requests only read access to your Analytics data.
- This is a separate connection from Search Console. A Search Console connection does not grant Analytics access, and the two are authorized independently.
- Connect may be switched off on a self-hosted or fresh deployment; the app tells you clearly if it is — see Troubleshooting.
3 · Connect a property
Open your account menu and go to Connected data.
Find the Google Analytics 4 card and click Connect Google Analytics 4.
Your browser moves to Google's consent screen. Sign in with the Google account that can access the property, and approve the read-only access request.
You're returned to the app and a property picker lists the Analytics properties that account can access. Choose the property to connect.
The property appears as Connected on Connected data and is scheduled to import. You can also Run now to trigger the first import immediately — when it finishes, the page table appears on the Search demand page.
4 · What happens after connecting
- Imports run automatically on a schedule (and anytime you hit Run now). Each import pulls page metrics for the rolling 28-day window, matching the Search Console window.
- The metrics are joined to your search demand by landing-page URL, and rendered on the Search demand page's page table: URL · Google Search impressions/clicks · GA4 sessions/conversions · AI-cited?
- Each number carries a method chip — “Measured by Google” for Search Console, “Measured by GA4” for analytics — so an estimate can never be mistaken for a measurement.
5 · What this integration does not claim
- No query attribution. GA4 does not tell us which search term drove a visit, so sessions are never shown against a query — only against a page.
- All channels, not search-only. Sessions include direct, social, email and referral traffic, not just Google Search.
- No causal link. Connecting Analytics does not cause — and cannot prove — a change in AI visibility. The two are shown side by side, never blended.
- Thresholding and sampling. At low volumes, GA4 may sample or withhold rows, so small numbers can be approximate or absent.
- A short lag. Analytics data typically arrives 24–48 hours after the fact, so the newest day or two is incomplete.
6 · Disconnecting a property
Disconnect is always available (it works regardless of the connect feature's state). Disconnecting revokes Google's access best-effort and removes the imported Analytics data locally.
From AEO Spotlight — open your account menu → Connected data, and use Disconnect this property on the Google Analytics 4 card. The page states what will be removed before you confirm it.
From Google's side — you can revoke this app's access at any time from your Google Account third-party access page. Imports stop as soon as Google rejects the next request.
7 · Troubleshooting & error codes
| Message / code | What it means & what to do |
|---|---|
ga4_connect_disabled | The Analytics connect surface isn't enabled on this deployment. Existing connected properties still work; you just can't start a new Google Analytics connect right now. |
no_properties | The Google account you chose doesn't have any accessible Analytics properties. Check the property (and the account's access) in Google Analytics, then connect again. |
access_denied | You denied the Google authorization. Nothing was connected — start again any time. |
invalid_state | The connect attempt expired or was reused. Just start a fresh connect. |
invalid_grant / token_exchange_failed | Google didn't complete the token exchange (e.g. the grant was revoked or reused). Start the connect again. |
Property status needs_reconnect | Google revoked the token (or it expired). Use Reconnect to re-authorize. |
Property status revoked / error | The connection was removed or failed. Connect the property again (or remove it). |
A property I expect isn't in the picker
The picker only shows properties the signed-in Google account can access. If it's missing, either sign in with an account that has access, or grant that account access to the property in Google Analytics and re-run the connect.
Connect is “not enabled on this deployment”
This integration is surfaced only when your deployment has the connect feature switched on (config flag + OAuth client + the Analytics APIs enabled on the Google Cloud project). If you see this and expected it to work, contact support — it's a platform configuration toggle, not something on your side.