Skip to content

firebase CLAUDE_AI_SETUP

Jump to bottom
github-actions[bot] edited this page Sep 3, 2026 · 3 revisions

cmp-firebase — Claude AI Setup Guide

/sync-firebase-analytics is a verify-gated sync that wires cmp-firebase into a consuming KMP app. Run from anywhere in the project; Claude detects the active project and walks the gates.

Quick Commands

/sync-firebase-analytics           # Full sync — Gradle + Firebase config + DI + (optional) MP secret
/sync-firebase-analytics --check   # Dry run — show status, no writes
/lib-sync cmp-firebase   # Same as /sync-firebase-analytics

What the Skill Does

/sync-firebase-analytics
        |
        v
+------------------------------------------------------------+
|  GATE 1: Gradle Dependency                                 |
|  Check: cmp-firebase:VERSION in libs.versions    |
|  Check: used in commonMain.dependencies                    |
|  Fix:   Auto-insert correct entries                        |
|  Result: PASS / FIXED / BLOCKED                            |
+----------------------------+-------------------------------+
                             | PASS
                             v
+------------------------------------------------------------+
|  GATE 2: Firebase Config Files (per platform)              |
|  Check: androidApp/google-services.json (Android target)   |
|  Check: cmp-ios/{app}/GoogleService-Info.plist (Apple)     |
|  Check: jsMain init (JS target)                            |
|  Fix:   Surface manual download steps if missing.          |
|         Library NEVER auto-creates these — they contain    |
|         your Firebase project's API keys.                  |
|  Result: PASS / MISSING (with remediation) / SKIPPED       |
+----------------------------+-------------------------------+
                             | PASS
                             v
+------------------------------------------------------------+
|  GATE 3: DI Wiring (Koin)                                  |
|  Check: AnalyticsModule import in app's KoinModules.kt     |
|  Check: AnalyticsHelper bound in module {}                 |
|  Fix:   Auto-insert AnalyticsModule + Mode.Firebase wiring |
|  Result: PASS / FIXED / SKIPPED (no Koin detected)         |
+----------------------------+-------------------------------+
                             | PASS
                             v
+------------------------------------------------------------+
|  GATE 4: PROJECT_CONFIG.analytics block (optional)         |
|  Check: idea-layer/PROJECT_CONFIG.yaml has analytics block |
|  Fix:   Auto-scaffold from template (property_id required) |
|  Result: PASS / FIXED / SKIPPED                            |
+----------------------------+-------------------------------+
                             | PASS
                             v
+------------------------------------------------------------+
|  GATE 5: MP API Secret (conditional)                       |
|  Trigger: app targets JVM / linuxX64 / linuxArm64 /        |
|           mingwX64 (any of the 4 nonFirebaseMain)          |
|  Check: release-layer/.env contains MP_API_SECRET          |
|  Check: PROJECT_CONFIG.analytics.measurement_protocol.     |
|         api_secret_secret_ref is set                       |
|  Fix:   Surface UI step (Firebase Console → MP Secrets);   |
|         prompt for value; write to .env                    |
|  Result: PASS / FIXED / NOT_NEEDED                         |
+------------------------------------------------------------+
                             |
                             v
                       SYNC COMPLETE

State Summary Output

+======================================================================+
|  /sync-firebase-analytics — COMPLETE                                  |
+======================================================================+
|  GATE 1   Gradle           [OK]  cmp-firebase:1.0.0        |
|  GATE 2   Firebase config  [OK]  google-services.json + Plist + JS   |
|  GATE 3   DI wiring        [OK]  AnalyticsHelper bound in Koin       |
|  GATE 4   PROJECT_CONFIG   [OK]  analytics block present             |
|  GATE 5   MP secret        N/A   no nonFirebase platforms targeted   |
+----------------------------------------------------------------------+
|  Targets covered: 15/15                                              |
|    firebaseMain (10): Android, iOS×3, macOS×2, tvOS×3, JS            |
|    nonFirebaseMain  (5): N/A — not targeted by this app              |
+----------------------------------------------------------------------+
|  Docs: docs/firebase/SETUP.md                              |
|  Next: /idea analytics --setup  (framework: enable BigQuery readback)|
+======================================================================+

Team Scenarios

First-time integration on a fresh project

/sync-firebase-analytics
# Gate 1 adds dependency to libs.versions.toml + build.gradle.kts
# Gate 2 detects missing google-services.json — surfaces UI step
#        ("Download from Firebase Console → Project Settings → Your apps")
# User downloads the file, drops it in androidApp/, re-runs:
/sync-firebase-analytics
# Gate 2 PASS, Gate 3 wires Koin, Gate 4 scaffolds PROJECT_CONFIG, done.

Version bump (cmp-firebase 1.0.0 → 1.1.0)

/sync-firebase-analytics
# Gate 1 detects old version, updates libs.versions.toml + verifies still used
# Other gates pass through (already wired).

Adding JVM (desktop) or Linux targets to an existing app

/sync-firebase-analytics
# Gates 1-4 already pass.
# Gate 5 detects new jvm / linuxX64 / linuxArm64 / mingwX64 targets → triggers MP setup.
# Surfaces the full step-by-step (see "How to generate an MP API secret" below).
# Recommended: run /secrets pull — vault aliases mbs-ga4-property-id + <proj>-mp-api-secret.
# Fallback: paste the MP API secret; Gate 5 writes to release-layer/.env and updates PROJECT_CONFIG.

How to generate an MP API secret

Required when Gate 5 fires (any of jvm / linuxX64 / linuxArm64 / mingwX64 / wasmJs in your build.gradle.kts). Skip this entirely if your app only targets Android/iOS/macOS/tvOS/JS — those use native GitLive SDK auth.

What it is

A short string token (typically 22 chars, looks like abc1d2e3f4-XYZ_a8B7c6D5e4F3g2H) that authorizes HTTP POSTs to Google's Measurement Protocol endpoint. It is the least-privileged Firebase credential — can only write events to one specific GA4 data stream, can't read anything, can't admin.

Step-by-step (Firebase Console UI)

  1. Open Firebase Console → click your project
  2. Click the gear icon (top-left, next to "Project Overview") → Project Settings
  3. Click the Integrations tab
  4. Find the Google Analytics card → click Manage (or Open in GA4)
  5. In the GA4 admin pane, navigate: Admin → Data Streams
  6. Click your data stream — pick the one matching the platform tier you're enabling MP for:
    • Web stream → for wasmJs / browser deploys
    • For jvm / linuxX64 / linuxArm64 / mingwX64, use whichever stream represents your "desktop" presence (often Web)
  7. Scroll to Measurement Protocol API secrets (bottom of the stream details page)
  8. Click Create
  9. Give it a descriptive name (e.g., jvm-prod, linux-staging)
  10. Copy the secret value immediately — it is shown ONCE. If you lose it, create a new one.

Where the secret goes

Recommended (vault-first): Gate 5 will prompt you to run /secrets pull. Analytics is org-global — two org-level secrets + per-app stream identity (see SETUP.md §2 mapping table):

  • mbs-firebase-sa — Firebase/GCP service-account JSON (ORG / workspace)
  • mbs-ga4-property-id — shared GA4 property id, numeric e.g. 473327398 (ORG / workspace)
  • <proj>-ga4-measurement-id — this app's GA4 stream measurement id G-XXXXXXXX (PROJECT)
  • <proj>-mp-api-secret — this app's Measurement-Protocol API secret (PROJECT, RULE-SECRETS-VAULT-001)

Fallback — paste when Gate 5 prompts you, OR add manually:

# release-layer/.env (gitignored — verify it's in your .gitignore)
MP_API_SECRET=abc1d2e3f4-XYZ_a8B7c6D5e4F3g2H
# idea-layer/PROJECT_CONFIG.yaml
analytics:
  envs:
    prod:
      property_id: G-XXXXXXXX
      measurement_protocol:
        api_secret_secret_ref: MP_API_SECRET   # env-var name; resolved at runtime

Secret hygiene (Hard Rules)

Rule Why
Use the vault (/secrets pull) Aliases mbs-firebase-sa / mbs-ga4-property-id / <proj>-mp-api-secret; no .env, no gh secret set (RULE-SECRETS-VAULT-001)
Never commit the value A leaked secret lets anyone write fake events to your GA4 stream (skews your funnel/retention metrics)
Never log the value App logs leak to crash reporters, third-party SDKs, dev consoles
Rotate on suspected leak Firebase Console → revoke old → create new → /secrets pull → redeploy app
One per environment Separate secrets for prod / staging / dev; don't share across
One per project Each Firebase project has its own; the mood-movies secret won't work for reels-downloader
Load from CI vault /secrets pull in CI. Never hard-code in build.gradle.kts

How MP secret differs from other Firebase credentials

Credential Privilege Used by
google-services.json / GoogleService-Info.plist Native SDK auto-config Android / iOS / macOS / tvOS native SDK
Firebase Web Config Native SDK auto-config Firebase JS SDK
Firebase Service Account JSON High — signs JWTs for any Firebase API Server-side (Crashlytics fetch, BigQuery, etc.)
MP API secret Lowest — write-only to one GA4 stream HTTP fallback for MeasurementProtocolAnalyticsHelper only

Dry run

/sync-firebase-analytics --check
# Shows current sync status across all 5 gates without modifying any files.
# Use to audit: PR review, CI pre-merge check, debugging "why aren't events flowing"

Project-Specific Keys (Hard Rule)

The library bakes in zero defaults for project-specific config. Every project supplies its own:

Item Where it lives Committed? Vault alias
google-services.json androidApp/google-services.json ❌ gitignored — (per-app identity, not an org secret)
GoogleService-Info.plist cmp-ios/{app}/GoogleService-Info.plist ❌ gitignored —
Firebase JS config jsMain init (keys loaded from env at build time) ❌ keys via env —
Firebase SA JSON Vault → /secrets pull materializes to secrets/live/ ❌ vault only mbs-firebase-sa
GA4 property_id (G-XXXXXXXX) idea-layer/PROJECT_CONFIG.yaml analytics.envs.{env}.property_id ✅ (not a secret) mbs-ga4-property-id (read via vault)
MP API secret Vault → /secrets pull; fallback: release-layer/.env ❌ vault only <proj>-mp-api-secret

/sync-firebase-analytics Gate 2 + Gate 5 verify presence and surface manual steps when missing — they NEVER auto-generate keys (they don't exist to generate).

Library API Quick Reference

Public types

io.github.mobilebytelabs.kmptoolkit.firebase.analytics.*
├── AnalyticsHelper                    interface — logEvent, logScreenView, logError, ...
├── AnalyticsEvent / Param             type-safe event + param data classes
├── EventTypes / ParamKeys             standard string constants
├── StubAnalyticsHelper                dev: logs to Kermit
├── NoOpAnalyticsHelper                release/test: discards events
├── TestAnalyticsHelper                tests: captures events for assertions
├── EventValidator                     taxonomy regex + PII regex (debug builds)
├── PerformanceTracker                 start/stop/measure block timer
├── EventRegistry                      declared-event enforcement (opt-in)
├── provideAnalyticsHelper()           expect/actual factory (firebaseMain → Firebase, else NoOp)
└── di.AnalyticsModule.Mode            { Firebase | Stub | NoOp }

io.github.mobilebytelabs.kmptoolkit.firebase.analytics.*
└── FirebaseAnalyticsHelper            firebaseMain only — wraps GitLive

io.github.mobilebytelabs.kmptoolkit.firebase.analytics.mp.*
├── MeasurementProtocolAnalyticsHelper commonMain — for nonFirebase platforms
├── MpConfig                           data class(measurementId, apiSecret, endpoint?)
└── ClientId                           internal — multiplatform-settings backed

Convenience methods

analytics.logScreenView(screenName, sourceScreen?)
analytics.logButtonClick(buttonName, screenName?)
analytics.logError(errorMessage, errorCode?, screen?)
analytics.logStateTransition(screenName, from, to)
analytics.logFeatureUsed(featureName, screen?)
analytics.setUserProperty(name, value)
analytics.setUserId(hashedUserId)

Builder DSL

analytics.log(EventTypes.FORM_COMPLETED) {
    param(ParamKeys.FORM_NAME, "registration")
    param(ParamKeys.COMPLETION_TIME, 45)        // numbers
    param("custom_metric", true)                // booleans
}

Sister Commands (claude-product-cycle framework)

  • /idea analytics — full growth pipeline (capture → BigQuery fetch → Claude analysis → ranked plan → optional codegen). See IDEA_ANALYTICS_GUIDE.md in the framework.
  • /idea firebase-crash — same auth pattern, parallel command for Crashlytics.

Docs

** Partials**

App Intents

Bubble

Clipboard

Cookbook

Firebase

In App Update

Intent Launcher

Inter App Comms

Modules

Network Monitor

Open Url

Pdf Generator

Remote Config

Share

Superpowers

Toast

User Tickets

General

Clone this wiki locally