Improve automation, relinted webapp to tab alignment

and introduced basic EDA in a jupyter notebook of kafka export (nonmodular yet)

Makefile

@@ -5,8 +5,13 @@ TEX       := main.tex
 JOBNAME   := main
 PDF       := paper/$(BUILDDIR)/$(JOBNAME).pdf
 
+.DEFAULT_GOAL := help
+
 all: pdf
 
+run.webapp:
+	@cd web && npm install && npm run dev
+
 $(BUILDDIR):
 	mkdir -p paper/$(BUILDDIR)
 
@@ -31,4 +36,4 @@ clean:
 	rm -rf paper/$(BUILDDIR)/*
 
 
-.PHONY: all pdf clean watch
+.PHONY: all pdf clean watch run.webapp

requirements.txt

@@ -1,2 +1,6 @@
 kafka-python
 dotenv
+pandas
+jupyter
+ipykernel
+matplotlib

web/src/app/api/track/route.ts

@@ -2,32 +2,32 @@ import { NextRequest, NextResponse } from 'next/server';
 import { sendInteractionEvent } from '@/lib/kafka';
 
 export async function POST(req: NextRequest) {
-  try {
-    const body = await req.json();
-    const { sessionId, eventType, targetEl, targetUrl, metadata } = body;
+    try {
+        const body = await req.json();
+        const { sessionId, eventType, targetEl, targetUrl, metadata } = body;
 
-    if (!sessionId || !eventType) {
-      return NextResponse.json(
-        { error: 'sessionId and eventType required' },
-        { status: 400 }
-      );
+        if (!sessionId || !eventType) {
+            return NextResponse.json(
+                { error: 'sessionId and eventType required' },
+                { status: 400 }
+            );
+        }
+
+        await sendInteractionEvent({
+            sessionId,
+            eventType,
+            targetEl,
+            targetUrl,
+            metadata,
+            ts: Date.now(),
+        });
+
+        return NextResponse.json({ success: true });
+    } catch (err: any) {
+        console.error('track error:', err);
+        return NextResponse.json(
+            { error: err.message || 'unknown error' },
+            { status: 500 }
+        );
     }
-
-    await sendInteractionEvent({
-      sessionId,
-      eventType,
-      targetEl,
-      targetUrl,
-      metadata,
-      ts: Date.now(),
-    });
-
-    return NextResponse.json({ success: true });
-  } catch (err: any) {
-    console.error('track error:', err);
-    return NextResponse.json(
-      { error: err.message || 'unknown error' },
-      { status: 500 }
-    );
-  }
 }

web/src/hooks/useInteractionTracking.ts

@@ -1,83 +1,117 @@
 import { useEffect, useRef } from 'react';
+import '@/lib/experiments' // ensure experiments lib is loaded
 
 const genSessionId = () => {
-  if (typeof window === 'undefined') return '';
-  let sid = sessionStorage.getItem('phantom_session_id');
-  if (!sid) {
-    sid = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
-    sessionStorage.setItem('phantom_session_id', sid);
-  }
-  return sid;
+    if (typeof window === 'undefined') return '';
+    let sid = sessionStorage.getItem('phantom_session_id');
+    if (!sid) {
+        sid = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        sessionStorage.setItem('phantom_session_id', sid);
+        // TODO: when creating new id send to exepriemtn tracking db
+        // match between sesion-id and experiment-id for this session
+        // so that we can identify all interactions aligning with a specific experiment goal.
+    }
+    return sid;
 };
 
 const track = async (ev: {
-  sessionId: string;
-  eventType: string;
-  targetEl?: string;
-  targetUrl?: string;
-  metadata?: Record<string, any>;
+    sessionId: string;
+    eventType: string;
+    targetEl?: string;
+    targetUrl?: string;
+    metadata?: Record<string, any>;
 }) => {
-  try {
-    await fetch('/api/track', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify(ev),
-    });
-  } catch (err) {
-    console.error('track failed:', err);
-  }
+    try {
+        await fetch('/api/track', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(ev),
+        });
+    } catch (err) {
+        console.error('track failed:', err);
+    }
 };
 
 export const useInteractionTracking = () => {
-  const sidRef = useRef<string>('');
+    const sidRef = useRef<string>('');
 
-  useEffect(() => {
-    sidRef.current = genSessionId();
+    useEffect(() => {
+        sidRef.current = genSessionId();
 
-    const handleClick = (e: MouseEvent) => {
-      const tgt = e.target as HTMLElement;
-      track({
-        sessionId: sidRef.current,
-        eventType: 'click',
-        targetEl: tgt.tagName,
-        targetUrl: tgt instanceof HTMLAnchorElement ? tgt.href : undefined,
-        metadata: {
-          x: e.clientX,
-          y: e.clientY,
-          path: window.location.pathname,
-        },
-      });
-    };
+        const handleClick = (e: MouseEvent) => {
+            const tgt = e.target as HTMLElement;
+            track({
+                sessionId: sidRef.current,
+                eventType: 'click',
+                targetEl: tgt.tagName,
+                targetUrl: tgt instanceof HTMLAnchorElement ? tgt.href : undefined,
+                metadata: {
+                    x: e.clientX,
+                    y: e.clientY,
+                    path: window.location.pathname,
+                },
+            });
+        };
 
-    const handleScroll = () => {
-      track({
-        sessionId: sidRef.current,
-        eventType: 'scroll',
-        metadata: {
-          scrollY: window.scrollY,
-          path: window.location.pathname,
-        },
-      });
-    };
+        const handleScroll = () => {
+            track({
+                sessionId: sidRef.current,
+                eventType: 'scroll',
+                metadata: {
+                    scrollY: window.scrollY,
+                    path: window.location.pathname,
+                },
+            });
+        };
 
-    const handlePageView = () => {
-      track({
-        sessionId: sidRef.current,
-        eventType: 'pageview',
-        metadata: {
-          path: window.location.pathname,
-          referrer: document.referrer,
-        },
-      });
-    };
+        const handlePageView = () => {
+            track({
+                sessionId: sidRef.current,
+                eventType: 'pageview',
+                metadata: {
+                    path: window.location.pathname,
+                    referrer: document.referrer,
+                },
+            });
+        };
 
-    handlePageView();
-    document.addEventListener('click', handleClick);
-    window.addEventListener('scroll', handleScroll, { passive: true });
+        enum DefinedInteractions {
+            ADD_TO_CART = 'add_to_cart',
+            PURCHASE = 'purchase',
+        }
 
-    return () => {
-      document.removeEventListener('click', handleClick);
-      window.removeEventListener('scroll', handleScroll);
-    };
-  }, []);
+        // called when clicking on "Add to Cart" button or "Purchase" button
+        const handleDefinedInteraction = (
+            interactionType: DefinedInteractions,
+            metadata?: Record<string, any>
+        ) => {
+            track({
+                sessionId: sidRef.current,
+                eventType: interactionType,
+                metadata: {
+                    path: window.location.pathname,
+                    ...metadata,
+                },
+            });
+        };
+
+
+        handlePageView();
+        document.addEventListener('click', handleClick);
+        document.addEventListener('definedInteraction', (e: Event) => {
+            const customEvent = e as CustomEvent;
+            handleDefinedInteraction(customEvent.detail.interactionType, customEvent.detail.metadata);
+        });
+        // TOO NOISY: enable if needed but tbh not worth it
+        //window.addEventListener('scroll', handleScroll, { passive: true });
+
+        return () => {
+            document.removeEventListener('click', handleClick);
+            document.removeEventListener('definedInteraction', (e: Event) => {
+                const customEvent = e as CustomEvent;
+                handleDefinedInteraction(customEvent.detail.interactionType, customEvent.detail.metadata);
+            });
+            //window.removeEventListener('scroll', handleScroll);
+        };
+    }, []);
 };

web/src/lib/experiments.ts

@@ -0,0 +1 @@
+//

web/src/lib/kafka.ts

@@ -3,39 +3,40 @@ import { Kafka, Producer } from 'kafkajs';
 let producer: Producer | null = null;
 
 const kafka = new Kafka({
-  clientId: 'phantom-web',
-  brokers: [`${process.env.KAFKA_HOST || 'localhost'}:${process.env.KAFKA_PORT || '9092'}`],
+    clientId: 'phantom-web',
+    brokers: [`${process.env.KAFKA_HOST || 'localhost'}:${process.env.KAFKA_PORT || '9092'}`],
 });
 
 export const getProducer = async (): Promise<Producer> => {
-  if (!producer) {
-    producer = kafka.producer();
-    await producer.connect();
-  }
-  return producer;
+    if (!producer) {
+        producer = kafka.producer();
+        await producer.connect();
+    }
+    return producer;
 };
 
 export const sendInteractionEvent = async (ev: {
-  sessionId: string;
-  eventType: string;
-  targetEl?: string;
-  targetUrl?: string;
-  metadata?: Record<string, any>;
-  ts: number;
+    sessionId: string;
+    eventType: string;
+    targetEl?: string;
+    targetUrl?: string;
+    metadata?: Record<string, any>;
+    ts: number;
 }) => {
-  const p = await getProducer();
-  await p.send({
-    topic: 'user-interactions',
-    messages: [{
-      key: ev.sessionId,
-      value: JSON.stringify(ev),
-    }],
-  });
+    const p = await getProducer();
+    // add to the metadata
+    await p.send({
+        topic: 'user-interactions',
+        messages: [{
+            key: ev.sessionId,
+            value: JSON.stringify(ev),
+        }],
+    });
 };
 
 export const disconnect = async () => {
-  if (producer) {
-    await producer.disconnect();
-    producer = null;
-  }
+    if (producer) {
+        await producer.disconnect();
+        producer = null;
+    }
 };