add reusable analytics tracking (#16)

romanindev · web-flow · commit 6768e4335272 · 2026-03-22T10:44:00.000+01:00
diff --git a/src/App.tsx b/src/App.tsx
@@ -1,6 +1,8 @@
+import { useEffect } from 'react';
 import { Suspense } from 'react';
 import { useRoutes } from 'react-router-dom';
 import { Box, CircularProgress } from '@mui/material';
+import { trackScrollDepth, trackTimeOnPage } from './services/analytics';
 import { routes } from './app/router';
 
 const Loader = () => {
@@ -14,5 +16,15 @@ const Loader = () => {
 export default function App() {
   const element = useRoutes(routes);
 
+  useEffect(() => {
+    const cleanupScroll = trackScrollDepth();
+    const cleanupTime = trackTimeOnPage(30);
+
+    return () => {
+      cleanupScroll();
+      cleanupTime();
+    };
+  }, []);
+
   return <Suspense fallback={<Loader />}>{element}</Suspense>;
 }
diff --git a/src/components/Footer/Footer.tsx b/src/components/Footer/Footer.tsx
@@ -1,5 +1,5 @@
 import { Box, Container, Link, Stack, Typography } from '@mui/material';
-import { createTrackedLinkHandler } from '../../services/analytics-handlers.ts';
+import { createTrackedLinkHandler } from '../../services/analytics';
 
 export const Footer = () => {
   return (
@@ -28,10 +28,13 @@ export const Footer = () => {
               target="_blank"
               rel="noreferrer"
               underline="hover"
-              onClick={createTrackedLinkHandler('npm', {
-                location: 'footer',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'npm',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'npm',
+                  location: 'footer',
+                  label: 'npm',
+                  link_url: 'https://www.npmjs.com/package/@dfsync/client',
+                },
               })}
             >
               npm
@@ -41,10 +44,13 @@ export const Footer = () => {
               target="_blank"
               rel="noreferrer"
               underline="hover"
-              onClick={createTrackedLinkHandler('github', {
-                location: 'footer',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'GitHub',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'github',
+                  location: 'footer',
+                  label: 'GitHub',
+                  link_url: 'https://github.com/dfsyncjs/dfsync',
+                },
               })}
             >
               GitHub
diff --git a/src/components/Header/Header.tsx b/src/components/Header/Header.tsx
@@ -3,7 +3,7 @@ import { AppBar, Box, Button, Container, Toolbar } from '@mui/material';
 import { Link as RouterLink } from 'react-router-dom';
 import { Brand } from '../Brand/Brand';
 import { ThemeToggle } from '../ThemeToggle/ThemeToggle';
-import { createTrackedLinkHandler } from '../../services/analytics-handlers.ts';
+import { createTrackedLinkHandler } from '../../services/analytics';
 
 export const Header = () => {
   return (
@@ -25,10 +25,13 @@ export const Header = () => {
               component={RouterLink}
               to="/docs"
               color="inherit"
-              onClick={createTrackedLinkHandler('docs', {
-                location: 'header',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'Docs',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'docs',
+                  location: 'header',
+                  label: 'Docs',
+                  link_url: '/docs',
+                },
               })}
             >
               Docs
@@ -38,10 +41,13 @@ export const Header = () => {
               href="https://www.npmjs.com/package/@dfsync/client"
               target="_blank"
               rel="noreferrer"
-              onClick={createTrackedLinkHandler('npm', {
-                location: 'header',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'npm',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'npm',
+                  location: 'header',
+                  label: 'npm',
+                  link_url: 'https://www.npmjs.com/package/@dfsync/client',
+                },
               })}
             >
               npm
@@ -52,10 +58,13 @@ export const Header = () => {
               target="_blank"
               rel="noreferrer"
               startIcon={<GitHubIcon />}
-              onClick={createTrackedLinkHandler('github', {
-                location: 'header',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'GitHub',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'github',
+                  location: 'header',
+                  label: 'GitHub',
+                  link_url: 'https://github.com/dfsyncjs/dfsync',
+                },
               })}
             >
               GitHub
diff --git a/src/components/Hero/Hero.tsx b/src/components/Hero/Hero.tsx
@@ -4,7 +4,7 @@ import { Box, Button, Chip, Container, Stack, Typography } from '@mui/material';
 import { Link as RouterLink } from 'react-router-dom';
 import { InstallCommand } from '../InstallCommand/InstallCommand';
 import { ProjectBadges } from '../ProjectBadges/ProjectBadges.tsx';
-import { createTrackedLinkHandler } from '../../services/analytics-handlers.ts';
+import { createTrackedLinkHandler } from '../../services/analytics';
 
 export const Hero = () => {
   return (
@@ -75,10 +75,13 @@ export const Hero = () => {
               target="_blank"
               rel="noreferrer"
               endIcon={<OpenInNewIcon />}
-              onClick={createTrackedLinkHandler('npm', {
-                location: 'hero',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'View on npm',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'npm',
+                  location: 'hero',
+                  label: 'View on npm',
+                  link_url: 'https://www.npmjs.com/package/@dfsync/client',
+                },
               })}
             >
               View on npm
@@ -90,10 +93,13 @@ export const Hero = () => {
               size="medium"
               to="/docs"
               startIcon={<ListIcon />}
-              onClick={createTrackedLinkHandler('docs', {
-                location: 'hero',
-                url: 'https://github.com/dfsyncjs/dfsync',
-                label: 'Documentation',
+              onClick={createTrackedLinkHandler({
+                params: {
+                  cta_name: 'docs',
+                  location: 'hero',
+                  label: 'Documentation',
+                  link_url: '/docs',
+                },
               })}
             >
               Documentation
diff --git a/src/components/InstallCommand/InstallCommand.tsx b/src/components/InstallCommand/InstallCommand.tsx
@@ -2,6 +2,7 @@ import { useState } from 'react';
 import ContentCopyIcon from '@mui/icons-material/ContentCopy';
 import CheckIcon from '@mui/icons-material/Check';
 import { IconButton, Stack, Typography } from '@mui/material';
+import { Analytics } from '../../services/analytics';
 
 export const InstallCommand = () => {
   const [copied, setCopied] = useState(false);
@@ -12,6 +13,11 @@ export const InstallCommand = () => {
     await navigator.clipboard.writeText(command);
     setCopied(true);
     setTimeout(() => setCopied(false), 2000);
+
+    Analytics.track('npm_install_copy', {
+      location: 'hero',
+      command: command,
+    });
   };
 
   return (
diff --git a/src/main.tsx b/src/main.tsx
@@ -1,9 +1,12 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
 import { HashRouter } from 'react-router-dom';
+import { Analytics, GA4Provider } from './services/analytics';
 import App from './App';
 import { AppProviders } from './app/AppProviders';
 
+Analytics.init(new GA4Provider());
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <AppProviders>
diff --git a/src/services/analytics-handlers.ts b/src/services/analytics-handlers.ts
diff --git a/src/services/analytics.ts b/src/services/analytics.ts
diff --git a/src/services/analytics/analytics.ts b/src/services/analytics/analytics.ts
@@ -0,0 +1,36 @@
+import type { AnalyticsEvent, AnalyticsEventParams, AnalyticsProvider } from './types';
+
+export class Analytics {
+  private static provider: AnalyticsProvider | null = null;
+
+  static init(provider: AnalyticsProvider): void {
+    this.provider = provider;
+  }
+
+  static track(name: string, params?: AnalyticsEventParams): void {
+    if (!this.provider) {
+      return;
+    }
+
+    const event: AnalyticsEvent = {
+      name,
+      params,
+    };
+
+    this.provider.track(event);
+  }
+
+  static trackCta(params: {
+    ctaName: string;
+    location?: string;
+    linkUrl?: string;
+    label?: string;
+  }): void {
+    this.track('cta_click', {
+      cta_name: params.ctaName,
+      location: params.location,
+      link_url: params.linkUrl,
+      label: params.label,
+    });
+  }
+}
diff --git a/src/services/analytics/create-tracked-link-handler.ts b/src/services/analytics/create-tracked-link-handler.ts
@@ -0,0 +1,15 @@
+import { Analytics } from './analytics';
+import type { AnalyticsEventParams } from './types';
+
+type TrackedLinkHandlerOptions = {
+  eventName?: string;
+  params?: AnalyticsEventParams;
+};
+
+export function createTrackedLinkHandler(options: TrackedLinkHandlerOptions = {}) {
+  const { eventName = 'cta_click', params } = options;
+
+  return () => {
+    Analytics.track(eventName, params);
+  };
+}
diff --git a/src/services/analytics/index.ts b/src/services/analytics/index.ts
@@ -0,0 +1,6 @@
+export * from './analytics';
+export * from './types';
+export * from './create-tracked-link-handler';
+export * from './track-scroll-depth';
+export * from './track-time-on-page';
+export * from './providers/ga4-provider';
diff --git a/src/services/analytics/providers/ga4-provider.ts b/src/services/analytics/providers/ga4-provider.ts
@@ -0,0 +1,14 @@
+import type { AnalyticsEvent, AnalyticsProvider } from '../types';
+
+export class GA4Provider implements AnalyticsProvider {
+  track(event: AnalyticsEvent): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    if (typeof window.gtag !== 'function') {
+      return;
+    }
+
+    window.gtag('event', event.name, event.params);
+  }
+}
diff --git a/src/services/analytics/track-scroll-depth.ts b/src/services/analytics/track-scroll-depth.ts
@@ -0,0 +1,38 @@
+import { Analytics } from './analytics';
+
+const THRESHOLDS = [25, 50, 75, 100] as const;
+
+export function trackScrollDepth(): () => void {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return () => {};
+  }
+
+  const tracked = new Set<number>();
+
+  const onScroll = () => {
+    const documentHeight = document.documentElement.scrollHeight;
+    const windowHeight = window.innerHeight;
+    const scrollTop = window.scrollY;
+
+    const maxScrollable = documentHeight - windowHeight;
+    if (maxScrollable <= 0) return;
+
+    const scrollPercent = Math.round((scrollTop / maxScrollable) * 100);
+
+    for (const threshold of THRESHOLDS) {
+      if (scrollPercent >= threshold && !tracked.has(threshold)) {
+        tracked.add(threshold);
+
+        Analytics.track('scroll_depth', {
+          percent: threshold,
+        });
+      }
+    }
+  };
+
+  window.addEventListener('scroll', onScroll, { passive: true });
+
+  return () => {
+    window.removeEventListener('scroll', onScroll);
+  };
+}
diff --git a/src/services/analytics/track-time-on-page.ts b/src/services/analytics/track-time-on-page.ts
@@ -0,0 +1,17 @@
+import { Analytics } from './analytics';
+
+export function trackTimeOnPage(seconds: number): () => void {
+  if (typeof window === 'undefined') {
+    return () => {};
+  }
+
+  const timeoutId = window.setTimeout(() => {
+    Analytics.track('time_on_page', {
+      seconds,
+    });
+  }, seconds * 1000);
+
+  return () => {
+    window.clearTimeout(timeoutId);
+  };
+}
diff --git a/src/services/analytics/types.ts b/src/services/analytics/types.ts
