Skip to main content
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: 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). 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. 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.
  • Bring data in covers the other ways to get your own data into Apostra.
  • Key event is defined in the glossary.
  • Errors explains how Apostra reports a request it cannot complete.