Analytics

The analytics documentation consolidates everything we need to measure the ignitionstack.pro funnel with Google Analytics 4 (GA4). All instrumentation follows the BDD specifications described in contents/prompts/features/08 - analytics-tracking-bdd.md and is versioned in the main repository.

The source of truth for these docs lives in docs/google-analytics. That directory contains the full specifications (ANALYTICS_EVENTS.md), the long-form documentation (GA_EVENTS_DOCUMENTATION.md), the quick reference, and implementation examples.

Stack Overview

Google Analytics 4

Measurement ID configured via NEXT_PUBLIC_GA_ID and injected in src/app/layout.tsx with the gtag-base and gtag-config scripts.
The WebVitals component (src/app/components/analytics/web-vitals.tsx) sends Core Web Vitals to GA4 and to /api/analytics/web-vitals using navigator.sendBeacon.
The deduplicated gtag loader sets anonymize_ip, cookie_flags, and forces client_storage: 'none' to meet privacy requirements.

Tracking Layers

Layer	File	Responsibility
Core client	`src/app/lib/analytics.ts`	Exposes `trackGAEvent`, `trackPageView`, `getCurrentPageMetadata`, and maps routes → `funnel_stage` with `getFunnelStageFromPath`. It also validates required params and injects `environment`.
Event registry	`src/app/lib/analytics-events.ts`	Typed helpers (`landingPageEvents`, `blogEvents`, `contactEvents`, etc.) that enforce `snake_case` naming and the right funnel for each event.
Hooks	`src/app/hooks/use-page-view.ts`, `use-click-tracking.ts`, `use-intersection-tracking.ts`	Automate page views, clicks, and section impressions based on the BDD specs (e.g., fire `section_view` when 60% of the section is visible).
Helper components	`src/app/components/analytics/web-vitals.tsx`, `src/app/components/landing-page/*`	Consume the hooks/registry helpers and centralize event firing inside UI components.

Instrumentation Flow

Automatic page view – call usePageView(locale) in the route layout. The hook uses trackPageView, deduplicates events by locale + page_path, and adds page_location, page_title, environment, and funnel_stage.
UI events – import the registry groups:


import { landingPageEvents, contactEvents } from "@/app/lib/analytics-events";
import { useClickTracking } from "@/app/hooks/use-click-tracking";
 
const { trackClick } = useClickTracking();
 
trackClick("hero_primary_cta_click", {
  source_component: "home_hero",
  cta_id: "hero_primary",
  destination: `/${locale}#projects`,
});
 
landingPageEvents.heroCTAClick({
  destination: `/${locale}#projects`,
  cta_type: "primary",
  page_path,
  page_title,
  locale,
});

Impressions / scroll – create a ref with useIntersectionTracking({ sectionId: "home_about", funnelStage: "awareness" }) and the hook fires section_view when ≥60% of the area is visible.
Web Vitals – no extra configuration needed: WebVitals already sends metrics such as CLS, INP, and LCP to GA and to the internal endpoint.

Current Event Coverage

The numbers below come from docs/google-analytics/ANALYTICS_EVENTS.md and represent the status on 2025-10-07.

Category	Total	Implemented	Pending
Global	3	1	2
Home	8	0	8
Contact	6	0	6
Store	3	0	3
Recommendations	1	0	1
Projects	2	0	2
Footer	2	0	2
TOTAL	25	1	24

Use the Events page to see each event with parameters, responsible components, and detailed status.

Process to Create a New Event

1. Define the event in the registry

Add the proper helper in src/app/lib/analytics-events.ts, following the [section]_[component]_[action] convention and using snake_case parameters.

2. Mirror the BDD scenario

Update docs/google-analytics/ANALYTICS_EVENTS.md and keep the implementation status (✅ or ⏳) aligned with reality.

3. Consume it in the component

Import the helper or use useClickTracking in the responsible React component. Always fill the required params (locale, page_path, page_title, funnel_stage, source_component).

4. Validate

Enable debug mode with localStorage.setItem('GA_DEBUG', 'true') or use GA4 DebugView to inspect the payload before deploying.

Debugging and QA

GA DebugView – https://support.google.com/analytics/answer/7201382
Local console – in development payloads go through the Pino logger (createServiceLogger('analytics')).
Chrome extension – Google Analytics Debugger
Web Vitals – monitored in the console and sent to /api/analytics/web-vitals in production.

Events – complete documentation (based on GA_EVENTS_DOCUMENTATION.md).
Quick Reference – condensed trigger table.
Tracking Examples – practical snippets extracted from GA_TRACKING_EXAMPLES.md.
Environment Setup – required variables (NEXT_PUBLIC_GA_ID).
Source files in the main repo: docs/google-analytics/*.md, src/app/lib/analytics*.ts, and src/app/hooks/*tracking*.ts.