Fondoo
GitHubStart your 7-day trial for $0Start trial
Docs

Connect Google Analytics 4 to Fondoo

Live5 min readUpdated

Fondoo can add the Google Analytics 4 (GA4) tag to your published pages, send server-side conversion events, and let your agent read GA4 reports. Each part needs a different value from Google, so set up only the parts you want.

What Fondoo can do with it

1. The browser tag (public, not a secret). Your Measurement ID (G-...) is saved with configure_site_pixels. Fondoo injects gtag.js on the next publish (not into previews).

2. The server connector (secret). Saved with add_connection_key. It runs these actions through connector_action:

  • events.send (write): send one GA4 recommended event from the server: purchase, refund, sign_up, generate_lead, begin_checkout, add_to_cart or login. Needs apiSecret, the visitor's _ga cookie as ids.client_id, and consentGranted:true.
  • events.validate (read): check the same event against Google's validation server. Nothing is recorded.
  • reports.query (read): a report over a date range, up to 9 dimensions and 10 metrics, with paging. Needs propertyId and serviceAccountJson.
  • reports.realtime (read): a report on the last 30 minutes. Same credentials.

Fondoo cannot change GA4 settings. No action needs owner approval; agents need analytics:write for events.send and analytics:read for the rest. Deleting the connection needs owner approval.

Before you start

  • A GA4 property with a web data stream. Standard GA4 has no fee. Analytics 360 is paid and has higher API quotas.
  • Google says viewing stream details needs the Editor role or higher (help).
  • For reports: a Google Cloud project, and the Administrator role on the GA4 property.
  • Some Google Cloud organizations block service account keys. The policy iam.disableServiceAccountKeyCreation is on by default for organizations created on or after 3 May 2024 (Google Cloud).

Step by step: get your credentials

Measurement ID (measurementId, required)

  1. In Google Analytics click Admin.
  2. Under Data collection and modification, click Data streams, then your web stream.
  3. Copy the Measurement ID (G-...). It goes into both configure_site_pixels and the connector.

Measurement Protocol API secret (apiSecret, optional, for server events)

  1. On the same web stream page, click Measurement Protocol API secrets, then Create (Google).
  2. Enter a nickname, click Create, and copy the Secret value. Anyone with it can send fake data to your property.

Property ID and service account (propertyId and serviceAccountJson, optional, for reports)

  1. In GA4 go to Admin → Property settings. Copy the numeric Property ID (Google).
  2. In the Google Cloud console, enable the Google Analytics Data API for your project (quickstart).
  3. Open IAM & Admin → Service accounts and create a service account.
  4. Click the service account → Keys tab → Add key → Create new key → JSON → Create. The file downloads once.
  5. In GA4 go to Admin → property Access management → + → Add users (Google). Enter the service account's email (client_email in the file) and choose Viewer. Fondoo only asks for the read-only scope https://www.googleapis.com/auth/analytics.readonly.
  6. Fields cannot contain line breaks. Paste the key as one line (jq -c . key.json) or as base64 (base64 -i key.json | tr -d '\n' on macOS).

Connect it in Fondoo

a. In the dashboard. Go to Connections → Connect a tool. Type "GA4" in Find a tool. On the GA4 card click Use a key, then Open secure key entry. Fill in measurementId and whichever optional fields you need. Click Save connection securely. The page expires after 15 minutes and works once.

The dashboard has no screen for the browser tag; use your agent or REST.

b. By asking your agent. Example prompt: "Add my GA4 Measurement ID G-ABC123XYZ to my site, then give me a secure link to add the GA4 server key."

The agent calls:

configure_site_pixels({siteId, ga4: {measurementId: "G-ABC123XYZ"}})
add_connection_key({provider: "ga4", siteId})

The second call returns a one-use securePasteUrl; never paste secrets into chat. Then publish_site injects the tag.

REST: the same calls are POST /v1/ops/configure_site_pixels and POST /v1/ops/add_connection_key, with the call input as the JSON body:

curl -X POST https://api.getfondoo.com/v1/ops/add_connection_key \
  -H "Authorization: Bearer $FONDOO_API_KEY" -H "Content-Type: application/json" \
  -d '{"provider":"ga4","siteId":"YOUR-SITE-ID"}'

Consent. requireConsentForPixels defaults to false, because Fondoo has no per-site region setting. Turn it on for EU or UK visitors. Then no tag loads until your banner calls window.fondooConsent.grant(). Global Privacy Control is always honored. The browser helper window.fondooPixel.track(name, {eventId, value, currency}) sends Purchase, Lead, CompleteRegistration and InitiateCheckout to GA4 as purchase, generate_lead, sign_up and begin_checkout.

Deduplication. GA4 does not deduplicate browser and server events by event ID, so send each action from one side only. For purchase and refund, Fondoo sets transaction_id to your eventId.

Test that it works

  1. Run test_connection({connectionId}). With report credentials, Fondoo reads the property metadata and shows connected with reports.query confirmed. Without them the status is limited. The API secret cannot be checked without sending data.
  2. Check an event without recording it: connector_action({connectionId, action: "events.validate", input: {name: "purchase", eventId: "test-1", consentGranted: true, ids: {client_id: "GA1.1.123456789.1700000000"}}}). An empty messages list means the payload is valid (Google does not check the secret here).
  3. After publishing, visit your site and watch the GA4 realtime report.

Troubleshooting

  • "Credential fields do not match the connector manifest": a value has the wrong format (G-... for the Measurement ID, digits for the property ID).
  • "Service account key JSON must contain client_email, private_key and token_uri...": the key was pasted with line breaks or cut short. Paste it minified or as base64.
  • Test shows invalid: the Data API is not enabled, the service account email was not added to the property, or the property ID is wrong.
  • "ids.client_id is required": pass the visitor's _ga cookie value.
  • Events missing from reports: Google returns success even for malformed events, so run events.validate. Events older than 72 hours are rejected.
  • Cannot create a key in Google Cloud: an organization admin must exempt the project from iam.disableServiceAccountKeyCreation.

Limits, data and security

  • Data API quotas per standard property: 200,000 core tokens per day, 40,000 per hour, 14,000 per project per hour, 10 concurrent requests; realtime has a separate quota of the same size; Analytics 360 has ten times more (quotas). Fondoo also applies a local budget of 60 requests per minute.
  • Email, phone and externalUserId are SHA-256 hashed before they leave Fondoo. Server events carry ad_user_data and ad_personalization as granted, so set consentGranted:true only for visitors who agreed.
  • Credentials are encrypted in Fondoo's connector vault. list_connections shows only a masked value. A rotation reminder is due after 90 days unless you set rotateAfter.
  • To rotate, run rotate_connection_key({connectionId}) and re-enter every field. To disconnect, run delete_connection (needs owner approval). This does not revoke anything at Google: delete the API secret on the stream page and the service account key in Google Cloud.
  • To remove the tag, call configure_site_pixels({siteId, ga4: null}) and publish again.
  • This connector does not use webhooks.
  • These points may differ for your account: whether the debug_mode flag Fondoo adds for test events shows them in DebugView, and the 10-metric limit per report.