Skip to content

t1k:marketing:analytics:firebase

FieldValue
Moduleanalytics
Version1.21.13
Effortlow
Tools—
/t1k:marketing:analytics:firebase

Firebase Analytics (GA4) — Metrics by Build Version

Section titled “Firebase Analytics (GA4) — Metrics by Build Version”

Firebase Analytics data lands in a GA4 property, one per Firebase app, where the build appears as the appVersion dimension (versionName on Android, short bundle version on iOS). Querying revenue and user metrics against that dimension is what makes build-vs-build comparison possible.

This skill is read-only reporting. It never writes to Firebase or to any ad network.

  • Comparing monetization or engagement between two app builds
  • Answering “did the build we shipped hurt ARPU / revenue / user counts”
  • Finding the GA4 property id for an app (there are hundreds — one per app)
  • Pulling per-version revenue into a CSV for further analysis
  • Ad-spend or Profit/ROAS reporting — that is t1k:marketing:analytics:crawldata, a completely separate skill with its own connectors. GA4’s revenue figure is an SDK-side estimate covering roughly the MAX slice only; it is not a revenue source. See references/ga4-revenue-coverage.md.
  • Crash / stability comparison between builds — GA4 exposes crashAffectedUsers, but Crashlytics itself has no public read API. Use the Play Developer Reporting API instead; see references/other-version-apis.md.
  • Rigorous retention-by-version — a user’s appVersion changes when they update, so GA4 cohorts drift underneath you. That needs the BigQuery export.

Three things, once.

1. A Google OAuth client, reused from the studio first. Run t1k vault list and reuse the studio’s existing Google OAuth client (typed kind oauth_client, e.g. the one The1Platform’s admob-api uses) when its Cloud project enables the two APIs in step 2. Only the requested scope differs. Create a new “Desktop app” client in the Firebase Cloud project only as a last resort: first the studio-auth exception (docs/studio-auth.md § “Google identity and Google APIs”, theonekit-core): an issue on The1Studio/studio-auth, then the user’s approval. Put the id and secret in a .env beside this skill:

GA4_CLIENT_ID=...
GA4_CLIENT_SECRET=...

Make sure your project’s .gitignore covers .env so credentials are never committed.

2. Enable two APIs in that Cloud project:

APINeeded for
analyticsdata.googleapis.com — Google Analytics Data APIevery report (required)
analyticsadmin.googleapis.com — Google Analytics Admin API--list property discovery only

A 403 from either carries the exact activation URL; the scripts print that response verbatim rather than swallowing it.

3. Mint the refresh token (scope analytics.readonly, covers both APIs):

Terminal window
bun scripts/ga4_oauth_setup.js # --port to match a registered redirect URI

It prints a consent URL, catches the redirect on localhost:4280, and writes GA4_REFRESH_TOKEN into the .env. Approve with an account that can see the Firebase projects.

A second Google account needs its own token. One consent sees one account’s properties, and re-running the setup without --label REPLACES the base token — the first account’s properties stop resolving (#382). Mint the second account beside the first, then select it per run:

Terminal window
bun scripts/ga4_oauth_setup.js --label second # writes GA4_REFRESH_TOKEN_SECOND
bun scripts/ga4_appversion.js --account second --property 539901361 --date 2026-08-18

--account (or GA4_ACCOUNT) resolves GA4_REFRESH_TOKEN_<ACCOUNT>; without it the scripts use the base token. Labels are uppercased, non-alphanumerics become _.

Terminal window
# Discover property ids — one GA4 property per Firebase app
bun scripts/ga4_appversion.js --list
bun scripts/ga4_appversion.js --list --filter puzzle
# One app, one day
bun scripts/ga4_appversion.js --property 522904484 --date 2026-08-18
# One app across a window — this is where multiple versions actually appear
bun scripts/ga4_appversion.js --property 522904484 --start 2026-07-20 --end 2026-08-18
# Several apps at once, to CSV
bun scripts/ga4_appversion.js --property 522904484,468898317 --date 2026-08-18 --csv out.csv
FlagMeaning
--listList visible GA4 properties (id, name, account). Implied when --property is absent.
--filterSubstring match on property or account name, for use with --list.
--propertyProperty id, or a comma-separated list. A property that fails does not abort the others.
--dateSingle day. Defaults to yesterday.
--start / --endDate range (overrides --date).
--metricsComma-separated override of the auto-selected metric list.
--csvWrite results to a CSV file.

ga4_version_compare.js is the purpose-built tool for “is the new build better or worse”. It reports engagement, stability, ad-delivery-per-user, and ad-funnel failure rates for two versions side by side, split by new vs returning users so the rollout’s cohort skew cannot invert the conclusion.

Terminal window
bun scripts/ga4_version_compare.js --property 470996808 --versions 1.1.7,1.1.8 \
--start 2026-08-13 --end 2026-08-18
bun scripts/ga4_version_compare.js --property 470996808 --versions 1.1.7,1.1.8 \
--date 2026-08-18 --segment new

Funnel rates are derived only when the property logs the matching event pair (e.g. rewarded_ad_displayed + rewarded_ad_show_fail), so apps with different event naming simply get fewer rows rather than wrong ones.

It cannot tell you which build earns more. That needs revenue per version, which these properties do not send. Do not try to back it out by regressing app-level revenue on the version user-split either: a build’s share of users rises monotonically with time during a rollout (measured correlation with the day index: 0.93), so the estimate cannot separate “the new build monetizes worse” from “that week was worse”. A real attempt produced a leave-one-out range of -56% to -129%, the latter physically impossible. Fix the instrumentation instead.

Output is one row per appVersion x platform, sorted by the first metric descending.

Metric selection is data-driven: each property’s metadata endpoint decides which candidate metrics exist. The verified-present and verified-absent metric names are in references/metrics.md.

  • GA4 revenue ≈ the MAX slice only, not total ad revenue. It is built from ad_impression events the mediation SDK logs, so it misses AdMob standard demand and any S2S network. Use it to compare versions against each other; never as a revenue figure. Full numbers and the measurement that backs this: references/ga4-revenue-coverage.md.
  • $0.00 on every revenue metric can be an access restriction, not “no revenue”. With the GA4 “No revenue metrics” data restriction on the OAuth account, the API returns 0.00 for totalAdRevenue, totalRevenue, purchaseRevenue and eventValue, with no error. Check metadata.schemaRestrictionResponse.activeMetricRestrictions first (the script prints a WARNING). See references/ga4-revenue-coverage.md.
  • Zero revenue does NOT mean zero ad events. Sampling 8 apps, one showed 95,031 active users across 16 versions and $0.00. Investigating a second such app found it logging 64,487 ad_impression events that day — GA4 derives revenue only when those events carry value + currency, and these carried neither (eventValue came back 0.0000 on every ad event). So the app monetizes fine; GA4 simply cannot see the money. The script prints an explicit NOTE when users exceed 100 with zero revenue. Never read that zero as “this build earned nothing” — run an eventName x eventValue report first.
  • Impression counts are usable even when revenue is not. When value is missing you can still compare ad_impression per user between versions, and break it down by format (banner_shown, rewarded_ad_displayed, interstitial_ad_displayed). A shift in format mix is a real monetization signal — banner inventory is worth far less per impression than rewarded.
  • (other) is a bucket, not a version. Once the version tail exceeds GA4’s cardinality limit the remainder is collapsed into a literal (other) row. The script flags it. Do not sum it into a named version.
  • Version strings are dirty. Real data contains 1 and 3 alongside 1.1.8. Normalize before ranking, and expect junk from old builds.
  • One property per app means one API call per app. A fleet-wide sweep is hundreds of calls; prefer filtering to the apps that actually shipped a new build.
  • Two builds rarely coexist on a single day. A one-day pull usually returns a single version. Use a range that spans the rollout to get a comparison.
  • Never compare two versions per-user without controlling for new vs returning. A freshly rolled-out build reaches new installs first, so its cohort is mostly day-0 users who behave very differently. Measured on a real 50% rollout: the new version was 86% new users against the old version’s 38%, which flipped the sign of the headline number — aggregate ad_impression per user read +9% for the new build, but splitting by the newVsReturning dimension showed -5% among new users and -2% among returning. Textbook Simpson’s paradox; always add newVsReturning to the dimensions.
  • A LOWER ad load-fail rate is NOT automatically better — it may mean lower price floors. A load failure usually means no ad was available at the price asked, which is the designed behavior of a high floor (CloudX First Look sets floors at P90 eCPM precisely to reject cheap demand). A build that fails less may simply be asking for less money and filling more easily. Worse, the rate is attempt-based: measured on a real pair of builds, the newer one produced 1.43 load outcomes per load request against the older one’s 1.02 — it was retrying after failures, which pulls the failure rate down without delivering a single extra ad. Judge ad delivery on impressions actually shown per user (and completions for rewarded), never on fill or failure rates alone.
  • Fill only creates revenue when failures were leaving ad slots empty. How many ads a player sees is governed by gameplay moments, not by fill rate. On the same pair, load-fail improved from 29.8% to 24.5% while total ad_impression per user went down 4%.
  • The Data API rejects more than 10 metrics per request (Requests are limited to 10 metrics within a nested request). Batch wider metric sets.
  • Check whether THIS property sends revenue before estimating. Revenue presence varies per property (Spranky/Role Swap: $0; LifeStory 502056278: full totalAdRevenue). Always query totalAdRevenue by appVersion first; only fall back to an estimate when it is 0.
  • ARPDAU is not revenue per new user. A GA4 UI comparison with a “First session date” segment gives revenue per install cohort; ARPDAU is totalRevenue / summed daily activeUsers. They answer different questions — state which one you are reporting.
  • Read-only reporting. No mutating calls exist in this skill.
  • Never print or commit the client id, secret, or refresh token. The .env beside this skill is gitignored; document variable names only.
  • The scripts surface API error bodies verbatim (they carry activation URLs) but never echo credential values.

Working and verified end-to-end against live properties. Scripts are bundled and zero-dependency (Node 26+ built-ins). Not wired into any scheduled job — this is a manual investigation tool today. A natural next step, unbuilt: a watcher that queries only apps which shipped a new version recently and reports new-vs-previous ARPU.