> ## 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. This page describes
> how the connection will work so you can see what it asks for before it opens.
> 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. Connecting
will not at first add anything to your campaign reports: the daily read that
brings site outcomes into reporting is a later step, and this page will cover it
when it ships.

## 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.

## 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. | Nothing yet: this is set only by the daily read, which is a later step. |
| 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.