feat(analytics): track photo gallery interactions

- Add trackPhotoClick, trackPhotoNavigation, trackLightboxClose helpers
- Instrument PhotoGallery.astro with PhotoSwipe event tracking
- Instrument MediaGallery.astro with PhotoSwipe event tracking
- Track initial photo click, slide navigation, and session completion
- Measure engagement depth via viewed photos count and completion rate
- Enables analysis of photo click rates, navigation patterns, and gallery engagement

Author: saadshahd

src/components/MediaGallery.astro

@@ -197,6 +197,7 @@ try {
   import PhotoSwipeDynamicCaption from "photoswipe-dynamic-caption-plugin";
   import "photoswipe/style.css";
   import "photoswipe-dynamic-caption-plugin/photoswipe-dynamic-caption-plugin.css";
+  import { trackPhotoClick, trackPhotoNavigation, trackLightboxClose } from '@/utils/analytics';
 
   // Check for reduced motion preference
   function prefersReducedMotion(): boolean {
@@ -241,6 +242,36 @@ try {
 
       lightbox.init();
       console.log("[MediaGallery] Lightbox initialized for:", galleryId);
+
+      // Track which photos were viewed during this session
+      const viewedSlides = new Set<number>();
+
+      // Track lightbox open (initial photo click)
+      lightbox.on('firstUpdate', () => {
+        const initialIndex = lightbox.pswp?.currSlide?.index ?? 0;
+        const photoElement = lightbox.pswp?.currSlide?.data?.element;
+        const photoSrc = photoElement?.getAttribute('href') || 'unknown';
+        const page = window.location.pathname.split('/').filter(Boolean).pop() || 'unknown';
+
+        viewedSlides.add(initialIndex);
+        trackPhotoClick(galleryId, photoSrc, initialIndex, page);
+      });
+
+      // Track navigation between slides
+      lightbox.on('change', () => {
+        const currentIndex = lightbox.pswp?.currSlide?.index ?? 0;
+        const totalSlides = lightbox.pswp?.getNumItems() ?? 0;
+
+        viewedSlides.add(currentIndex);
+        trackPhotoNavigation(galleryId, currentIndex, totalSlides);
+      });
+
+      // Track session completion when lightbox closes
+      lightbox.on('close', () => {
+        const totalSlides = lightbox.pswp?.getNumItems() ?? 0;
+        trackLightboxClose(galleryId, viewedSlides.size, totalSlides);
+        viewedSlides.clear(); // Reset for next session
+      });
     });
   }
 

src/components/PhotoGallery.astro

@@ -196,6 +196,7 @@ try {
   import PhotoSwipeDynamicCaption from 'photoswipe-dynamic-caption-plugin';
   import "photoswipe/style.css";
   import 'photoswipe-dynamic-caption-plugin/photoswipe-dynamic-caption-plugin.css';
+  import { trackPhotoClick, trackPhotoNavigation, trackLightboxClose } from '@/utils/analytics';
 
   // Check for reduced motion preference
   function prefersReducedMotion(): boolean {
@@ -240,6 +241,36 @@ try {
 
       lightbox.init();
       console.log("[PhotoGallery] Lightbox initialized for:", galleryId);
+
+      // Track which photos were viewed during this session
+      const viewedSlides = new Set<number>();
+
+      // Track lightbox open (initial photo click)
+      lightbox.on('firstUpdate', () => {
+        const initialIndex = lightbox.pswp?.currSlide?.index ?? 0;
+        const photoElement = lightbox.pswp?.currSlide?.data?.element;
+        const photoSrc = photoElement?.getAttribute('href') || 'unknown';
+        const page = window.location.pathname.split('/').filter(Boolean).pop() || 'unknown';
+
+        viewedSlides.add(initialIndex);
+        trackPhotoClick(galleryId, photoSrc, initialIndex, page);
+      });
+
+      // Track navigation between slides
+      lightbox.on('change', () => {
+        const currentIndex = lightbox.pswp?.currSlide?.index ?? 0;
+        const totalSlides = lightbox.pswp?.getNumItems() ?? 0;
+
+        viewedSlides.add(currentIndex);
+        trackPhotoNavigation(galleryId, currentIndex, totalSlides);
+      });
+
+      // Track session completion when lightbox closes
+      lightbox.on('close', () => {
+        const totalSlides = lightbox.pswp?.getNumItems() ?? 0;
+        trackLightboxClose(galleryId, viewedSlides.size, totalSlides);
+        viewedSlides.clear(); // Reset for next session
+      });
     });
   }
 

src/utils/analytics.ts

@@ -172,3 +172,80 @@ export function trackAccordionToggle(
     ...(section && { section }),
   });
 }
+
+/**
+ * Track photo lightbox open (user clicks thumbnail)
+ *
+ * Useful for understanding which photos attract attention and get opened.
+ *
+ * @param galleryId - Gallery container ID (e.g., 'media-gallery', 'statsbomb-photos')
+ * @param photoSrc - Image path (unique identifier)
+ * @param photoIndex - Position in gallery (0-indexed)
+ * @param page - Page identifier (e.g., 'statsbomb-case-study')
+ *
+ * @example
+ * trackPhotoClick('media-gallery', '/images/team-photo.jpg', 0, 'statsbomb-case-study');
+ */
+export function trackPhotoClick(
+  galleryId: string,
+  photoSrc: string,
+  photoIndex: number,
+  page: string,
+): void {
+  trackEvent("photo-click", {
+    gallery: galleryId,
+    photo: photoSrc,
+    position: photoIndex + 1, // Human-readable (1-indexed)
+    page,
+  });
+}
+
+/**
+ * Track gallery navigation (prev/next slide in lightbox)
+ *
+ * Useful for understanding how deeply users explore galleries.
+ *
+ * @param galleryId - Gallery container ID
+ * @param photoIndex - New slide index (0-indexed)
+ * @param totalPhotos - Total slides in gallery
+ *
+ * @example
+ * trackPhotoNavigation('media-gallery', 3, 16);
+ */
+export function trackPhotoNavigation(
+  galleryId: string,
+  photoIndex: number,
+  totalPhotos: number,
+): void {
+  trackEvent("photo-navigation", {
+    gallery: galleryId,
+    position: photoIndex + 1,
+    total: totalPhotos,
+    depth: `${Math.round(((photoIndex + 1) / totalPhotos) * 100)}%`,
+  });
+}
+
+/**
+ * Track lightbox close (engagement session end)
+ *
+ * Useful for understanding gallery completion rates and engagement depth.
+ *
+ * @param galleryId - Gallery container ID
+ * @param viewedCount - Number of unique photos viewed in this session
+ * @param totalPhotos - Total slides in gallery
+ *
+ * @example
+ * trackLightboxClose('media-gallery', 5, 16); // Viewed 5 out of 16 photos (31% completion)
+ */
+export function trackLightboxClose(
+  galleryId: string,
+  viewedCount: number,
+  totalPhotos: number,
+): void {
+  trackEvent("lightbox-close", {
+    gallery: galleryId,
+    viewed: viewedCount,
+    total: totalPhotos,
+    completion: `${Math.round((viewedCount / totalPhotos) * 100)}%`,
+  });
+}