t1k:marketing:analytics:firebase
| Field | Value |
|---|---|
| Module | analytics |
| Version | 1.21.13 |
| Effort | low |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:marketing:analytics:firebaseFirebase 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.
When to Use
Section titled “When to Use”- 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
When NOT to Use
Section titled “When NOT to Use”- 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. Seereferences/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; seereferences/other-version-apis.md. - Rigorous retention-by-version — a user’s
appVersionchanges 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:
| API | Needed for |
|---|---|
analyticsdata.googleapis.com — Google Analytics Data API | every 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):
bun scripts/ga4_oauth_setup.js # --port to match a registered redirect URIIt 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:
bun scripts/ga4_oauth_setup.js --label second # writes GA4_REFRESH_TOKEN_SECONDbun 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 _.
Running a report
Section titled “Running a report”# Discover property ids — one GA4 property per Firebase appbun scripts/ga4_appversion.js --listbun scripts/ga4_appversion.js --list --filter puzzle
# One app, one daybun scripts/ga4_appversion.js --property 522904484 --date 2026-08-18
# One app across a window — this is where multiple versions actually appearbun scripts/ga4_appversion.js --property 522904484 --start 2026-07-20 --end 2026-08-18
# Several apps at once, to CSVbun scripts/ga4_appversion.js --property 522904484,468898317 --date 2026-08-18 --csv out.csv| Flag | Meaning |
|---|---|
--list | List visible GA4 properties (id, name, account). Implied when --property is absent. |
--filter | Substring match on property or account name, for use with --list. |
--property | Property id, or a comma-separated list. A property that fails does not abort the others. |
--date | Single day. Defaults to yesterday. |
--start / --end | Date range (overrides --date). |
--metrics | Comma-separated override of the auto-selected metric list. |
--csv | Write results to a CSV file. |
Comparing two builds head-to-head
Section titled “Comparing two builds head-to-head”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.
bun scripts/ga4_version_compare.js --property 470996808 --versions 1.1.7,1.1.8 \ --start 2026-08-13 --end 2026-08-18bun scripts/ga4_version_compare.js --property 470996808 --versions 1.1.7,1.1.8 \ --date 2026-08-18 --segment newFunnel 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.
Metrics
Section titled “Metrics”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.
Hard rules
Section titled “Hard rules”- GA4 revenue ≈ the MAX slice only, not total ad revenue. It is built from
ad_impressionevents 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,purchaseRevenueandeventValue, with no error. Checkmetadata.schemaRestrictionResponse.activeMetricRestrictionsfirst (the script prints a WARNING). Seereferences/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_impressionevents that day — GA4 derives revenue only when those events carryvalue+currency, and these carried neither (eventValuecame back0.0000on 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 aneventNamexeventValuereport first. - Impression counts are usable even when revenue is not. When
valueis missing you can still comparead_impressionper 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
1and3alongside1.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_impressionper user read +9% for the new build, but splitting by thenewVsReturningdimension showed -5% among new users and -2% among returning. Textbook Simpson’s paradox; always addnewVsReturningto 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_impressionper 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 querytotalAdRevenuebyappVersionfirst; 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.
Security
Section titled “Security”- Read-only reporting. No mutating calls exist in this skill.
- Never print or commit the client id, secret, or refresh token. The
.envbeside this skill is gitignored; document variable names only. - The scripts surface API error bodies verbatim (they carry activation URLs) but never echo credential values.
Status
Section titled “Status”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.