user-analytics-tracker 2.1.0 → 3.0.0

package/dist/index.cjs.js

@@ -4,6 +4,97 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var react = require('react');
 
+/**
+ * Core types for the analytics tracker package
+ */
+/**
+ * Default essential fields for IP location storage
+ * These fields are stored when mode is 'essential' (default)
+ */
+const DEFAULT_ESSENTIAL_IP_FIELDS = [
+    // Core identification
+    'ip',
+    'country',
+    'countryCode',
+    'region',
+    'city',
+    // Geographic coordinates (stored here, not duplicated in location)
+    'lat',
+    'lon',
+    // Additional geographic info
+    'continent',
+    'continentCode',
+    // Network info
+    'type',
+    'isEu',
+    'isp',
+    'connection',
+    'connection.asn',
+    'connection.org',
+    'connection.isp',
+    'connection.domain',
+    // Timezone (stored here, not duplicated in location)
+    'timezone',
+    'timezoneDetails',
+    'timezoneDetails.id',
+    'timezoneDetails.abbr',
+    'timezoneDetails.utc',
+    // Flag (only emoji in essential mode)
+    'flag.emoji',
+];
+/**
+ * Default essential fields for Device Info storage
+ */
+const DEFAULT_ESSENTIAL_DEVICE_FIELDS = [
+    'type',
+    'os',
+    'osVersion',
+    'browser',
+    'browserVersion',
+    'deviceModel',
+    'deviceBrand',
+    'userAgent',
+];
+/**
+ * Default essential fields for Network Info storage
+ */
+const DEFAULT_ESSENTIAL_NETWORK_FIELDS = [
+    'type',
+    'effectiveType',
+    'downlink',
+    'rtt',
+    'saveData',
+];
+/**
+ * Default essential fields for Location Info storage
+ */
+const DEFAULT_ESSENTIAL_LOCATION_FIELDS = [
+    // Minimal location fields - only coordinates and source
+    // All IP-related data (ip, country, city, etc.) is stored in customData.ipLocation to avoid duplication
+    'lat',
+    'lon',
+    'source',
+    'ts',
+];
+/**
+ * Default essential fields for Attribution Info storage
+ */
+const DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS = [
+    'landingUrl',
+    'path',
+    'hostname',
+    'referrerUrl',
+    'referrerDomain',
+    'navigationType',
+    'isReload',
+    'isBackForward',
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_term',
+    'utm_content',
+];
+
 /**
  * Network Type Detector
  * Detects WiFi, Mobile Data (Cellular), Hotspot, Ethernet, or Unknown
@@ -562,25 +653,28 @@ function checkAndSetLocationConsent(msisdn) {
  * This ensures we capture all available data and any new fields added by the API
  */
 /**
- * Get public IP address using ipwho.is API
+ * Get complete IP location data from ipwho.is API (HIGH PRIORITY)
+ * This is the primary method - gets IP, location, connection, and all data in one call
  * No API key required
  *
- * @returns Promise<string | null> - The public IP address, or null if unavailable
+ * @returns Promise<IPLocation | null> - Complete IP location data, or null if unavailable
  *
  * @example
  * ```typescript
- * const ip = await getPublicIP();
- * console.log('Your IP:', ip); // e.g., "203.0.113.42"
+ * const location = await getCompleteIPLocation();
+ * console.log('IP:', location?.ip);
+ * console.log('Country:', location?.country);
+ * console.log('ISP:', location?.connection?.isp);
  * ```
  */
-async function getPublicIP() {
+async function getCompleteIPLocation() {
     // Skip if we're in an environment without fetch (SSR)
     if (typeof fetch === 'undefined') {
         return null;
     }
     try {
-        // Call ipwho.is without IP parameter - it auto-detects user's IP
-        // Using HTTPS endpoint for better security
+        // Call ipwho.is without IP parameter - it auto-detects user's IP and returns everything
+        // This is the HIGH PRIORITY source - gets IP, location, connection, timezone, flag, etc. in one call
         const response = await fetch('https://ipwho.is/', {
             method: 'GET',
             headers: {
@@ -597,22 +691,105 @@ async function getPublicIP() {
         if (data.success === false) {
             return null;
         }
-        return data.ip || null;
+        // Store all keys dynamically from the response
+        // This ensures we capture all fields, including nested objects and any new fields
+        const locationData = {
+            ip: data.ip,
+            // Map all fields from the API response dynamically
+            ...Object.keys(data).reduce((acc, key) => {
+                // Store all keys and their values, preserving nested objects
+                acc[key] = data[key];
+                return acc;
+            }, {}),
+        };
+        // Add backward compatibility mappings for existing code
+        if (data.latitude !== undefined) {
+            locationData.lat = data.latitude;
+        }
+        if (data.longitude !== undefined) {
+            locationData.lon = data.longitude;
+        }
+        if (data.country_code !== undefined) {
+            locationData.countryCode = data.country_code;
+        }
+        if (data.region !== undefined) {
+            locationData.regionName = data.region;
+        }
+        if (data.connection?.isp !== undefined) {
+            locationData.isp = data.connection.isp;
+        }
+        if (data.connection?.org !== undefined) {
+            locationData.org = data.connection.org;
+        }
+        if (data.connection?.asn !== undefined) {
+            locationData.as = `AS${data.connection.asn}`;
+        }
+        if (data.timezone?.id !== undefined) {
+            locationData.timezone = data.timezone.id;
+        }
+        locationData.query = data.ip;
+        return locationData;
     }
     catch (error) {
         // Silently fail - don't break user experience
         if (error.name !== 'AbortError') {
-            console.warn('[IP Geolocation] Error fetching public IP:', error.message);
+            console.warn('[IP Geolocation] Error fetching complete IP location from ipwho.is:', error.message);
         }
         return null;
     }
 }
 /**
- * Get location from IP address using ipwho.is API
+ * Get public IP address using ipwho.is API (FALLBACK - lower priority)
+ * This is kept for backward compatibility and as a fallback
+ * Prefer getCompleteIPLocation() which gets everything in one call
+ *
+ * @returns Promise<string | null> - The public IP address, or null if unavailable
+ *
+ * @example
+ * ```typescript
+ * const ip = await getPublicIP();
+ * console.log('Your IP:', ip); // e.g., "203.0.113.42"
+ * ```
+ */
+async function getPublicIP() {
+    // Try to get complete location first (includes IP)
+    const completeLocation = await getCompleteIPLocation();
+    if (completeLocation?.ip) {
+        return completeLocation.ip;
+    }
+    // Fallback: try direct IP fetch (less efficient, lower priority)
+    try {
+        const response = await fetch('https://ipwho.is/', {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+            },
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (data.success === false) {
+            return null;
+        }
+        return data.ip || null;
+    }
+    catch (error) {
+        if (error.name !== 'AbortError') {
+            console.warn('[IP Geolocation] Error fetching public IP (fallback):', error.message);
+        }
+        return null;
+    }
+}
+/**
+ * Get location from IP address using ipwho.is API (HIGH PRIORITY)
  * Free tier: No API key required
  *
  * Stores all keys dynamically from the API response, including nested objects
  * This ensures we capture all available data and any new fields added by the API
+ *
+ * Note: If you don't have an IP yet, use getCompleteIPLocation() which gets everything in one call
  */
 async function getIPLocation(ip) {
     // Skip localhost/private IPs (these can't be geolocated)
@@ -1039,15 +1216,21 @@ class LocationDetector {
         }
         this.ipLocationFetchingRef.current = true;
         try {
-            // Get public IP first, then get location
-            const publicIP = await getPublicIP();
-            if (!publicIP) {
-                throw new Error('Could not determine public IP address');
+            // HIGH PRIORITY: Get complete IP location data from ipwho.is in one call
+            // This gets IP, location, connection, timezone, flag, and all other data at once
+            // More efficient than making separate calls
+            let ipLocation = await getCompleteIPLocation();
+            // If complete location fetch failed, try fallback: get IP first, then location
+            if (!ipLocation) {
+                console.log('[Location] Primary ipwho.is call failed, trying fallback...');
+                const publicIP = await getPublicIP();
+                if (publicIP) {
+                    // Fallback: Get location from IP using ipwho.is API
+                    ipLocation = await getIPLocation(publicIP);
+                }
             }
-            // Get location from IP using ipwho.is API
-            const ipLocation = await getIPLocation(publicIP);
             if (!ipLocation) {
-                throw new Error('Could not fetch location data');
+                throw new Error('Could not fetch location data from ipwho.is');
             }
             // Convert IP location to LocationInfo format
             // Map all available fields from the IP location response
@@ -1062,7 +1245,7 @@ class LocationDetector {
                 permission: 'granted', // IP location doesn't require permission
                 source: 'ip',
                 ts: new Date().toISOString(),
-                ip: ipLocation.ip || publicIP,
+                ip: ipLocation.ip || undefined,
                 country: ipLocation.country || undefined,
                 countryCode: ipLocation.country_code || ipLocation.countryCode || undefined,
                 city: ipLocation.city || undefined,
@@ -1072,7 +1255,7 @@ class LocationDetector {
             // Store the full IP location data in a custom field for access to all keys
             // This preserves all dynamic keys from the API response
             locationResult.ipLocationData = ipLocation;
-            console.log('[Location] IP-based location obtained:', {
+            console.log('[Location] IP-based location obtained from ipwho.is:', {
                 ip: locationResult.ip,
                 lat: locationResult.lat,
                 lon: locationResult.lon,
@@ -1080,6 +1263,8 @@ class LocationDetector {
                 country: locationResult.country,
                 continent: ipLocation.continent,
                 timezone: locationResult.timezone,
+                isp: ipLocation.connection?.isp,
+                connection: ipLocation.connection,
             });
             this.lastIPLocationRef.current = locationResult;
             return locationResult;
@@ -1916,6 +2101,264 @@ class MetricsCollector {
 // Global metrics collector instance
 const metricsCollector = new MetricsCollector();
 
+/**
+ * Generic field storage transformer
+ * Filters object fields based on storage configuration
+ */
+/**
+ * Filter object fields based on storage configuration
+ *
+ * @param data - The data object to filter
+ * @param config - Storage configuration
+ * @param defaultEssentialFields - Default essential fields for this data type
+ * @returns Filtered data object with only configured fields
+ */
+function filterFieldsByConfig(data, config, defaultEssentialFields) {
+    if (!data) {
+        return null;
+    }
+    const mode = config?.mode || 'essential';
+    let fieldsToInclude = [];
+    if (mode === 'essential') {
+        // Use default essential fields
+        fieldsToInclude = [...defaultEssentialFields];
+    }
+    else if (mode === 'all') {
+        // Include all fields, then exclude specified ones
+        fieldsToInclude = ['*']; // Special marker for "all fields"
+    }
+    else if (mode === 'custom' && config) {
+        // Use custom field list
+        fieldsToInclude = config.fields || [];
+    }
+    // If mode is 'all', just exclude specified fields
+    if (mode === 'all') {
+        const filtered = { ...data };
+        if (config?.exclude && config.exclude.length > 0) {
+            const excludeSet = new Set(config.exclude);
+            Object.keys(filtered).forEach(key => {
+                if (excludeSet.has(key)) {
+                    delete filtered[key];
+                }
+            });
+            // Handle nested exclusions
+            if (filtered.connection && excludeSet.has('connection')) {
+                delete filtered.connection;
+            }
+            if (filtered.timezoneDetails && excludeSet.has('timezoneDetails')) {
+                delete filtered.timezoneDetails;
+            }
+            if (filtered.flag && excludeSet.has('flag')) {
+                delete filtered.flag;
+            }
+            if (filtered.firstTouch && excludeSet.has('firstTouch')) {
+                delete filtered.firstTouch;
+            }
+            if (filtered.lastTouch && excludeSet.has('lastTouch')) {
+                delete filtered.lastTouch;
+            }
+        }
+        return filtered;
+    }
+    // For 'essential' or 'custom' mode, only include specified fields
+    const filtered = {};
+    const includeSet = new Set(fieldsToInclude);
+    // Helper to check if a field path should be included
+    const shouldInclude = (fieldPath) => {
+        // Direct match - most specific
+        if (includeSet.has(fieldPath))
+            return true;
+        // For nested fields (e.g., 'flag.emoji'), only include if explicitly listed
+        // Don't auto-include all children just because parent is included
+        const parts = fieldPath.split('.');
+        if (parts.length > 1) {
+            // For nested fields, require explicit inclusion
+            // This prevents 'flag' from including all 'flag.*' fields
+            return includeSet.has(fieldPath);
+        }
+        // For top-level fields only, check if parent path is included
+        // This allows 'connection' to work when all connection.* fields are listed
+        return false;
+    };
+    // Helper to check if a parent object should be created (for nested objects)
+    const shouldIncludeParent = (parentPath) => {
+        // Check if any child of this parent is included
+        for (const field of fieldsToInclude) {
+            if (field.startsWith(parentPath + '.')) {
+                return true;
+            }
+        }
+        // Also check if parent itself is explicitly included
+        return includeSet.has(parentPath);
+    };
+    // Filter top-level fields
+    Object.keys(data).forEach(key => {
+        if (shouldInclude(key)) {
+            filtered[key] = data[key];
+        }
+    });
+    // Handle nested objects - only create if at least one child field is included
+    if (data.connection && shouldIncludeParent('connection')) {
+        filtered.connection = {};
+        if (shouldInclude('connection.asn'))
+            filtered.connection.asn = data.connection.asn;
+        if (shouldInclude('connection.org'))
+            filtered.connection.org = data.connection.org;
+        if (shouldInclude('connection.isp'))
+            filtered.connection.isp = data.connection.isp;
+        if (shouldInclude('connection.domain'))
+            filtered.connection.domain = data.connection.domain;
+        // If no connection fields were included, remove the object
+        if (Object.keys(filtered.connection).length === 0) {
+            delete filtered.connection;
+        }
+    }
+    if (data.timezoneDetails && shouldIncludeParent('timezoneDetails')) {
+        filtered.timezoneDetails = {};
+        if (shouldInclude('timezoneDetails.id'))
+            filtered.timezoneDetails.id = data.timezoneDetails.id;
+        if (shouldInclude('timezoneDetails.abbr'))
+            filtered.timezoneDetails.abbr = data.timezoneDetails.abbr;
+        if (shouldInclude('timezoneDetails.utc'))
+            filtered.timezoneDetails.utc = data.timezoneDetails.utc;
+        if (shouldInclude('timezoneDetails.isDst'))
+            filtered.timezoneDetails.isDst = data.timezoneDetails.isDst;
+        if (shouldInclude('timezoneDetails.offset'))
+            filtered.timezoneDetails.offset = data.timezoneDetails.offset;
+        if (shouldInclude('timezoneDetails.currentTime'))
+            filtered.timezoneDetails.currentTime = data.timezoneDetails.currentTime;
+        // If no timezoneDetails fields were included, remove the object
+        if (Object.keys(filtered.timezoneDetails).length === 0) {
+            delete filtered.timezoneDetails;
+        }
+    }
+    if (data.flag && shouldIncludeParent('flag')) {
+        filtered.flag = {};
+        // Only include specific flag fields if they're explicitly in the include list
+        if (shouldInclude('flag.emoji'))
+            filtered.flag.emoji = data.flag.emoji;
+        if (shouldInclude('flag.img'))
+            filtered.flag.img = data.flag.img;
+        if (shouldInclude('flag.emojiUnicode'))
+            filtered.flag.emojiUnicode = data.flag.emojiUnicode;
+        // If no specific flag fields are included, don't add the flag object
+        if (Object.keys(filtered.flag).length === 0) {
+            delete filtered.flag;
+        }
+    }
+    if (data.firstTouch && shouldInclude('firstTouch')) {
+        filtered.firstTouch = data.firstTouch;
+    }
+    if (data.lastTouch && shouldInclude('lastTouch')) {
+        filtered.lastTouch = data.lastTouch;
+    }
+    // Remove null and undefined values to reduce payload size
+    const cleanValue = (val) => {
+        if (val === null || val === undefined) {
+            return undefined; // Will be filtered out
+        }
+        // For objects, recursively clean nested null/undefined values
+        if (typeof val === 'object' && !Array.isArray(val) && val !== null) {
+            const cleaned = {};
+            let hasAnyValue = false;
+            Object.keys(val).forEach(key => {
+                const cleanedChild = cleanValue(val[key]);
+                if (cleanedChild !== undefined) {
+                    cleaned[key] = cleanedChild;
+                    hasAnyValue = true;
+                }
+            });
+            return hasAnyValue ? cleaned : undefined;
+        }
+        // For arrays, clean each element
+        if (Array.isArray(val)) {
+            const cleaned = val.map(cleanValue).filter(item => item !== undefined);
+            return cleaned.length > 0 ? cleaned : undefined;
+        }
+        return val;
+    };
+    const cleaned = {};
+    Object.keys(filtered).forEach(key => {
+        const cleanedValue = cleanValue(filtered[key]);
+        if (cleanedValue !== undefined) {
+            cleaned[key] = cleanedValue;
+        }
+    });
+    return cleaned;
+}
+
+/**
+ * Transform IP location data from API format (snake_case) to backend-expected format (camelCase)
+ * Supports configurable field storage to optimize storage capacity
+ *
+ * @param ipLocation - Raw IP location data from ipwho.is API
+ * @param config - Optional configuration for which fields to store
+ * @returns Transformed IP location data matching backend schema (only includes configured fields)
+ */
+function transformIPLocationForBackend(ipLocation, config) {
+    if (!ipLocation) {
+        return null;
+    }
+    // Transform to match backend expected format (camelCase)
+    // Build complete object first, then filter based on configuration
+    const transformed = {
+        // Basic fields
+        ip: ipLocation.ip,
+        country: ipLocation.country,
+        countryCode: ipLocation.country_code || ipLocation.countryCode,
+        region: ipLocation.region || ipLocation.regionName,
+        city: ipLocation.city,
+        postal: ipLocation.postal,
+        capital: ipLocation.capital,
+        callingCode: ipLocation.calling_code || ipLocation.callingCode,
+        // Geographic fields
+        continent: ipLocation.continent,
+        continentCode: ipLocation.continent_code || ipLocation.continentCode,
+        lat: ipLocation.latitude ?? ipLocation.lat,
+        lon: ipLocation.longitude ?? ipLocation.lon,
+        borders: ipLocation.borders,
+        // Network fields
+        type: ipLocation.type,
+        isEu: ipLocation.is_eu ?? ipLocation.isEu,
+        // ISP/Connection - preserve connection object and also add top-level isp
+        isp: ipLocation.connection?.isp || ipLocation.isp,
+        connection: ipLocation.connection ? {
+            asn: ipLocation.connection.asn,
+            org: ipLocation.connection.org,
+            isp: ipLocation.connection.isp,
+            domain: ipLocation.connection.domain,
+        } : undefined,
+        // Timezone - store both simple string and full details object
+        timezone: typeof ipLocation.timezone === 'string'
+            ? ipLocation.timezone
+            : ipLocation.timezone?.id,
+        timezoneDetails: ipLocation.timezone && typeof ipLocation.timezone === 'object' ? {
+            id: ipLocation.timezone.id,
+            abbr: ipLocation.timezone.abbr,
+            utc: ipLocation.timezone.utc,
+            // Exclude these in essential mode: isDst, offset, currentTime
+            // They will be filtered out by filterFieldsByConfig if not in essential fields
+            isDst: ipLocation.timezone.is_dst,
+            offset: ipLocation.timezone.offset,
+            currentTime: ipLocation.timezone.current_time,
+        } : undefined,
+        // Flag - transform to camelCase
+        flag: ipLocation.flag ? {
+            img: ipLocation.flag.img,
+            emoji: ipLocation.flag.emoji,
+            emojiUnicode: ipLocation.flag.emoji_unicode,
+        } : undefined,
+    };
+    // Remove undefined values to keep the payload clean
+    Object.keys(transformed).forEach(key => {
+        if (transformed[key] === undefined) {
+            delete transformed[key];
+        }
+    });
+    // Filter fields based on configuration using generic filter
+    return filterFieldsByConfig(transformed, config, DEFAULT_ESSENTIAL_IP_FIELDS);
+}
+
 /**
  * Analytics Service
  * Sends analytics events to your backend API
@@ -2179,18 +2622,50 @@ class AnalyticsService {
      * Track user journey with full context
      */
     static async trackUserJourney({ sessionId, pageUrl, networkInfo, deviceInfo, location, attribution, ipLocation, userId, customData, pageVisits = 1, interactions = 0, }) {
+        // Get field storage config (support both new and legacy format)
+        const fieldStorage = this.config.fieldStorage || {};
+        const ipLocationConfig = fieldStorage.ipLocation || this.config.ipLocationFields;
+        // Transform and filter all data types based on configuration
+        const transformedIPLocation = transformIPLocationForBackend(ipLocation, ipLocationConfig);
+        const filteredDeviceInfo = filterFieldsByConfig(deviceInfo, fieldStorage.deviceInfo, DEFAULT_ESSENTIAL_DEVICE_FIELDS);
+        const filteredNetworkInfo = filterFieldsByConfig(networkInfo, fieldStorage.networkInfo, DEFAULT_ESSENTIAL_NETWORK_FIELDS);
+        // For location: In essential mode, remove duplicate fields that are already in customData.ipLocation
+        // This prevents storing the same data twice (e.g., ip, country, city, region, timezone)
+        const locationConfig = fieldStorage.location;
+        const locationMode = locationConfig?.mode || 'essential';
+        let filteredLocation = filterFieldsByConfig(location, locationConfig, DEFAULT_ESSENTIAL_LOCATION_FIELDS);
+        // In essential mode, if we have IP location data, remove duplicate fields from location
+        // to avoid storing the same data twice
+        if (locationMode === 'essential' && transformedIPLocation && filteredLocation) {
+            // Remove fields that are duplicated in customData.ipLocation
+            const duplicateFields = ['ip', 'country', 'countryCode', 'city', 'region', 'timezone'];
+            const minimalLocation = { ...filteredLocation };
+            duplicateFields.forEach(field => {
+                delete minimalLocation[field];
+            });
+            // Only keep essential location fields: lat, lon, source, ts
+            filteredLocation = {
+                lat: minimalLocation.lat,
+                lon: minimalLocation.lon,
+                source: minimalLocation.source,
+                ts: minimalLocation.ts,
+            };
+        }
+        const filteredAttribution = filterFieldsByConfig(attribution, fieldStorage.attribution, DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS);
         await this.trackEvent({
             sessionId,
             pageUrl,
-            networkInfo,
-            deviceInfo,
-            location,
-            attribution,
-            ipLocation,
+            networkInfo: filteredNetworkInfo || undefined,
+            deviceInfo: filteredDeviceInfo || undefined,
+            location: filteredLocation || undefined,
+            attribution: filteredAttribution || undefined,
+            // Don't include raw ipLocation - we have the filtered/transformed version in customData
+            ipLocation: undefined,
             userId: userId ?? sessionId,
             customData: {
                 ...customData,
-                ...(ipLocation && { ipLocation }),
+                // Store transformed and filtered IP location in customData for backend integration
+                ...(transformedIPLocation && { ipLocation: transformedIPLocation }),
             },
             eventName: 'page_view', // Auto-tracked as page view
         });
@@ -2261,17 +2736,54 @@ class AnalyticsService {
         }
         const finalSessionId = context?.sessionId || autoContext?.sessionId || 'unknown';
         const finalPageUrl = context?.pageUrl || autoContext?.pageUrl || '';
+        // Extract IP location from location object if available
+        const locationData = context?.location || autoContext?.location;
+        const ipLocationData = locationData && typeof locationData === 'object'
+            ? locationData?.ipLocationData
+            : undefined;
+        // Get field storage config (support both new and legacy format)
+        const fieldStorage = this.config.fieldStorage || {};
+        const ipLocationConfig = fieldStorage.ipLocation || this.config.ipLocationFields;
+        // Transform and filter all data types based on configuration
+        const transformedIPLocation = transformIPLocationForBackend(ipLocationData, ipLocationConfig);
+        const filteredDeviceInfo = filterFieldsByConfig(context?.deviceInfo || autoContext?.deviceInfo, fieldStorage.deviceInfo, DEFAULT_ESSENTIAL_DEVICE_FIELDS);
+        const filteredNetworkInfo = filterFieldsByConfig(context?.networkInfo || autoContext?.networkInfo, fieldStorage.networkInfo, DEFAULT_ESSENTIAL_NETWORK_FIELDS);
+        // For location: In essential mode, remove duplicate fields that are already in customData.ipLocation
+        const locationConfig = fieldStorage.location;
+        const locationMode = locationConfig?.mode || 'essential';
+        let filteredLocation = filterFieldsByConfig((context?.location || autoContext?.location), locationConfig, DEFAULT_ESSENTIAL_LOCATION_FIELDS);
+        // In essential mode, if we have IP location data, remove duplicate fields from location
+        if (locationMode === 'essential' && transformedIPLocation && filteredLocation) {
+            // Remove fields that are duplicated in customData.ipLocation
+            const duplicateFields = ['ip', 'country', 'countryCode', 'city', 'region', 'timezone'];
+            const minimalLocation = { ...filteredLocation };
+            duplicateFields.forEach(field => {
+                delete minimalLocation[field];
+            });
+            // Only keep essential location fields: lat, lon, source, ts
+            filteredLocation = {
+                lat: minimalLocation.lat,
+                lon: minimalLocation.lon,
+                source: minimalLocation.source,
+                ts: minimalLocation.ts,
+            };
+        }
+        const filteredAttribution = filterFieldsByConfig(context?.attribution || autoContext?.attribution, fieldStorage.attribution, DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS);
         await this.trackEvent({
             sessionId: finalSessionId,
             pageUrl: finalPageUrl,
-            networkInfo: context?.networkInfo || autoContext?.networkInfo,
-            deviceInfo: context?.deviceInfo || autoContext?.deviceInfo,
-            location: context?.location || autoContext?.location,
-            attribution: context?.attribution || autoContext?.attribution,
+            networkInfo: filteredNetworkInfo || undefined,
+            deviceInfo: filteredDeviceInfo || undefined,
+            location: filteredLocation || undefined,
+            attribution: filteredAttribution || undefined,
             userId: context?.userId || finalSessionId,
             eventName,
             eventParameters: parameters || {},
-            customData: parameters || {},
+            customData: {
+                ...(parameters || {}),
+                // Store transformed IP location in customData for backend integration
+                ...(transformedIPLocation && { ipLocation: transformedIPLocation }),
+            },
         });
     }
     /**
@@ -2449,6 +2961,8 @@ function useAnalytics(options = {}) {
                 logLevel: config.logLevel,
                 enableMetrics: config.enableMetrics,
                 sessionTimeout: config.sessionTimeout,
+                fieldStorage: config.fieldStorage,
+                ipLocationFields: config.ipLocationFields, // Legacy support
             });
         }
     }, [
@@ -2736,6 +3250,11 @@ function useAnalytics(options = {}) {
 
 exports.AnalyticsService = AnalyticsService;
 exports.AttributionDetector = AttributionDetector;
+exports.DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS = DEFAULT_ESSENTIAL_ATTRIBUTION_FIELDS;
+exports.DEFAULT_ESSENTIAL_DEVICE_FIELDS = DEFAULT_ESSENTIAL_DEVICE_FIELDS;
+exports.DEFAULT_ESSENTIAL_IP_FIELDS = DEFAULT_ESSENTIAL_IP_FIELDS;
+exports.DEFAULT_ESSENTIAL_LOCATION_FIELDS = DEFAULT_ESSENTIAL_LOCATION_FIELDS;
+exports.DEFAULT_ESSENTIAL_NETWORK_FIELDS = DEFAULT_ESSENTIAL_NETWORK_FIELDS;
 exports.DeviceDetector = DeviceDetector;
 exports.LocationDetector = LocationDetector;
 exports.NetworkDetector = NetworkDetector;
@@ -2744,6 +3263,8 @@ exports.checkAndSetLocationConsent = checkAndSetLocationConsent;
 exports.clearLocationConsent = clearLocationConsent;
 exports.clearSession = clearSession;
 exports.default = useAnalytics;
+exports.filterFieldsByConfig = filterFieldsByConfig;
+exports.getCompleteIPLocation = getCompleteIPLocation;
 exports.getIPFromRequest = getIPFromRequest;
 exports.getIPLocation = getIPLocation;
 exports.getLocationConsentTimestamp = getLocationConsentTimestamp;
@@ -2760,6 +3281,7 @@ exports.saveJSON = saveJSON;
 exports.saveSessionJSON = saveSessionJSON;
 exports.setLocationConsentGranted = setLocationConsentGranted;
 exports.trackPageVisit = trackPageVisit;
+exports.transformIPLocationForBackend = transformIPLocationForBackend;
 exports.updateSessionActivity = updateSessionActivity;
 exports.useAnalytics = useAnalytics;
 //# sourceMappingURL=index.cjs.js.map