# Ad Impression Tracking - Testing Guide

## Implementation Complete ✅

Professional ad impression tracking has been implemented following IAB/MRC industry standards.

## What Was Implemented

### 1. Session Management (`lib/ad-session.ts`)
- ✅ Unique session ID generation (UUID v4)
- ✅ Session-based impression tracking using sessionStorage
- ✅ Automatic cleanup when browser closes
- ✅ Prevents duplicate tracking within same session

### 2. Ad Carousel Updates (`components/ui/ad-carousel.tsx`)
- ✅ 50% viewability requirement (using `useInView` with `amount: 0.5`)
- ✅ 1-second minimum view time (IAB/MRC standard)
- ✅ Session-based tracking (no duplicates in same session)
- ✅ Detailed console logging for debugging
- ✅ Proper cleanup of timers

### 3. Admin Dashboard (`app/admin/ads/page.tsx`)
- ✅ "Unique Impressions" label with info tooltip
- ✅ CTR tooltip explaining calculation
- ✅ Industry standard explanations

## Testing Scenarios

### Test 1: First Visit - Track Impression ✓
**Steps:**
1. Open browser in incognito/private mode
2. Navigate to homepage: `https://thegeezerguide.com`
3. Wait for ad carousel to load
4. Keep ad visible for 1+ second
5. Check browser console

**Expected Console Logs:**
```
[Ad Session] New session created: <uuid>
[Ad Carousel] Session initialized: { sessionId: '<uuid>', trackedCount: 0, trackedAds: [] }
[Ad Carousel] Impression check: { adId: '...', facilityName: '...', isInView: true, alreadyTracked: false }
[Ad Carousel] Tracking unique impression: { adId: '...', facilityName: '...', sessionId: '<uuid>' }
[Analytics] Impression tracked for ad <id>: { impressions: 1, clicks: 0, ctr: '0.00%' }
[Ad Carousel] Impression tracked successfully: { success: true, impressions: 1, ... }
[Ad Session] Marked impression tracked: { adId: '...', totalTracked: 1, sessionId: '<uuid>' }
```

**Expected Result:** ✅ 1 impression tracked

---

### Test 2: Carousel Auto-Rotation - Track Each Unique Ad Once ✓
**Steps:**
1. Continue from Test 1 (same session)
2. Wait for carousel to auto-rotate (5 seconds)
3. Ad B appears, wait 1+ second
4. Carousel rotates to Ad C, wait 1+ second
5. Check console logs

**Expected Console Logs:**
```
[Ad Carousel] Tracking unique impression: { adId: '<ad-b-id>', ... }
[Ad Session] Marked impression tracked: { adId: '<ad-b-id>', totalTracked: 2 }
[Ad Carousel] Tracking unique impression: { adId: '<ad-c-id>', ... }
[Ad Session] Marked impression tracked: { adId: '<ad-c-id>', totalTracked: 3 }
```

**Expected Result:** ✅ 3 unique impressions (Ad A, Ad B, Ad C)

---

### Test 3: Carousel Returns to Ad A - Skip Duplicate ✓
**Steps:**
1. Continue from Test 2 (same session)
2. Wait for carousel to rotate back to Ad A
3. Check console logs

**Expected Console Logs:**
```
[Ad Carousel] Impression check: { adId: '<ad-a-id>', alreadyTracked: true }
[Ad Carousel] Already tracked impression in this session: <ad-a-id>
```

**Expected Result:** ✅ No new impression tracked (still 3 total)

---

### Test 4: Page Refresh - Session Persists ✓
**Steps:**
1. Continue from Test 3 (same session)
2. Refresh the page (F5 or Cmd+R)
3. Wait for carousel to load
4. Check console logs

**Expected Console Logs:**
```
[Ad Session] Existing session loaded: <same-uuid-as-before>
[Ad Carousel] Session initialized: { sessionId: '<same-uuid>', trackedCount: 3, trackedAds: ['<ad-a>', '<ad-b>', '<ad-c>'] }
[Ad Carousel] Already tracked impression in this session: <ad-a-id>
```

**Expected Result:** ✅ No new impressions (session persists, already tracked)

---

### Test 5: Scroll Out of View - No Tracking ✓
**Steps:**
1. Open new incognito window
2. Navigate to homepage
3. Immediately scroll down so carousel is not visible
4. Wait 5 seconds
5. Check console logs

**Expected Console Logs:**
```
[Ad Carousel] Ad not in view, skipping impression tracking
```

**Expected Result:** ✅ No impression tracked (not 50% visible)

---

### Test 6: Quick Scroll Away - No Tracking ✓
**Steps:**
1. Open new incognito window
2. Navigate to homepage
3. Wait 0.5 seconds (less than 1 second)
4. Scroll down quickly
5. Check console logs

**Expected Console Logs:**
```
[Ad Carousel] Impression check: { isInView: true, ... }
[Ad Carousel] Ad no longer visible after 1s, skipping impression
```

**Expected Result:** ✅ No impression tracked (not visible for full 1 second)

---

### Test 7: New Browser Session - Track Again ✓
**Steps:**
1. Close all browser windows
2. Open new browser (not incognito)
3. Navigate to homepage
4. Wait 1+ second
5. Check console logs

**Expected Console Logs:**
```
[Ad Session] New session created: <new-uuid-different-from-before>
[Ad Carousel] Tracking unique impression: { adId: '...', sessionId: '<new-uuid>' }
```

**Expected Result:** ✅ New impression tracked (new session)

---

### Test 8: Background Tab - No Tracking ✓
**Steps:**
1. Open homepage in new tab
2. Immediately switch to another tab (don't let ad be visible for 1s)
3. Wait 5 seconds
4. Switch back and check console

**Expected Result:** ✅ No impression tracked (tab was in background)

---

### Test 9: Admin Dashboard - Verify Metrics ✓
**Steps:**
1. Complete Tests 1-3 (3 unique impressions)
2. Click on one ad (1 click)
3. Navigate to admin dashboard: `https://thegeezerguide.com/admin/ads`
4. Click "Refresh" button
5. Check the analytics boxes

**Expected Display:**
- **Unique Impressions**: 3 (with info tooltip)
- **Clicks**: 1
- **CTR**: 33.33% (1 click / 3 impressions)

**Tooltip Text:**
- Impressions: "Unique impressions per user session. Ad must be 50% visible for 1+ second. Follows IAB/MRC industry standards."
- CTR: "Click-Through Rate = (Clicks / Unique Impressions) × 100. Industry average: 0.05-0.1% for display ads."

---

### Test 10: Multiple Users - Independent Sessions ✓
**Steps:**
1. User A: Open homepage in Chrome incognito
2. User B: Open homepage in Firefox private
3. Both wait 1+ second on same ad
4. Check admin dashboard

**Expected Result:** ✅ 2 impressions (one per user session)

---

## Quick Test Checklist

Run through this checklist to verify everything works:

- [ ] New session creates unique ID
- [ ] First ad view tracks impression after 1 second
- [ ] Each unique ad in carousel tracked once
- [ ] Duplicate ad views in same session skipped
- [ ] Page refresh preserves session (no duplicate tracking)
- [ ] Scrolling out of view prevents tracking
- [ ] Quick scroll away (< 1s) prevents tracking
- [ ] Browser close/reopen creates new session
- [ ] Background tabs don't track impressions
- [ ] Admin dashboard shows "Unique Impressions" label
- [ ] Tooltips explain tracking methodology
- [ ] CTR calculates correctly

## Browser Console Commands

Use these commands in the browser console for debugging:

```javascript
// Check current session stats
sessionStorage.getItem('geezer_guide_ad_session_id')
sessionStorage.getItem('geezer_guide_tracked_impressions')

// Clear session (for testing)
sessionStorage.clear()

// Check if specific ad was tracked
JSON.parse(sessionStorage.getItem('geezer_guide_tracked_impressions') || '[]')
```

## Expected Behavior Summary

### ✅ SHOULD Track Impression:
- Ad is 50%+ visible in viewport
- User views ad for 1+ continuous second
- Ad has valid MongoDB ObjectId
- Ad not already tracked in this session

### ❌ SHOULD NOT Track Impression:
- Ad below fold (not visible)
- User scrolls away before 1 second
- Ad already tracked in current session
- Browser tab in background
- Invalid ad ID

## Industry Compliance

This implementation follows:
- **IAB (Interactive Advertising Bureau)** standards
- **MRC (Media Rating Council)** viewability guidelines
- 50% viewability threshold
- 1-second minimum view time
- Unique impressions per session

## Success Criteria

✅ All tests pass
✅ Console logs show proper tracking logic
✅ No duplicate impressions in same session
✅ Session persists across page reloads
✅ New sessions track independently
✅ Admin dashboard displays accurate metrics
✅ Tooltips explain methodology clearly

## Notes

- sessionStorage automatically clears when browser closes (not just tab)
- Each browser/device gets independent session
- Carousel auto-rotation does NOT inflate impression counts
- Fair and accurate metrics for advertisers