Google Analytics 4
The only caOS source that is not an ad platform. It brings what happened on the site (sessions, users, events, revenue) and never media spend. Spend keeps coming from Meta, Google Ads and the other sources; GA4 is the other half.
Start
Connecta Google login, and not the Ads one
No credential is requested from anyone: it is a Google login. What has to exist first is access. Ask whoever administers the client's GA4 to grant read access to the Google account you will use.
GA4 has its own login, separate from Google Ads. Connecting one does not connect the other. Two cards, two authorisations, and they can be two different Google accounts. That is common: at the same client, whoever administers Ads is rarely the person who administers Analytics.
Choosing the properties is a separate step, and GA4 does not take you there. On the other connectors caOS opens that screen by itself after authorising; on GA4 it does not. Go back to Sources and choose which properties enter the workspace. Until you choose, the property appears nowhere.
Your credential, and what happens to it
Connect once and you are connected. The credential renews itself, indefinitely. You do not need a date in the calendar and you do not need to reconnect periodically.
There is only one way the connection drops: someone revokes access on the platform side (password changed, person removed from the account, authorisation cancelled). The account then shows up under Lost connections and reconnecting fixes it, keeping the tags it already had.
Your credential is encrypted end to end. It is encrypted before it is stored, and the key does not live in the database, so even database access does not reveal it. Nobody at caOS, and not you either, can read the credential back after it is saved. The screen only shows that it exists and is valid.
Only the metrics you asked for are read. caOS does not write to your ad account in order to extract data, and it stores no personal data about who saw the ad. Processing follows Brazilian data protection law (LGPD), and deletion is yours: revoking the connection erases the stored credential.
Reference
Metrics and dimensionswhat each field means
GA4 has no paid media metric: no cost, no impressions, no clicks. What it brings is on-site behaviour, and the link back to media is the campaign.
Core metrics8
| API field | What it is | Where it shows up |
|---|---|---|
| sessions | Visits to the site. | The number clients usually call visits. Do not sum across days, see Good to know. |
| engagedSessions | Engaged sessions, by GA4's definition. | Over 10 seconds, or a conversion, or two pages. |
| engagementRate | Engaged sessions ÷ sessions. | Recompute from the sums if you aggregate periods. |
| activeUsers | Active users in the period. | Does not sum across days: the same person would count twice. |
| newUsers | Users arriving for the first time. | Good for separating acquisition from return. |
| totalUsers | All users in the period. | Also does not sum. |
| averageSessionDuration | Average session length, in seconds. | An average of averages does not work: weight it by sessions. |
| sessionsPerUser | Sessions ÷ users. | Derived, recompute when aggregating. |
Dimensions3
| API field | What it is | Where it shows up |
|---|---|---|
| sessionCampaignName | The campaign that brought the session. | This is where GA4 finds the media. |
| sessionSource | Where it came from (google, facebook, direct). | With sessionMedium, it forms the source/medium pair. |
| sessionDefaultChannelGroup | The channel, already grouped by Google. | Use it when the client thinks in channels, not campaigns. |
Report parameters
The fields above say what comes back. These parameters say how: they decide the grain of the row, the period it covers and what counts as a conversion. Two reports from the same account showing different numbers almost always differ here.
| Parameter | What it changes | Values |
|---|---|---|
| dimensions | What each row is cut by. | At most 9 per report. Beyond that the Data API returns HTTP 400, and caOS fails earlier with the right message. |
| metrics | The number columns. | At most 10 per report, and at least 1. This is why there are six reports instead of one. |
| dateRanges | The period. | Comes from the source. Yesterday always arrives partial, see Data freshness. |
| dimensionFilter | A filter over the dimensions. | Optional. Filtering reduces rows, it does not change a metric's definition. |
| zeroed row | What the API omits. | A row with everything at zero is not returned. The same day returns more rows when you ask for more metrics. |
Everything you can pull
The tables above are what most reports use, but you are not stuck with them. The full GA4 catalogue has 6 tables and 81 fields, and you choose what goes in when you build the source. What is marked used by default is what the example source uses; the rest is available just the same.
The list below comes from the Xtractor catalogue itself, the same one the new source screen reads. If a field is here, the screen offers it.
ga4_acquisition_campaign used by default17 fields
date, sessionSource, sessionMedium, sessionSourceMedium, sessionCampaignId, sessionCampaignName, sessionDefaultChannelGroup, sessions, engagedSessions, activeUsers, newUsers, totalUsers, screenPageViews, bounceRate, engagementRate, averageSessionDuration, sessionsPerUser
ga4_ecommerce_campaign15 fields
date, sessionSource, sessionMedium, sessionCampaignId, sessionCampaignName, addToCarts, checkouts, ecommercePurchases, transactions, purchaseRevenue, totalRevenue, totalPurchasers, firstTimePurchasers, itemsViewed, itemsPurchased
ga4_channel_campaign14 fields
date, sessionDefaultChannelGroup, sessionSourceMedium, sessionCampaignId, sessionCampaignName, sessions, engagedSessions, activeUsers, newUsers, totalUsers, screenPageViews, totalRevenue, purchaseRevenue, transactions
analytics_campaign_performance13 fields
date, sessionManualCampaignName, sessionManualSourceMedium, sessionManualAdContent, addToCarts, checkouts, newUsers, purchaseRevenue, sessions, totalPurchasers, totalRevenue, transactions, engagedSessions
ga4_funnel_events12 fields
date, sessionDefaultChannelGroup, sessionSource, sessionMedium, eventName, eventCount, eventCountPerUser, eventValue, sessions, activeUsers, totalUsers, userEngagementDuration
ga4_item_performance10 fields
date, itemName, itemCategory, sessionCampaignName, itemRevenue, itemsPurchased, itemsViewed, itemsAddedToCart, itemsCheckedOut, itemDiscountAmount
Dimensions always come along. Ticking a single metric brings every dimension of that report with it, which is why the number of saved fields is larger than what you clicked.
There are six reports, and each one is closed. You cannot mix fields from two: if you need sessions and revenue together, use the report that carries both, or extract two reports.
Output
Where the data landsa spreadsheet and a warehouse are different jobs
Google Sheets
For building a report by hand
Pick a report and tick the metrics. Since dimensions come along, the tab is born with more columns than you clicked.
To join it to media, the linking field is the campaign name. It only works if campaign tagging is the same on both sides.
BigQuery
For modelling on top
6 reports, all daily, and no paid media field at all.
Legacy campaign (manual UTM), acquisition by campaign, ecommerce by campaign, and channel with sessions and revenue in the same cut. The channel one exists precisely to deliver sessions and revenue together: joining the other two is not one to one.
Trust
Data freshnessyesterday is always partial
GA4 attribution takes about two days to settle. Measured: yesterday arrives with almost half of sessions carrying no attributed source; from two days back, it sits around 2%. A daily report about the previous day publishes a number in which half the traffic still has no source. Treat yesterday as partial.
That is why caOS re-reads recent days on every sync and rewrites what changed: yesterday's session that gained a source today shows up attributed in your spreadsheet, with no action from you.
Sessions do not add up. It is an estimated number per query: re-aggregating daily rows does not give exactly the monthly figure. Revenue and transactions, by contrast, match exactly.
A row with everything at zero is not returned. This confuses reconciliation: the same day returns more rows when you ask for more metrics. When comparing against the GA4 interface, ask for the same metrics on both sides.
Detail
Good to knowwhat usually raises questions
The legacy campaign report only sees hand-typed UTMs. Anything arriving through Google Ads auto-tagging does not enter it. Measured on a real property: the manual campaign covers a little under half of sessions. For Google Ads campaigns, use the acquisition or channel reports.
GA4 takes up a platform slot in your plan. If the limit is already full, the source is refused when you save.
Know which property belongs to the client. caOS lists every property the login can reach, and an agency login usually reaches dozens.
Support
When it failsthe message and what to do
Card with a padlock and “no connection”. No GA4 connection exists yet. Connect first, build the source afterwards.
“State token expired or already used.” The window stayed open for more than ten minutes, or the link was used twice.
Authenticated and no property appears. Reading the properties failed. Either the login has access to no property, or the wrong Google account was used.
The properties appeared, but are not in Sources. They still need choosing: on GA4 that step does not open by itself.
A login with many Analytics accounts brings only some of them. The lookup asks for one page and does not ask for the next, and the excess is ignored without warning.