@kido/traffic-attributionCopy Anchor Link

Architecture Paradigm: Zero-TBT Idle Telemetry Loader + AI Agent Classifier + Speculative Prefetch Gate + First-Party OTLP Proxy + 12KB HyperLogLog Engine.

💥 The Real-World Bottleneck (Why It Exists)Copy Anchor Link

In high-growth consumer and SaaS platforms, marketing tracking requirements directly undermine frontend performance and engineering reliability:

1. The 800ms+ Total Blocking Time (TBT) CWV Penalty:
   • Synchronously injecting Google Analytics 4 (GA4), Meta Pixel, Hotjar, and Sentry inside <head> or via Google Tag Manager (GTM) monopolizes the browser main thread for 500–1,200ms during page load.
   • Result: Google Search penalizes organic ranking due to failed Core Web Vitals (CWV) metrics (INP > 200ms, LCP > 2.5s).
2. Speculative Browser Prefetch Draining Ad Spend:
   • Modern browsers (Chrome, Edge, Safari) proactively prefetch links hovered or predicted in search results using sec-purpose: prefetch.
   • Naïve analytics log these as actual user visits and conversions, inflating affiliate payouts, poisoning conversion funnels, and burning third-party ad budgets on phantom visitors.
3. Ad-Blockers Blind-Spotting 35%+ of Technical Traffic:
   • 35% to 50% of technical, developer, and privacy-conscious users run uBlock Origin or Brave browser, blocking requests to google-analytics.com and clarity.ms.
4. Sentry Noise Bill Explosion:
   • Automated penetration testing bots, scraping crawlers, and aggressive browser extensions (such as translation tools or password managers) trigger millions of harmless console errors, exhausting monthly Sentry quotas in days.

🏛️ 3-Tier Production Evolution LadderCopy Anchor Link

📐 Architecture & Data FlowCopy Anchor Link

📦 Architecture & Core API ExportsCopy Anchor Link

All capabilities are strictly isolated in packages/traffic-attribution:

1. src/deferred-telemetry/Copy Anchor Link

• DeferredTelemetryLoader: Main-thread non-blocking loader deferring script injection until requestIdleCallback fires or user interaction occurs (touch, scroll, keydown).
• createGA4Plugin(config): Deferred Google Analytics 4 plugin.
• createClarityPlugin(config): Deferred Microsoft Clarity heatmap plugin.
• createMetaPixelPlugin(config): Deferred Meta Pixel conversion tracking plugin.
• createSentryBeforeSend(options): Sentry error sanitizer dropping Cốc Cốc, Zalo in-app webview noise, and browser extension stack frames.
• filterSentryTransaction(options): Discards runaway background transactions exceeding 28s.

2. src/ai-detection.tsCopy Anchor Link

• detectTrafficSource(options): Multi-signal parser identifying traffic channel (ai_agent, search_engine, social_network, direct, referral) and platform (chatgpt, claude, perplexity, deepseek, gemini, google, tiktok).
• isAiTraffic(source): Boolean helper detecting generative engine traffic.

3. src/prefetch-filter.tsCopy Anchor Link

• isSpeculativePrefetch(headers): Detects browser speculative prefetch headers (sec-purpose: prefetch, purpose: prefetch, x-moz: prefetch, x-prerender).

4. src/bitmask-rotater.tsCopy Anchor Link

• selectUnvisitedLinkBitmask(links, cookieMask): Stateless integer bitmask A/B link rotator stored in cookies with zero database overhead.
• createBitmaskCookieString(name, bitmask): Formats standard Set-Cookie header.

5. src/hll-analytics/Copy Anchor Link

• HllAnalyticsEngine: HyperLogLog cardinality engine counting 1,000,000 unique visitors in 12 KB of RAM with 99% accuracy.
• MemoryHllDriver: In-memory HyperLogLog driver for single-node setups.
• IoRedisHllDriver: Distributed Redis HyperLogLog driver utilizing native PFADD and PFCOUNT.

6. src/otlp-vitals-proxy/Copy Anchor Link

• forwardOtlpTelemetry(req, options): Edge handler proxying Real User Monitoring (RUM) metrics through a first-party domain to bypass ad-blockers.

💻 Production Implementation & Code SnippetCopy Anchor Link

1. Client-Side Telemetry Gate (src/components/telemetry-gate.tsx)Copy Anchor Link

'use client';

import { useEffect } from 'react';
import {
  DeferredTelemetryLoader,
  createGA4Plugin,
  createClarityPlugin,
  createMetaPixelPlugin,
} from '@kido/traffic-attribution';

export function TelemetryGate() {
  useEffect(() => {
    // 1. Initialize deferred loader with a 3,500ms fallback timeout
    const loader = new DeferredTelemetryLoader({
      idleTimeoutMs: 3500,
      plugins: [
        createGA4Plugin({ measurementId: 'G-XXXXXXXXXX' }),
        createClarityPlugin({ projectId: 'YYYYYYYY' }),
        createMetaPixelPlugin({ pixelId: '1234567890' }),
      ],
    });

    // 2. Arm the loader (listens for requestIdleCallback or first scroll/touch)
    loader.arm();

    return () => {
      loader.disarm();
    };
  }, []);

  return null;
}

2. Sentry Client Configuration (sentry.client.config.ts)Copy Anchor Link

import * as Sentry from '@sentry/react';
import {
  createSentryBeforeSend,
  filterSentryTransaction,
} from '@kido/traffic-attribution';

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  tracesSampleRate: 0.1,
  // Drop harmless browser extension crashes & in-app webview noise
  beforeSend: createSentryBeforeSend({
    dropGenericWebviewNoise: true, // Filters Zalo & Cốc Cốc webview script injection
    ignoreExtensions: true,        // Filters chrome-extension:// errors
  }),
  // Clamp transactions longer than 28 seconds
  beforeSendTransaction: filterSentryTransaction({
    maxDurationMs: 28_000,
    dropBackgroundTransactions: true,
  }),
});

3. Edge HTTP Request Handler (src/middleware.ts or Edge API)Copy Anchor Link

import {
  detectTrafficSource,
  isSpeculativePrefetch,
  selectUnvisitedLinkBitmask,
  createBitmaskCookieString,
} from '@kido/traffic-attribution';

export async function handleHttpRequest(req: Request) {
  // 1. Drop speculative prefetch requests with HTTP 204
  if (isSpeculativePrefetch(req.headers)) {
    return new Response(null, { status: 204 });
  }

  // 2. Classify incoming traffic (detects ChatGPT, Claude, Perplexity)
  const source = detectTrafficSource({
    referer: req.headers.get('referer'),
    userAgent: req.headers.get('user-agent'),
    internalDomains: ['example.com'],
  });

  if (source.channel === 'ai_agent') {
    console.log(`[AI-CRAWLER] Bot identified: ${source.platform}`);
  }

  // 3. Stateless A/B Destination Rotation via Cookie Bitmask (0 DB reads)
  const offers = [
    'https://example.com/pricing-v1',
    'https://example.com/pricing-v2',
    'https://example.com/pricing-v3',
  ];
  const cookieHeader = req.headers.get('cookie') || '';
  const bitmask = cookieHeader.match(/ab_mask=(\d+)/)?.[1] || '0';
  const { selectedItem, nextBitmask } = selectUnvisitedLinkBitmask(offers, bitmask);

  return new Response(null, {
    status: 302,
    headers: {
      Location: selectedItem,
      'Set-Cookie': createBitmaskCookieString('ab_mask', nextBitmask),
    },
  });
}

⚡ Benchmark & Verified PerformanceCopy Anchor Link

Tested under simulated 100,000 requests/sec with k6:

🚀 Surgical Extraction & CLI InstallationCopy Anchor Link

npx @kido/cli add traffic-attribution