From c0f57996670fd127a51fba805edf9cdfc247063c Mon Sep 17 00:00:00 2001
From: Marc Mintel <marc@mintel.me>
Date: Mon, 16 Feb 2026 18:31:28 +0100
Subject: [PATCH] feat(analytics): add blog engagement, ToC tracking, and 404
 monitoring

- Added BlogEngagementTracker for reading time and completion tracking
- Added ToC click tracking in blog posts
- Added global 404 error monitoring in not-found.tsx
- Completed 'Total Transparency' suite
---
 app/[locale]/blog/[slug]/page.tsx             |  7 +++
 app/[locale]/not-found.tsx                    | 23 +++++---
 .../analytics/BlogEngagementTracker.tsx       | 53 +++++++++++++++++++
 components/blog/TableOfContents.tsx           | 16 ++++--
 4 files changed, 88 insertions(+), 11 deletions(-)
 create mode 100644 components/analytics/BlogEngagementTracker.tsx

diff --git a/app/[locale]/blog/[slug]/page.tsx b/app/[locale]/blog/[slug]/page.tsx
index 7c4e6eca..5cc8739f 100644
--- a/app/[locale]/blog/[slug]/page.tsx
+++ b/app/[locale]/blog/[slug]/page.tsx
@@ -11,6 +11,7 @@ import TableOfContents from '@/components/blog/TableOfContents';
 import { mdxComponents } from '@/components/blog/MDXComponents';
 import { Heading } from '@/components/ui';
 import { setRequestLocale } from 'next-intl/server';
+import BlogEngagementTracker from '@/components/analytics/BlogEngagementTracker';
 
 interface BlogPostProps {
   params: Promise<{
@@ -67,6 +68,12 @@ export default async function BlogPost({ params }: BlogPostProps) {
 
   return (
     <article className="bg-white min-h-screen font-sans selection:bg-primary/10 selection:text-primary">
+      <BlogEngagementTracker
+        title={post.frontmatter.title}
+        slug={slug}
+        category={post.frontmatter.category}
+        readingTime={getReadingTime(post.content)}
+      />
       {/* Featured Image Header */}
       {post.frontmatter.featuredImage ? (
         <div className="relative w-full h-[70vh] min-h-[500px] overflow-hidden group">
diff --git a/app/[locale]/not-found.tsx b/app/[locale]/not-found.tsx
index ed0d56c9..f2bb9a93 100644
--- a/app/[locale]/not-found.tsx
+++ b/app/[locale]/not-found.tsx
@@ -1,9 +1,20 @@
 import { useTranslations } from 'next-intl';
 import { Container, Button, Heading } from '@/components/ui';
 import Scribble from '@/components/Scribble';
+import { useEffect } from 'react';
+import { useAnalytics } from '@/components/analytics/useAnalytics';
+import { AnalyticsEvents } from '@/components/analytics/analytics-events';
 
 export default function NotFound() {
   const t = useTranslations('Error.notFound');
+  const { trackEvent } = useAnalytics();
+
+  useEffect(() => {
+    trackEvent(AnalyticsEvents.ERROR, {
+      type: '404_not_found',
+      path: typeof window !== 'undefined' ? window.location.pathname : 'unknown',
+    });
+  }, [trackEvent]);
 
   return (
     <Container className="relative py-24 flex flex-col items-center justify-center text-center min-h-[70vh] overflow-hidden">
@@ -16,19 +27,17 @@ export default function NotFound() {
         <Heading level={1} className="text-6xl md:text-8xl font-bold mb-2">
           404
         </Heading>
-        <Scribble 
-          variant="circle" 
-          className="w-[150%] h-[150%] -top-[25%] -left-[25%] text-accent/40" 
+        <Scribble
+          variant="circle"
+          className="w-[150%] h-[150%] -top-[25%] -left-[25%] text-accent/40"
         />
       </div>
 
       <Heading level={2} className="text-2xl md:text-3xl font-bold mb-4 text-primary">
         {t('title')}
       </Heading>
-      
-      <p className="text-white/60 mb-10 max-w-md text-lg">
-        {t('description')}
-      </p>
+
+      <p className="text-white/60 mb-10 max-w-md text-lg">{t('description')}</p>
 
       <div className="flex flex-col sm:flex-row gap-4">
         <Button href="/" variant="accent" size="lg">
diff --git a/components/analytics/BlogEngagementTracker.tsx b/components/analytics/BlogEngagementTracker.tsx
new file mode 100644
index 00000000..e0216f78
--- /dev/null
+++ b/components/analytics/BlogEngagementTracker.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import { useEffect } from 'react';
+import { useAnalytics } from './useAnalytics';
+import { AnalyticsEvents } from './analytics-events';
+
+interface BlogEngagementTrackerProps {
+  title: string;
+  slug: string;
+  category?: string;
+  readingTime: number;
+}
+
+/**
+ * BlogEngagementTracker
+ * Tracks reading time and article completion.
+ */
+export default function BlogEngagementTracker({
+  title,
+  slug,
+  category,
+  readingTime,
+}: BlogEngagementTrackerProps) {
+  const { trackEvent } = useAnalytics();
+
+  useEffect(() => {
+    // Article start
+    trackEvent(AnalyticsEvents.BLOG_POST_VIEW, {
+      title,
+      slug,
+      category,
+      estimated_reading_time: readingTime,
+      location: 'blog_post_pdp',
+    });
+
+    const startTime = Date.now();
+
+    return () => {
+      const dwellTime = Math.round((Date.now() - startTime) / 1000);
+
+      // We only consider it a "read" if they stay a reasonable amount of time
+      // or if they scroll (covered by ScrollDepthTracker)
+      trackEvent('blog_dwell_time', {
+        title,
+        slug,
+        seconds: dwellTime,
+        reading_time_completion: Math.min(100, Math.round((dwellTime / (readingTime * 60)) * 100)),
+      });
+    };
+  }, [title, slug, category, readingTime, trackEvent]);
+
+  return null;
+}
diff --git a/components/blog/TableOfContents.tsx b/components/blog/TableOfContents.tsx
index cab12ef7..e7e1c406 100644
--- a/components/blog/TableOfContents.tsx
+++ b/components/blog/TableOfContents.tsx
@@ -2,6 +2,8 @@
 
 import React, { useEffect, useState } from 'react';
 import { cn } from '@/components/ui/utils';
+import { useAnalytics } from '../analytics/useAnalytics';
+import { AnalyticsEvents } from '../analytics/analytics-events';
 
 interface TocItem {
   id: string;
@@ -16,11 +18,12 @@ interface TableOfContentsProps {
 
 export default function TableOfContents({ headings, locale }: TableOfContentsProps) {
   const [activeId, setActiveId] = useState<string>('');
+  const { trackEvent } = useAnalytics();
 
   useEffect(() => {
     const observerOptions = {
       rootMargin: '-10% 0% -70% 0%',
-      threshold: 0
+      threshold: 0,
     };
 
     const observer = new IntersectionObserver((entries) => {
@@ -66,15 +69,20 @@ export default function TableOfContents({ headings, locale }: TableOfContentsPro
               <a
                 href={`#${heading.id}`}
                 className={cn(
-                  "text-sm md:text-base transition-all duration-300 hover:text-primary block leading-snug",
+                  'text-sm md:text-base transition-all duration-300 hover:text-primary block leading-snug',
                   activeId === heading.id
-                    ? "text-primary font-bold translate-x-1"
-                    : "text-text-secondary font-medium hover:translate-x-1"
+                    ? 'text-primary font-bold translate-x-1'
+                    : 'text-text-secondary font-medium hover:translate-x-1',
                 )}
                 onClick={(e) => {
                   e.preventDefault();
                   const element = document.getElementById(heading.id);
                   if (element) {
+                    trackEvent(AnalyticsEvents.TOC_CLICK, {
+                      heading_id: heading.id,
+                      heading_text: heading.text,
+                      location: 'blog_sidebar',
+                    });
                     const yOffset = -100;
                     const y = element.getBoundingClientRect().top + window.pageYOffset + yOffset;
                     window.scrollTo({ top: y, behavior: 'smooth' });