Google Analytics Integration

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/google-analytics-integration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A core feature that connects the shop to Google Analytics 4, automatically sends conversion data (orders, revenue, customer acquisition) and funnel events (cart abandon, checkout step, payment method choice), and gives merchants a dashboard showing traffic and sales trends without manual configuration.

The problem

A Polish e-commerce merchant has traffic but no data. She doesn’t know if her social-media ads work, which landing pages convert best, or where visitors abandon cart. She can’t see product-level ROI. Adding GA4 to her shop required developer help (€500). She wants built-in analytics so she can make data-driven decisions.

What it does

• GA4 property creation: auto-connect shop to GA4 (via Google OAuth), no manual code needed
• Event tracking: auto-send events to GA4 for purchase, add-to-cart, view-item, begin-checkout
• Revenue tracking: orders and line-item revenue sync to GA4 in real-time
• Customer tracking: GA4 user ID linked to shop customer (cross-session tracking)
• Conversion attribution: track which channel (organic, paid, email) led to purchase
• Product performance: GA4 shows which products drive revenue, which are low-engagement
• Admin dashboard: traffic (users, sessions), revenue (total, per-channel), top products, top landing pages
• Goal/conversion setup: auto-configure GA4 goals (e.g., ‘order placed’ = conversion)
• Historical sync: optionally backfill GA4 with past orders (if GA4 is just enabled)
• Opt-out support: customers can opt-out of GA4 tracking (via privacy settings or Do-Not-Track)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Google Ads (Google’s paid advertising platform)—different service; we integrate, not manage
• Attribution modeling beyond GA4’s built-in—out of scope (GA4 handles this)
• Custom event logic (e.g., ‘track if customer spent >€100’)—merchant can build via webhooks
• Machine learning forecasts (e.g., ‘predict revenue next month’)—out of scope (GA4’s predictive analytics is separate)
• Privacy-first analytics (e.g., Plausible, Fathom)—out of scope; GA4-specific

Data model

New: GoogleAnalyticsConfig(shopId, ga4_property_id, measurement_id, sync_enabled, created_at). Stored in core settings, not a separate schema migration.

API

• POST /integrations/google-analytics/connect — OAuth flow to authorize GA4
• GET /integrations/google-analytics/status — return connection status
• POST /integrations/google-analytics/disconnect — remove GA4 connection
• POST /integrations/google-analytics/sync-events — manual trigger to backfill past orders
• GET /analytics/dashboard — return traffic, revenue, product performance (from GA4)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Analytics dashboard: traffic overview (users, sessions, bounce rate), revenue (total, per-channel), top products, top landing pages, goal completions (orders), customer acquisition cost (if ads data available)

The seam — why this is core

Core owns: order/checkout data structure, event logging on frontend. Paid pack owns: GA4 connection, event schema mapping, historical backfill, advanced analytics features (attribution, forecasting).

Core owns the interface + honest GA4 connector; analytics is infrastructure, not a per-country obligation or support commitment.

Dependencies

• core checkout flow (orders, cart data must exist)
• Next.js storefront integration (GA4 tracking code must run on frontend)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Connecting GA4 via OAuth creates GoogleAnalyticsConfig and returns connection status=‘connected’
• A customer completes an order; GA4 receives ‘purchase’ event with order ID, revenue, currency within 5 seconds
• Analytics dashboard shows 1000+ users, 50 orders, €5000 revenue for last 30 days
• Top 5 products by revenue are listed in dashboard (matches GA4 data)
• Traffic by channel (organic, direct, paid) is shown in dashboard breakdown
• Disconnecting GA4 stops sending events; new orders don’t appear in GA4
• Backfilling 3 months of past orders sends all 500 orders as purchase events to GA4
• A customer with Do-Not-Track enabled is not tracked (GA4 receives no events for them)

Risks

GA4 connection breaks (OAuth token expires or revoked)—events stop flowing; must alert merchant. Event mapping wrong: ‘purchase’ event sent with malformed data (missing revenue)—GA4 ignores it. Privacy: if shop stores too much PII and sends to GA4, GDPR violation—must validate data before sending. Backfill performance: if syncing 1M+ past orders, GA4 API rate limits hit—must implement retry/backoff.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.