@thead-vantage/react 2.15.0 → 2.17.0

package/README.md

@@ -184,7 +184,7 @@ export default function ArticlePage() {
 You can also use the utility functions directly:
 
 ```tsx
-import { fetchAdBanner, trackImpression, trackClick } from '@/lib/ads';
+import { fetchAdBanner, trackImpression, trackClick, collectFingerprint } from '@/lib/ads';
 
 // Fetch an ad
 const response = await fetchAdBanner({
@@ -196,8 +196,14 @@ const response = await fetchAdBanner({
 });
 
 // Track events (automatically skipped in TheAd Vantage dev mode)
-trackImpression(adId);
-trackClick(adId);
+// Note: trackImpression and trackClick now require apiKey parameter
+// They automatically include client fingerprinting data for fraud detection
+trackImpression(adId, apiKey);
+trackClick(adId, apiKey);
+
+// You can also collect fingerprint data manually if needed
+const fingerprint = collectFingerprint();
+console.log('Client fingerprint:', fingerprint);
 ```
 
 ---
@@ -335,8 +341,9 @@ The TheAd Vantage integration uses a smart mode detection system to support diff
 ### Utilities
 - **`src/lib/ads.ts`**: Utility functions for fetching and tracking ads
   - `fetchAdBanner(params)`: Fetches ads with full parameter support
-  - `trackImpression(adId)`: Tracks ad impressions (skipped in dev mode)
-  - `trackClick(adId)`: Tracks ad clicks (skipped in dev mode)
+  - `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)
+  - `collectFingerprint()`: Collects client fingerprinting data for fraud detection
 
 ## Implementation Instructions for AI Agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thead-vantage/react",
-  "version": "2.15.0",
+  "version": "2.17.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

@@ -43,17 +43,22 @@ export function AdBanner({
           userSegment,
         });
 
-        console.log('[AdBanner] Processed response:', {
-          success: response.success,
-          hasAd: !!response.ad,
-          devMode: response.dev_mode,
-          message: response.message,
-          _dev_note: response._dev_note,
-          fullResponse: response,
-        });
+        // Only log in development mode
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[AdBanner] Processed response:', {
+            success: response.success,
+            hasAd: !!response.ad,
+            devMode: response.dev_mode,
+            message: response.message,
+            _dev_note: response._dev_note,
+            fullResponse: response,
+          });
+        }
 
         if (response.success && response.ad) {
-          console.log('[AdBanner] Setting ad:', response.ad);
+          if (process.env.NODE_ENV === 'development') {
+            console.log('[AdBanner] Setting ad:', response.ad);
+          }
           setAd(response.ad);
           setDevMode(response.dev_mode || false);
 

package/src/index.ts

@@ -14,11 +14,13 @@ export {
   fetchAdBanner,
   trackImpression,
   trackClick,
+  collectFingerprint,
   type Ad,
   type AdData,
   type AdsResponse,
   type AdBannerResponse,
   type FetchAdBannerParams,
+  type Fingerprint,
 } from './lib/ads';
 
 // Export configuration utilities

package/src/lib/ads.ts

@@ -3,7 +3,17 @@
  * Automatically handles development mode to prevent tracking
  */
 
-import { getApiBaseUrl, shouldUseDevFlags } from './thead-vantage-config';
+import { getApiBaseUrl, shouldUseDevFlags, isDevelopmentMode } from './thead-vantage-config';
+
+/**
+ * Helper function to log only in development mode
+ * Errors and warnings are always logged
+ */
+function devLog(...args: unknown[]): void {
+  if (process.env.NODE_ENV === 'development' || isDevelopmentMode()) {
+    console.log(...args);
+  }
+}
 
 export interface AdData {
   id: string;
@@ -147,7 +157,7 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
     
     // Log the request (without exposing the API key)
     const logUrl = url.replace(new RegExp(`api_key=${params.apiKey}`, 'g'), 'api_key=***');
-    console.log('[AdBanner] Fetching ad from:', logUrl);
+    devLog('[AdBanner] Fetching ad from:', logUrl);
 
     // Make direct request to thead-vantage.com
     // Try to make a "simple request" that doesn't trigger preflight
@@ -205,8 +215,8 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
       const data: AdsResponse = await response.json();
 
       // Debug logging - log the FULL response to see exactly what we're getting
-      console.log('[AdBanner] Full API Response:', JSON.stringify(data, null, 2));
-      console.log('[AdBanner] API Response Summary:', {
+      devLog('[AdBanner] Full API Response:', JSON.stringify(data, null, 2));
+      devLog('[AdBanner] API Response Summary:', {
       success: data.success,
       hasAd: !!data.ad,
       hasAds: !!(data.ads && Array.isArray(data.ads)),
@@ -246,19 +256,19 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
 
       // Handle both single ad and array of ads
       if (data.ads && Array.isArray(data.ads) && data.ads.length > 0) {
-      // If we get an array, use the first ad and ensure it's Ad type
-      const firstAd = data.ads[0];
-      console.log('[AdBanner] Processing ads array, first ad:', JSON.stringify(firstAd, null, 2));
-      
-      // Check if it's already an Ad, otherwise convert from AdData
-      let ad: Ad = isAd(firstAd) 
-        ? firstAd 
-        : convertToAd(firstAd as AdData);
-      
-      // Normalize the type (standard -> image)
-      ad = normalizeAdType(ad);
-      
-      console.log('[AdBanner] Converted ad:', JSON.stringify(ad, null, 2));
+        // If we get an array, use the first ad and ensure it's Ad type
+        const firstAd = data.ads[0];
+        devLog('[AdBanner] Processing ads array, first ad:', JSON.stringify(firstAd, null, 2));
+        
+        // Check if it's already an Ad, otherwise convert from AdData
+        let ad: Ad = isAd(firstAd) 
+          ? firstAd 
+          : convertToAd(firstAd as AdData);
+        
+        // Normalize the type (standard -> image)
+        ad = normalizeAdType(ad);
+        
+        devLog('[AdBanner] Converted ad:', JSON.stringify(ad, null, 2));
       
       return {
         success: data.success,
@@ -271,19 +281,19 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
 
       // Handle single ad response - convert AdData to Ad
       if (data.ad) {
-      console.log('[AdBanner] Processing single ad:', JSON.stringify(data.ad, null, 2));
-      
-      // Check if it's already in Ad format or needs conversion
-      let ad: Ad;
-      if (isAd(data.ad)) {
-        // Already in Ad format, normalize the type
-        ad = normalizeAdType(data.ad);
-      } else {
-        // Convert from AdData format
-        ad = convertToAd(data.ad);
-      }
-      
-      console.log('[AdBanner] Converted ad:', JSON.stringify(ad, null, 2));
+        devLog('[AdBanner] Processing single ad:', JSON.stringify(data.ad, null, 2));
+        
+        // Check if it's already in Ad format or needs conversion
+        let ad: Ad;
+        if (isAd(data.ad)) {
+          // Already in Ad format, normalize the type
+          ad = normalizeAdType(data.ad);
+        } else {
+          // Convert from AdData format
+          ad = convertToAd(data.ad);
+        }
+        
+        devLog('[AdBanner] Converted ad:', JSON.stringify(ad, null, 2));
       
       return {
         success: data.success,
@@ -360,9 +370,62 @@ export async function fetchAdBanner(params: FetchAdBannerParams): Promise<AdBann
   }
 }
 
+/**
+ * Collect client fingerprinting data for fraud detection
+ * This data is used by the server to detect duplicate impressions, bot traffic, and fraudulent clicks
+ */
+export interface Fingerprint {
+  screenWidth: number | null;
+  screenHeight: number | null;
+  timezone: string | null;
+  language: string | null;
+  colorDepth: number | null;
+  platform: string | null;
+  cookiesEnabled: boolean | null;
+}
+
+export function collectFingerprint(): Fingerprint {
+  // Only collect fingerprint in browser context
+  if (typeof window === 'undefined') {
+    return {
+      screenWidth: null,
+      screenHeight: null,
+      timezone: null,
+      language: null,
+      colorDepth: null,
+      platform: null,
+      cookiesEnabled: null,
+    };
+  }
+
+  try {
+    return {
+      screenWidth: window.screen?.width ?? null,
+      screenHeight: window.screen?.height ?? null,
+      timezone: Intl?.DateTimeFormat?.()?.resolvedOptions?.()?.timeZone ?? null,
+      language: navigator?.language ?? null,
+      colorDepth: window.screen?.colorDepth ?? null,
+      platform: navigator?.platform ?? null,
+      cookiesEnabled: navigator?.cookieEnabled ?? null,
+    };
+  } catch (error) {
+    console.warn('[AdBanner] Error collecting fingerprint:', error);
+    return {
+      screenWidth: null,
+      screenHeight: null,
+      timezone: null,
+      language: null,
+      colorDepth: null,
+      platform: null,
+      cookiesEnabled: null,
+    };
+  }
+}
+
 /**
  * Track an ad impression (when ad is viewed)
  * Sends tracking directly to TheAd Vantage API (or skips in dev mode)
+ * Includes client fingerprinting data for fraud detection
  * 
  * @param adId - The ID of the ad being tracked
  * @param apiKey - The API key for the platform (required for CORS validation and platform identification)
@@ -403,7 +466,7 @@ export async function trackImpression(adId: string, apiKey: string, apiUrl?: str
     // Check if we should skip tracking (dev mode)
     const useDevFlags = shouldUseDevFlags();
     if (useDevFlags) {
-      console.log(`[DEV] Impression tracking skipped for ad: ${adId}`);
+      devLog(`[DEV] Impression tracking skipped for ad: ${adId}`);
       return;
     }
     
@@ -418,6 +481,7 @@ export async function trackImpression(adId: string, apiKey: string, apiUrl?: str
       body: JSON.stringify({
         action: 'impression',
         adId,
+        fingerprint: collectFingerprint(), // Include fingerprint data for fraud detection
       }),
     });
     
@@ -431,16 +495,16 @@ export async function trackImpression(adId: string, apiKey: string, apiUrl?: str
     
     const data = await response.json();
     if (data.dev_mode) {
-      console.log(`[DEV] Impression tracking skipped for ad: ${adId}`);
+      devLog(`[DEV] Impression tracking skipped for ad: ${adId}`);
     } else {
-      console.debug(`[AdBanner] Impression tracked successfully for ad: ${adId}`);
+      devLog(`[AdBanner] Impression tracked successfully for ad: ${adId}`);
     }
   } catch (error) {
-    // Handle CORS errors gracefully (tracking failures shouldn't break the app)
-    if (error instanceof TypeError && (error.message.includes('CORS') || error.message.includes('Failed to fetch'))) {
-      // This is expected until the server configures CORS for /api/ads/track endpoint
-      // The ad still displays correctly, tracking just won't work until server-side CORS is fixed
-      console.debug(`[AdBanner] Tracking impression failed (CORS): The /api/ads/track endpoint needs CORS headers configured on the server. Ad still displayed successfully.`);
+      // Handle CORS errors gracefully (tracking failures shouldn't break the app)
+      if (error instanceof TypeError && (error.message.includes('CORS') || error.message.includes('Failed to fetch'))) {
+        // This is expected until the server configures CORS for /api/ads/track endpoint
+        // The ad still displays correctly, tracking just won't work until server-side CORS is fixed
+        devLog(`[AdBanner] Tracking impression failed (CORS): The /api/ads/track endpoint needs CORS headers configured on the server. Ad still displayed successfully.`);
     } else {
       console.error('Error tracking impression:', error);
     }
@@ -491,7 +555,7 @@ export async function trackClick(adId: string, apiKey: string, apiUrl?: string):
     // Check if we should skip tracking (dev mode)
     const useDevFlags = shouldUseDevFlags();
     if (useDevFlags) {
-      console.log(`[DEV] Click tracking skipped for ad: ${adId}`);
+      devLog(`[DEV] Click tracking skipped for ad: ${adId}`);
       return;
     }
     
@@ -506,6 +570,7 @@ export async function trackClick(adId: string, apiKey: string, apiUrl?: string):
       body: JSON.stringify({
         action: 'click',
         adId,
+        fingerprint: collectFingerprint(), // Include fingerprint data for fraud detection
       }),
     });
     
@@ -519,16 +584,16 @@ export async function trackClick(adId: string, apiKey: string, apiUrl?: string):
     
     const data = await response.json();
     if (data.dev_mode) {
-      console.log(`[DEV] Click tracking skipped for ad: ${adId}`);
+      devLog(`[DEV] Click tracking skipped for ad: ${adId}`);
     } else {
-      console.debug(`[AdBanner] Click tracked successfully for ad: ${adId}`);
+      devLog(`[AdBanner] Click tracked successfully for ad: ${adId}`);
     }
   } catch (error) {
     // Handle CORS errors gracefully (tracking failures shouldn't break the app)
     if (error instanceof TypeError && (error.message.includes('CORS') || error.message.includes('Failed to fetch'))) {
       // This is expected until the server configures CORS for /api/ads/track endpoint
       // The ad still works correctly, click tracking just won't work until server-side CORS is fixed
-      console.debug(`[AdBanner] Tracking click failed (CORS): The /api/ads/track endpoint needs CORS headers configured on the server. Ad still works correctly.`);
+      devLog(`[AdBanner] Tracking click failed (CORS): The /api/ads/track endpoint needs CORS headers configured on the server. Ad still works correctly.`);
     } else {
       console.error('Error tracking click:', error);
     }

package/src/lib/thead-vantage-config.ts

@@ -116,15 +116,9 @@ export function getApiBaseUrl(explicitApiUrl?: string): string {
   }
 
   // Log which URL was selected (helpful for debugging)
-  // Always log in browser context, but only in development for server-side
-  if (typeof window !== 'undefined') {
-    if (process.env.NODE_ENV === 'development') {
-      console.log(`[TheAd Vantage] API Base URL selected: ${selectedUrl} (reason: ${reason})`);
-    } else {
-      // In production, log to console but only if there's an issue (helps with debugging)
-      // We'll log errors separately, but this helps identify configuration issues
-      console.debug(`[TheAd Vantage] API Base URL: ${selectedUrl}`);
-    }
+  // Only log in development mode
+  if (typeof window !== 'undefined' && (process.env.NODE_ENV === 'development' || isDevelopmentMode())) {
+    console.log(`[TheAd Vantage] API Base URL selected: ${selectedUrl} (reason: ${reason})`);
   }
 
   return selectedUrl;