> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Analytics 4

> What connecting Google Analytics 4 to an advertiser does, what access it asks Google for and why, who can connect it, and what each connection state means and how to fix it.

> [!WARNING]
>
> **Setup is not available yet.** There is no screen, agent tool or documented API
> operation to connect Google Analytics 4 today, so you cannot connect it, and
> there is nothing to ask your Apostra contact to switch on. The campaign report
> columns described below appear only for an advertiser that has connected Google
> Analytics, so you will not see them yet. This page describes how the connection
> and the columns will work so you can see what they ask for and show before they
> open. Apostra will announce it when setup is available.

Most advertisers already run Google Analytics 4 on their site. Once setup is
available, connecting it to an advertiser lets Apostra read your own site
reports for that advertiser: how many visits a campaign brought, and how many of
those visits did something you count as a result, such as signing up.

You will connect once for each advertiser. You sign in with Google, choose one
GA4 property, and choose which of that property's key events count. From then on
Apostra reads your property once a day and shows the results next to delivery in
campaign reports (see "Site outcomes in campaign reports" below).

## What Apostra asks Google for, and why

Apostra asks for one permission: read-only access to Google Analytics
(`analytics.readonly`). It asks for nothing else, and it checks every time it
uses the access. If Google ever returns more than read-only access, Apostra
refuses to use it and the connection shows as needing a reconnect.

Read-only access lets Apostra do three things:

* List the GA4 properties you can see, so you can choose one.
* List the key event names of the property you chose, so you can choose which
  count.
* Read that property's reports.

Reports and key event names are totals and names. They never contain people.
Apostra uses what it reads only to show you your own reports for your own
advertiser, and for nothing else.

**Apostra never stores your Google token.** Google sign-in runs through WorkOS,
which holds the token encrypted and refreshes it. Apostra asks WorkOS for a
valid token each time it needs one, uses it for that one piece of work, and
drops it.

## Who can connect, and what access they need

* **One connection for each advertiser.** The Google Analytics property belongs
  to the advertiser, not to whoever clicked Connect. Everyone with access to the
  advertiser can see the connection's state. Only an account admin can connect,
  change the property or key events, reconnect, or disconnect.
* **The person who signs in needs access to the property in Google Analytics.**
  They need at least read access to the property they choose. The connection
  reads as that person. If they lose access to the property, or leave your
  organization, the connection becomes unhealthy (see below). Any account admin
  can reconnect it, and the property and key events you chose are kept.
  A person who connected an advertiser is deleted from Apostra only after their
  connection is released: Apostra removes their Google sign-in at WorkOS and
  disconnects the connection, clearing their sign-in details. The property and
  key events are kept for the next admin who reconnects.
* **Staff acting for your account and service tokens cannot connect it.** The
  Google sign-in has to be a person's own.

## Choose a property and key events

After you sign in, choose one GA4 property from the list Google returns. Then
choose which of its key events count. Key events are GA4's name for what used to
be called conversions, and you set them up in Google Analytics.

* You can choose up to 10 key events.
* You can choose none. The connection still works, and key events are simply
  left out.
* Apostra stores the property's ID, name, timezone and currency, as Google
  reports them, and the key event names you chose.

Until you choose a property, the connection stays pending.

## Site outcomes in campaign reports

Once an advertiser is connected, a stored campaign delivery read
(`get_delivery` with `report: "campaign_delivery"`) carries a `siteOutcomes`
section for the media buys in the read, and Murph reads the same section. It
appears only when an advertiser in the read has connected Google Analytics. If
Apostra cannot read the section within a few seconds, the report comes back
without it, so a slow read never holds up your delivery numbers.

For each media buy it shows:

| Column | What it is |
| - | - |
| `sessions` | Visits Google Analytics credited to this buy. |
| `engaged_sessions` | The visits Google Analytics marked as engaged. |
| `key_events` | The key events you chose, added together, with the count for each event name. Left out when you chose none. |
| `costPerSession` | Spend divided by `sessions`, for the whole range. |
| `costPerKeyEvent` | Spend divided by `key_events`, for the whole range. |

The counts use the AdCP `vendor_metric_values` shape with Google as the vendor, so
a `sessions` count can never be mistaken for the `clicks` or `conversions` a seller
reports. Each media buy shows the counts summed over the days Apostra read in the range, with how many days were read and how many were not.

### How to read the numbers

* **Counted in the same visit.** Google Analytics credits a key event to the
  campaign of the visit it happened in. Someone who clicks the ad on Monday and
  signs up on Wednesday in a new visit counts as direct, so delayed results are
  undercounted. The label says so: *Site analytics (GA4, same visit, not
  verified)*.
* **Not verified, never billable, never sent to sellers.** The seller did not
  report these numbers and cannot confirm them. Apostra never uses them for
  billing. Google's report API returns totals, not people, so Apostra cannot send
  them to a seller to optimise delivery. To have a seller optimise to sign-ups,
  use an event source and the seller's pixel or server events instead
  ([Bring data in](https://docs.apostra.com/v3/bring-data-in.md)). You can have both, and the numbers will
  differ, because a seller counts what it can attribute and Google Analytics
  counts what happened on your site. Apostra shows both and never adds them
  together.
* **Only buys carrying our tags.** Apostra matches a visit to a buy by the buy's
  id in the visit's campaign tag (`utm_campaign`). Visits with any other campaign
  name are ignored. If you set your own `utm_campaign` on a landing page, visits
  to that page cannot be matched to the buy, and no outcomes appear for it.
* **No tagged visits found.** If a seller reported clicks for a buy but Google
  Analytics saw no tagged visits on the days it read, the buy's counts are empty
  and `reason` is `no_tagged_visits_found`. The tags may not be reaching your
  landing page. It is not a count of zero.

### When the numbers are read, and what zero means

* **Once a day, by the property's day.** A day is a calendar day in your GA4
  property's timezone, as Google Analytics reports it. Apostra never moves it
  into the campaign's timezone. Today is never read, because it is not finished.
* **Provisional, then settled.** Google Analytics can change recent numbers for
  about 48 hours. Apostra re-reads the last three closed days each day. A day is
  `provisional` until it has been read three days after it closed, then
  `settled`.
* **Zero means read and empty.** A buy has a count of zero for a day only when
  Apostra read that day and Google Analytics had nothing for the buy. A day
  Apostra did not read, including today and any day while the connection was
  unhealthy, is unavailable and is counted in `daysUnavailable`. It is never shown
  as zero.
* **The first read goes back.** The first read after you connect, and a read
  after a long gap, goes back to the day of the advertiser's earliest buy, but no
  further than 90 days. Choosing a different property, or different key events,
  drops the days already read and reads them again, because the old days would
  read as zero for events Apostra never asked about.

### Cost per visit and per key event

Each cost divides the buy's spend over the whole requested range by its count
over the same range. Apostra does not show a cost for a single day, because a
Google Analytics day and a campaign day are different 24-hour windows. A cost is
left out when any day the buy spent on was not read, when the buy's spend spans
more than one currency, or when the count is zero.

A cost is `provisional` unless every Google Analytics day behind it is settled and
the spend is the seller's final (Official) figure. It takes the weaker of the two.

### When Apostra fails instead of guessing

A daily read stores nothing unless it read everything it needed. It fails, and
keeps the days it already had, when Google Analytics reports that it lost rows to
the "(other)" row because the property has too many campaigns, when it samples the
report, when paging does not reach the reported row count, or when a call fails or
runs past its deadline (30 seconds for each Google call, five minutes for one
connection's whole read). A single failed run changes nothing: Apostra tries
again the next day. Only a failure to read the report counts. If Apostra's own
side fails before Google is asked, for example a lookup or a database error, the
run is retried at the next check and never counts toward the three. After three
failed runs in a row the connection becomes unhealthy with the reason
`read_failed`, and Apostra's on-call team is alerted once. Apostra keeps trying
once a day, and the first good read makes the connection active again, so a
provider outage heals without you doing anything. The numbers already stored
stay, and reports show the connection's state and when Apostra last read it.

## Connection states

A connection is always in one of these states. An unhealthy connection also says
why.

| State | Reason | What it means | What to do |
| - | - | - | - |
| Not connected | | Nothing is connected for this advertiser. | Connect Google Analytics. |
| Pending | | You signed in, or started to, and have not chosen a property. | Finish signing in, then choose a property. |
| Active | | Google gave access and the property is readable. | Nothing. |
| Unhealthy | `needs_reauthorization` | Google access ended or changed. | Reconnect. |
| Unhealthy | `not_installed` | The connection was removed. | Reconnect. |
| Unhealthy | `scope_violation` | Google returned access other than read-only Google Analytics access. | Reconnect. Apostra needs read-only access and nothing else. |
| Unhealthy | `property_access_lost` | The signed-in Google user can no longer see the chosen property. | Reconnect as someone who can see it, or choose another property. |
| Unhealthy | `property_missing` | Google has no such property. | Choose another property. |
| Unhealthy | `read_failed` | Apostra could not read Google Analytics for three days in a row. The numbers already stored stay. | Usually nothing: Apostra keeps trying once a day and the connection becomes active on the first good read, filling the days it missed, back as far as 90 days. If it stays unhealthy, reconnect. The property and key events you chose are kept. |
| Disconnected | | The connection was disconnected. | Connect again. |

Apostra checks an active connection against Google at most every five minutes.
If Google or WorkOS cannot be reached when it checks, the connection keeps the
state it had and the check reports that it could not be completed. A failed
check is never read as the connection being unhealthy.

## Reconnect, change, or disconnect

* **Reconnect.** Sign in with Google again. The property and key events you chose
  are kept, so you do not choose them again. If a different admin signs in, the
  connection now reads as that person, and the first person's Google sign-in with
  Apostra is removed unless another of your advertisers still uses it.
* **One sign-in at a time.** If another admin has started signing in with Google
  for the same advertiser and has not finished, you cannot reconnect until they
  finish or 15 minutes have passed. Apostra tells you when this happens. The
  person who is signing in can start again at any time.
* **Change the property or key events.** Choose again. Apostra reads the
  property's details and key events from Google, so it only accepts events the
  property actually defines.
* **Disconnect.** Apostra removes the Google sign-in at WorkOS and clears who
  connected it. Your property and key event choice is kept, so connecting again
  restores it. If another advertiser in your organization uses the same person's
  Google sign-in, Apostra leaves that sign-in in place for it.

## Related

* [Bring data in](https://docs.apostra.com/v3/bring-data-in.md) covers the other ways to get your own data
  into Apostra.
* [Key event](https://docs.apostra.com/v2/concepts/glossary.md#k) is defined in the glossary.
* [Errors](https://docs.apostra.com/v3/errors.md) explains how Apostra reports a request it cannot complete.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.