Google Tracking

Google Tracking

Configure and manage the full Google tracking stack — GTM container management, GA4 analytics, live tag scanning, and custom script injection. This skill captures the exact architecture and patterns used across Lead Gen Jay.

Architecture Overview

Three layers handle Google tracking, each serving a distinct purpose:

1. GTM (primary) — Google Tag Manager container loaded globally via admin settings. Manages all Google tags (GA4, Google Ads, etc.) from a single container. This is the recommended approach.

2. GA4 standalone (fallback) — Direct gtag.js injection. Auto-skipped when GTM is configured to prevent double-counting. Only used when GTM is not set up.

3. GA4 Data API (server-side) — Service account authenticated API for querying analytics data. Powers the admin analytics dashboard. No client-side involvement.

Configuration Flow

Admin Settings UI (/admin/settings)
  → app_settings table (Supabase, key: "global_tracking")
    → GlobalTracking server component (fetches config)
      → TrackingScripts client component (renders scripts)
        → Next.js <Script> elements (afterInteractive strategy)

Key Files

TrackingConfig Interface

The core type used everywhere tracking is configured:

interface TrackingConfig {
  googleAnalyticsId?: string;      // G-XXXXXXX
  facebookPixelId?: string;        // Numeric pixel ID
  googleTagManagerId?: string;     // GTM-XXXXXX
  customHeadScripts?: string;      // Raw HTML <script> tags or pure JS
  customBodyScripts?: string;      // Raw HTML <script> tags or pure JS
}

Defined in src/types/document.ts. Used by both global settings and per-page settings (page_settings table).

Environment Variables

The GA4 Data API variables are only needed for the admin analytics dashboard. Client-side tracking (GTM/GA4 scripts) is configured entirely through the admin UI.

GTM-First Strategy

The codebase enforces a GTM-first approach to prevent double-counting:

// In tracking-scripts.tsx
const shouldLoadGA4 = googleAnalyticsId && !googleTagManagerId;

Rules:

• When googleTagManagerId is set, the standalone GA4 gtag.js script is never loaded
• GA4 should be configured as a tag inside GTM instead
• A dev console warning fires if both GTM and standalone GA4 IDs are configured
• Custom third-party scripts (Hyros, LinkedIn, TikTok, etc.) go in customHeadScripts

Script loading strategies:

• Head scripts (GTM, GA4, FB Pixel, custom head): afterInteractive — loads after page hydration
• Body scripts (custom body): lazyOnload — loads when browser is idle
• GTM noscript iframe: rendered directly in body as <noscript> fallback

Setting Up GTM

Via Admin UI (recommended)

1. Go to /admin/settings
2. Enter GTM container ID (e.g., GTM-XXXXXXX) in the Google Tag Manager field
3. Leave Google Analytics ID empty (configure GA4 inside GTM instead)
4. Save — changes take effect within 5 minutes (cache TTL)

Via API

curl -X PATCH /api/admin/settings/global-tracking \
  -H "Content-Type: application/json" \
  -d '{"tracking": {"googleTagManagerId": "GTM-XXXXXXX"}}'

Requires admin authentication via Supabase session cookie.

Database

Config is stored in the app_settings table:

-- key: 'global_tracking', value: JSONB TrackingConfig
SELECT value FROM app_settings WHERE key = 'global_tracking';

Adding Custom Tracking Scripts

Third-party scripts (Hyros universal, LinkedIn Insight, TikTok Pixel, etc.) go in the Custom Head Scripts field.

Via Admin UI

1. Go to /admin/settings
2. Paste script tags into the "Custom Head Scripts" field
3. Supports both raw <script> HTML and pure JavaScript

How parseScriptTags works

The parseScriptTags() function in tracking-scripts.tsx handles three input formats:

1. External scripts: <script src="https://example.com/script.js"></script> → renders as <Script src="..." strategy="afterInteractive" />
2. Inline scripts: <script>console.log("hello")</script> → renders as <Script dangerouslySetInnerHTML={{__html: '...'}} />
3. Raw JS (legacy): console.log("hello") → treated as inline script (backward compatible)

Multiple <script> tags in a single field are supported — each becomes its own Next.js <Script> element.

GA4 Data API Usage

The analytics dashboard uses fetchAnalyticsData(dateRange) from src/lib/analytics/ga4-client.ts. It runs 6 parallel report queries via Promise.all:

Page categorization

Pages are auto-categorized based on path prefixes:

• Landing: /insiders, /97-new, /aia, /cheatsheet
• Checkout: /insiders-checkout, /aia-checkout
• Tool: /tools/*, /skills
• Resource: /r/*, /doc/*, /downloads

Caching

• Analytics responses cached for 10 minutes in-memory (src/lib/analytics/cache.ts)
• Global tracking config cached for 5 minutes (src/lib/settings.ts)
• Pass bustCache: true to fetchAnalyticsData() to force a fresh fetch

Authentication

Uses BetaAnalyticsDataClient from @google-analytics/data with service account credentials:

new BetaAnalyticsDataClient({
  credentials: {
    client_email: process.env.GA4_SERVICE_ACCOUNT_EMAIL,
    private_key: process.env.GA4_PRIVATE_KEY?.replace(/\\n/g, "\n"),
  },
});

Tag Scanner (Verification)

The tag scanner in src/lib/website/tag-scanner.ts verifies that tracking tags are actually present in rendered page HTML.

Functions

// Scan a single page
scanPageTags(url: string, path: string): Promise<TagScanResult>

// Batch scan with concurrency limit (default: 3)
scanBatchTags(pages: { url, path }[], concurrency?: number): Promise<TagScanSummary>

Detection patterns

Tracking coverage audit

The /api/admin/website/tracking endpoint combines tag scanner data with configured settings to produce a coverage matrix showing which tags are active on which pages.

Admin UI

The Website Management dashboard (/admin/website) has a Tracking tab that displays:

• Coverage percentages per tag type
• Per-page tag presence matrix
• Live scan results vs configured settings

Troubleshooting

Relationship to Other Tracking

• Hyros: Server-side lead tracking via src/lib/hyros.ts. Universal script loaded via customHeadScripts. See the hyros-integration skill.
• PostHog: Loaded via customHeadScripts. Detected by tag scanner. MCP server available for querying.
• Meta Pixel: Has dedicated facebookPixelId field in TrackingConfig. Loaded by TrackingScripts directly.
• Other pixels (LinkedIn, TikTok, Google Ads): All go in customHeadScripts as raw <script> tags.

Common Patterns

Setting up tracking for a new project

1. Get GTM container ID from Google Tag Manager
2. Configure GA4 as a tag inside GTM (not standalone)
3. Enter GTM ID in admin settings
4. Add any third-party scripts to Custom Head Scripts
5. Verify with tag scanner or admin Website > Tracking tab

Adding GA4 Data API for analytics dashboard

1. Create a Google Cloud service account
2. Grant it Viewer access to the GA4 property
3. Set GA4_SERVICE_ACCOUNT_EMAIL, GA4_PRIVATE_KEY, GA4_PROPERTY_ID in .env.local
4. Add the same vars to Vercel environment
5. Analytics dashboard at /admin/website will start showing data

Debugging missing tracking

1. Check admin settings — is GTM/GA4 configured?
2. Run tag scanner from /admin/website Tracking tab
3. Compare configured IDs vs detected IDs
4. Check browser dev console for loading errors
5. Verify the GlobalTracking component is in the root layout