@thead-vantage/react 2.17.0 → 2.19.0

package/README.md

@@ -151,12 +151,24 @@ The main component for displaying ads from TheAd Vantage.
 | `userId` | `string \| null` | No | `null` | User ID for ad targeting |
 | `userSegment` | `string \| null` | No | `null` | User segment for ad targeting |
 | `className` | `string` | No | `''` | Additional CSS classes |
+| `clickMetadata` | `Record<string, unknown>` | No | - | Optional metadata to send with click tracking events |
+| `impressionMetadata` | `Record<string, unknown>` | No | - | Optional metadata to send with impression tracking events |
+| `showImpressionFinished` | `boolean` | No | `false` | Show spinning checkmark during impression timer (2s), then green checkmark when complete |
 
 **Example**:
 ```tsx
 import { AdBanner } from '@/components/AdBanner';
 
 export default function ArticlePage() {
+  const userData = {
+    id: 'user-123',
+    email: 'user@example.com',
+    school: 'University of Example',
+    grade: 'Senior',
+    major: 'Computer Science',
+    role: 'student',
+  };
+
   return (
     <div>
       <article>
@@ -169,9 +181,26 @@ export default function ArticlePage() {
           platformId="10"
           apiKey="abc123xyz"
           size="medium-rectangle"
-          userId="user-123"
+          userId={userData.id}
           userSegment="premium"
           className="my-4"
+          clickMetadata={{
+            userId: userData.id,
+            email: userData.email,
+            school: userData.school,
+            grade: userData.grade,
+            major: userData.major,
+            role: userData.role,
+          }}
+          impressionMetadata={{
+            userId: userData.id,
+            email: userData.email,
+            school: userData.school,
+            grade: userData.grade,
+            major: userData.major,
+            role: userData.role,
+          }}
+          showImpressionFinished={true}
         />
       </aside>
     </div>
@@ -179,6 +208,60 @@ export default function ArticlePage() {
 }
 ```
 
+### Metadata Tracking
+
+The `AdBanner` component supports optional metadata that is sent with click and impression tracking events. This allows you to pass additional context about the user or session to TheAd Vantage for analytics purposes.
+
+**Metadata Props**:
+- `clickMetadata`: Optional object with key-value pairs sent with click events
+- `impressionMetadata`: Optional object with key-value pairs sent with impression events
+
+**Example with Metadata**:
+```tsx
+<AdBanner
+  platformId="10"
+  apiKey="abc123xyz"
+  size="medium-rectangle"
+  clickMetadata={{
+    userId: userData?.id,
+    email: userData?.email,
+    school: userData?.school,
+    grade: userData?.grade,
+    major: userData?.major,
+    role: userData?.role,
+  }}
+  impressionMetadata={{
+    userId: userData?.id,
+    email: userData?.email,
+    school: userData?.school,
+    grade: userData?.grade,
+    major: userData?.major,
+    role: userData?.role,
+  }}
+/>
+```
+
+**Note**: The metadata is sent to the `/api/ads/track` endpoint on thead-vantage.com. Ensure the API has been updated to support receiving metadata (see `other/thead-vantage-api-metadata-prompt.md` for implementation details).
+
+### Impression Finished Indicator
+
+The `showImpressionFinished` prop enables a visual indicator that shows when an impression has been recorded:
+
+- **Spinning Checkmark**: A gray spinning checkmark appears in the top-right corner of the ad during the 2-second impression timer
+- **Green Checkmark**: After 2 seconds, the checkmark turns green to indicate the impression has been recorded
+
+**Example**:
+```tsx
+<AdBanner
+  platformId="10"
+  apiKey="abc123xyz"
+  size="banner"
+  showImpressionFinished={true}
+/>
+```
+
+This feature is useful for debugging and providing visual feedback that impressions are being tracked correctly.
+
 ### Utility Functions
 
 You can also use the utility functions directly:
@@ -198,8 +281,16 @@ const response = await fetchAdBanner({
 // Track events (automatically skipped in TheAd Vantage dev mode)
 // Note: trackImpression and trackClick now require apiKey parameter
 // They automatically include client fingerprinting data for fraud detection
-trackImpression(adId, apiKey);
-trackClick(adId, apiKey);
+// Optional metadata can be passed as the last parameter
+trackImpression(adId, apiKey, apiUrl, {
+  userId: 'user-123',
+  email: 'user@example.com',
+  school: 'University of Example',
+});
+trackClick(adId, apiKey, apiUrl, {
+  userId: 'user-123',
+  email: 'user@example.com',
+});
 
 // You can also collect fingerprint data manually if needed
 const fingerprint = collectFingerprint();
@@ -335,14 +426,16 @@ The TheAd Vantage integration uses a smart mode detection system to support diff
 
 ### Components
 - **`src/components/AdBanner.tsx`**: Main React component for displaying ads
-  - Props: `platformId`, `apiKey`, `size`, `apiUrl?`, `userId?`, `userSegment?`, `className?`
+  - Props: `platformId`, `apiKey`, `size`, `apiUrl?`, `userId?`, `userSegment?`, `className?`, `clickMetadata?`, `impressionMetadata?`, `showImpressionFinished?`
   - Automatically handles loading, error states, and dev mode indicators
+  - Supports optional metadata for click and impression tracking
+  - Optional impression finished indicator (spinning checkmark → green checkmark)
 
 ### Utilities
 - **`src/lib/ads.ts`**: Utility functions for fetching and tracking ads
   - `fetchAdBanner(params)`: Fetches ads with full parameter support
-  - `trackImpression(adId, apiKey, apiUrl?)`: Tracks ad impressions with fingerprinting (skipped in dev mode)
-  - `trackClick(adId, apiKey, apiUrl?)`: Tracks ad clicks with fingerprinting (skipped in dev mode)
+  - `trackImpression(adId, apiKey, apiUrl?, metadata?)`: Tracks ad impressions with fingerprinting and optional metadata (skipped in dev mode)
+  - `trackClick(adId, apiKey, apiUrl?, metadata?)`: Tracks ad clicks with fingerprinting and optional metadata (skipped in dev mode)
   - `collectFingerprint()`: Collects client fingerprinting data for fraud detection
 
 ## Implementation Instructions for AI Agents
@@ -415,7 +508,38 @@ The system uses this priority order to determine which API URL to use:
 />
 ```
 
-**Pattern 3: Custom API URL Override**
+**Pattern 3: Ad with Metadata Tracking**
+```tsx
+<AdBanner 
+  platformId="10" 
+  apiKey="key" 
+  size="medium-rectangle"
+  clickMetadata={{
+    userId: userData?.id,
+    email: userData?.email,
+    school: userData?.school,
+    grade: userData?.grade,
+  }}
+  impressionMetadata={{
+    userId: userData?.id,
+    email: userData?.email,
+    school: userData?.school,
+    grade: userData?.grade,
+  }}
+/>
+```
+
+**Pattern 4: Ad with Impression Finished Indicator**
+```tsx
+<AdBanner 
+  platformId="10" 
+  apiKey="key" 
+  size="banner"
+  showImpressionFinished={true}
+/>
+```
+
+**Pattern 5: Custom API URL Override**
 ```tsx
 <AdBanner 
   platformId="10" 
@@ -425,7 +549,7 @@ The system uses this priority order to determine which API URL to use:
 />
 ```
 
-**Pattern 4: Programmatic Ad Fetching**
+**Pattern 6: Programmatic Ad Fetching**
 ```tsx
 const response = await fetchAdBanner({
   platformId: '10',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thead-vantage/react",
-  "version": "2.17.0",
+  "version": "2.19.0",
   "description": "React components and utilities for TheAd Vantage ad platform integration",
   "main": "./src/index.ts",
   "module": "./src/index.ts",

package/src/components/AdBanner.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useState } from 'react';
+import { useEffect, useState, useRef } from 'react';
 import Image from 'next/image';
 import { fetchAdBanner, trackImpression, trackClick, type Ad } from '../lib/ads';
 
@@ -12,6 +12,9 @@ export interface AdBannerProps {
   userId?: string | null;
   userSegment?: string | null;
   className?: string;
+  clickMetadata?: Record<string, unknown>; // Optional metadata to send with click events
+  impressionMetadata?: Record<string, unknown>; // Optional metadata to send with impression events
+  showImpressionFinished?: boolean; // Show spinning checkmark during impression timer, then green check when complete
 }
 
 export function AdBanner({
@@ -22,11 +25,16 @@ export function AdBanner({
   userId = null,
   userSegment = null,
   className = '',
+  clickMetadata,
+  impressionMetadata,
+  showImpressionFinished = false,
 }: AdBannerProps) {
   const [ad, setAd] = useState<Ad | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   const [devMode, setDevMode] = useState(false);
+  const [impressionStatus, setImpressionStatus] = useState<'pending' | 'counting' | 'completed'>('pending');
+  const impressionTimerRef = useRef<NodeJS.Timeout | null>(null);
 
   useEffect(() => {
     const loadAd = async () => {
@@ -62,8 +70,24 @@ export function AdBanner({
           setAd(response.ad);
           setDevMode(response.dev_mode || false);
 
-          // Track impression (will be skipped in dev mode)
-          trackImpression(response.ad.id, apiKey, apiUrl);
+          // Start impression timer if showImpressionFinished is enabled
+          if (showImpressionFinished) {
+            setImpressionStatus('counting');
+            // Standard impression timer: 2 seconds of view time
+            impressionTimerRef.current = setTimeout(() => {
+              setImpressionStatus('completed');
+              impressionTimerRef.current = null;
+            }, 2000);
+
+            // Track impression (will be skipped in dev mode)
+            // Note: We don't wait for the API call to complete - the timer determines when to show green check
+            trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata).catch(() => {
+              // Silently handle tracking errors - timer will still complete
+            });
+          } else {
+            // Track impression without timer UI
+            trackImpression(response.ad.id, apiKey, apiUrl, impressionMetadata);
+          }
         } else {
           // Create a more detailed error message
           const errorDetails = [];
@@ -107,11 +131,19 @@ export function AdBanner({
     };
 
     loadAd();
-  }, [platformId, apiKey, size, apiUrl, userId, userSegment]);
+
+    // Cleanup timer on unmount or when dependencies change
+    return () => {
+      if (impressionTimerRef.current) {
+        clearTimeout(impressionTimerRef.current);
+        impressionTimerRef.current = null;
+      }
+    };
+  }, [platformId, apiKey, size, apiUrl, userId, userSegment, showImpressionFinished, impressionMetadata]);
 
   const handleClick = () => {
     if (ad) {
-      trackClick(ad.id, apiKey, apiUrl);
+      trackClick(ad.id, apiKey, apiUrl, clickMetadata);
       // The link will handle navigation
     }
   };
@@ -133,7 +165,7 @@ export function AdBanner({
   }
 
   return (
-    <div className={className}>
+    <div className={`relative ${className}`}>
       <a
         href={ad.targetUrl}
         onClick={handleClick}
@@ -156,6 +188,45 @@ export function AdBanner({
           </div>
         )}
       </a>
+      {showImpressionFinished && impressionStatus !== 'pending' && (
+        <div className="absolute top-2 right-2">
+          {impressionStatus === 'counting' ? (
+            <svg
+              className="w-5 h-5 text-gray-400 animate-spin"
+              xmlns="http://www.w3.org/2000/svg"
+              fill="none"
+              viewBox="0 0 24 24"
+            >
+              <circle
+                className="opacity-25"
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                strokeWidth="4"
+              />
+              <path
+                className="opacity-75"
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+              />
+            </svg>
+          ) : impressionStatus === 'completed' ? (
+            <svg
+              className="w-5 h-5 text-green-500"
+              xmlns="http://www.w3.org/2000/svg"
+              viewBox="0 0 20 20"
+              fill="currentColor"
+            >
+              <path
+                fillRule="evenodd"
+                d="M10 18a8 8 0 100-16 8 8 0 000 16zm3.707-9.293a1 1 0 00-1.414-1.414L9 10.586 7.707 9.293a1 1 0 00-1.414 1.414l2 2a1 1 0 001.414 0l4-4z"
+                clipRule="evenodd"
+              />
+            </svg>
+          ) : null}
+        </div>
+      )}
       {devMode && (
         <p className="text-xs text-gray-500 mt-1">[DEV] No tracking active</p>
       )}

package/src/lib/ads.ts

@@ -430,8 +430,9 @@ export function collectFingerprint(): Fingerprint {
  * @param adId - The ID of the ad being tracked
  * @param apiKey - The API key for the platform (required for CORS validation and platform identification)
  * @param apiUrl - Optional API base URL override
+ * @param metadata - Optional metadata object to send with the impression event
  */
-export async function trackImpression(adId: string, apiKey: string, apiUrl?: string): Promise<void> {
+export async function trackImpression(adId: string, apiKey: string, apiUrl?: string, metadata?: Record<string, unknown>): Promise<void> {
   try {
     if (!apiKey) {
       console.warn('[AdBanner] Cannot track impression: API key is required');
@@ -482,6 +483,7 @@ export async function trackImpression(adId: string, apiKey: string, apiUrl?: str
         action: 'impression',
         adId,
         fingerprint: collectFingerprint(), // Include fingerprint data for fraud detection
+        ...(metadata && { metadata }), // Include metadata if provided
       }),
     });
     
@@ -519,8 +521,9 @@ export async function trackImpression(adId: string, apiKey: string, apiUrl?: str
  * @param adId - The ID of the ad being tracked
  * @param apiKey - The API key for the platform (required for CORS validation and platform identification)
  * @param apiUrl - Optional API base URL override
+ * @param metadata - Optional metadata object to send with the click event
  */
-export async function trackClick(adId: string, apiKey: string, apiUrl?: string): Promise<void> {
+export async function trackClick(adId: string, apiKey: string, apiUrl?: string, metadata?: Record<string, unknown>): Promise<void> {
   try {
     if (!apiKey) {
       console.warn('[AdBanner] Cannot track click: API key is required');
@@ -571,6 +574,7 @@ export async function trackClick(adId: string, apiKey: string, apiUrl?: string):
         action: 'click',
         adId,
         fingerprint: collectFingerprint(), // Include fingerprint data for fraud detection
+        ...(metadata && { metadata }), // Include metadata if provided
       }),
     });