ADR 0002: GA4 Onboarding — Soft Gate (Accepted)

Status

Accepted — Option A — 11 Jun 2026. Decision owned by the founder.

Option B (OAuth auto-provision of GA4 account/property) is not rejected — recorded as a Phase 3+ consideration only, contingent on Google Analytics Admin API capability, OAuth app verification, and a viable tag path (likely k.js relay). Revisit when Phase 1–2 pilots prove the soft-gate model and Google API surface is stable for external apps.

Context

GA4 is the source of truth for cross-channel optimization (ga4-source-of-truth.md). Onboarding must balance:

• Client retains ownership of analytics data
• Minimal client IT during portal onboarding
• Honest optimization when GA4 is absent (never silent fallback)
• API realism — not every GA4 setup step is headless-automatable today

A prior discussion explored whether Kobi could create GA4 in the client's Google account via OAuth, self-grant Admin, configure key events, and auto-deploy measurement (gtag or k.js). Google’s Admin API supports property creation, key events, Ads links, and access bindings under OAuth — but new Analytics account creation still requires the client to accept Terms of Service in-browser (accounts.provisionAccountTicket). Tag deployment to the client website is not an Admin API concern; first-party relay (k.js) is a separate Phase 2+ track.

Decision drivers

Options considered

Option A — Soft gate + degraded mode (chosen for Phase 1)

Onboarding v1:

• Client invites Kobi (service account or automation user) as GA4 Administrator on an existing property — or Skip for now
• If Admin granted: Kobi links Ads ↔ GA4 via Admin API + reads via Analytics Data API
• Kobi does not create GA4 properties or accounts in v1
• Tag install: implementation guide only (gtag/GTM); no GTM publish automation
• If GA4 skipped or absent: explicit degraded mode — optimize on platform + CRM, degraded_attribution flag, tighter spend caps, visible banner (optimization.md)

Pros: Matches current portal UX; stable SA token; fewer OAuth scopes for pilot; no ToS provisioning flow in v1.

Cons: Extra client step (GA4 Admin invite); greenfield clients without GA4 need manual setup or skip.

Option B — OAuth GA4 auto-provision (Phase 3+ consideration only)

Hypothetical later flow:

1. Client Connect Google Analytics (OAuth) in portal
2. Detect existing property or start account ticket → client accepts Google ToS
3. API: properties.create, dataStreams.create, keyEvents.create, accessBindings.create (Kobi SA), properties.googleAdsLinks.create
4. Tags: implementation guide in interim; k.js relay (Phase 2+) as auto-deploy path once CNAME + loader are in place

Pros: Lower friction for clients without GA4; Kobi standard taxonomy applied consistently.

Cons: OAuth app verification (analytics.edit, analytics.manage.users); client personal-token fragility unless SA is bound post-create; ToS step not fully headless; consent/KVKK still required; API behavior and quotas must be re-validated before build.

Gate to promote from consideration to build:

• Phase 1–2 pilots complete with Option A; measure GA4 connect rate and support burden
• Google Admin API + OAuth verification path confirmed for external SaaS at Kobi’s scale
• Tag path decided: k.js relay SKU live or acceptable guide-only for auto-provisioned properties
• Legal sign-off on provisioning under client Google identity

Consequences

Phase 1 (now)

• Portal screen 5 unchanged: Invite Kobi Admin or Skip (onboarding-client-portal.md)
• Cross-check marks properties.create as deferred, not in v1 scope (onboarding-api-cross-check.md)
• Optimization agent must honor degraded mode when ga4_connected !== true
• PRE/onboarding tests cover: Admin granted → Ads link; skipped → onboarding completes without link

Phase 3+ (if Option B is promoted)

• New ADR amendment or ADR 0002 status → Superseded by Option B with migration plan for existing tenants
• OAuth consent screen + Google Cloud OAuth verification project
• Portal replaces or supplements “invite” with “Connect Google Analytics”
• Property naming: Kobi - {tenant_name} under client account (ga4-source-of-truth.md)

Related decisions

References

• GA4 source of truth
• Onboarding
• Onboarding API cross-check §3 GA4
• First-party tag relay (k.js) — tag path for Option B
• Google Analytics Admin API