@datalyr/react-native 1.2.1 → 1.3.0

package/src/ConversionValueEncoder.ts

@@ -1,8 +1,12 @@
-// Interface definitions
+import { SKANCoarseValue, SKANConversionResult } from './native/SKAdNetworkBridge';
+
+// SKAN 4.0 compatible event mapping
 interface EventMapping {
   bits: number[];
   revenueBits?: number[];
   priority: number;
+  coarseValue?: SKANCoarseValue;  // SKAN 4.0: low, medium, high
+  lockWindow?: boolean;           // SKAN 4.0: lock the conversion window after this event
 }
 
 interface ConversionTemplate {
@@ -18,11 +22,21 @@ export class ConversionValueEncoder {
   }
 
   /**
-   * Encode an event into Apple's 0-63 conversion value format
+   * Encode an event into Apple's 0-63 conversion value format (SKAN 3.0 compatible)
+   * @deprecated Use encodeWithSKAN4 for iOS 16.1+
    */
   encode(event: string, properties?: Record<string, any>): number {
+    return this.encodeWithSKAN4(event, properties).fineValue;
+  }
+
+  /**
+   * Encode an event with full SKAN 4.0 support (fine value, coarse value, lock window)
+   */
+  encodeWithSKAN4(event: string, properties?: Record<string, any>): SKANConversionResult {
     const mapping = this.template.events[event];
-    if (!mapping) return 0;
+    if (!mapping) {
+      return { fineValue: 0, coarseValue: 'low', lockWindow: false, priority: 0 };
+    }
 
     let conversionValue = 0;
 
@@ -32,18 +46,30 @@ export class ConversionValueEncoder {
     }
 
     // Set revenue bits if revenue is provided
+    let coarseValue: SKANCoarseValue = mapping.coarseValue || 'medium';
     if (mapping.revenueBits && properties) {
       const revenue = properties.revenue || properties.value || 0;
       const revenueTier = this.getRevenueTier(revenue);
-      
+
       for (let i = 0; i < Math.min(mapping.revenueBits.length, 3); i++) {
         if ((revenueTier >> i) & 1) {
           conversionValue |= (1 << mapping.revenueBits[i]);
         }
       }
+
+      // Upgrade coarse value based on revenue
+      coarseValue = this.getCoarseValueForRevenue(revenue);
     }
 
-    return Math.min(conversionValue, 63);
+    // Ensure value is within 0-63 range
+    const fineValue = Math.min(conversionValue, 63);
+
+    return {
+      fineValue,
+      coarseValue,
+      lockWindow: mapping.lockWindow || false,
+      priority: mapping.priority
+    };
   }
 
   /**
@@ -59,43 +85,58 @@ export class ConversionValueEncoder {
     if (revenue < 250) return 6;    // $100-250
     return 7;                       // $250+
   }
+
+  /**
+   * Map revenue to SKAN 4.0 coarse value
+   */
+  private getCoarseValueForRevenue(revenue: number): SKANCoarseValue {
+    if (revenue < 10) return 'low';      // $0-10 = low value
+    if (revenue < 50) return 'medium';   // $10-50 = medium value
+    return 'high';                       // $50+ = high value
+  }
 }
 
-// Industry templates
+// Industry templates with SKAN 4.0 support
 export const ConversionTemplates = {
+  // E-commerce template - optimized for online stores
+  // SKAN 4.0: purchase locks window, high-value events get "high" coarse value
   ecommerce: {
     name: 'ecommerce',
     events: {
-      purchase: { bits: [0], revenueBits: [1, 2, 3], priority: 100 },
-      add_to_cart: { bits: [4], priority: 30 },
-      begin_checkout: { bits: [5], priority: 50 },
-      signup: { bits: [6], priority: 20 },
-      subscribe: { bits: [0, 1], revenueBits: [2, 3, 4], priority: 90 },
-      view_item: { bits: [7], priority: 10 }
+      purchase: { bits: [0], revenueBits: [1, 2, 3], priority: 100, coarseValue: 'high' as SKANCoarseValue, lockWindow: true },
+      add_to_cart: { bits: [4], priority: 30, coarseValue: 'low' as SKANCoarseValue },
+      begin_checkout: { bits: [5], priority: 50, coarseValue: 'medium' as SKANCoarseValue },
+      signup: { bits: [6], priority: 20, coarseValue: 'low' as SKANCoarseValue },
+      subscribe: { bits: [0, 1], revenueBits: [2, 3, 4], priority: 90, coarseValue: 'high' as SKANCoarseValue, lockWindow: true },
+      view_item: { bits: [7], priority: 10, coarseValue: 'low' as SKANCoarseValue }
     }
   } as ConversionTemplate,
-  
+
+  // Gaming template - optimized for mobile games
+  // SKAN 4.0: purchase locks window, tutorial completion is medium value
   gaming: {
     name: 'gaming',
     events: {
-      level_complete: { bits: [0], priority: 40 },
-      tutorial_complete: { bits: [1], priority: 60 },
-      purchase: { bits: [2], revenueBits: [3, 4, 5], priority: 100 },
-      achievement_unlocked: { bits: [6], priority: 30 },
-      session_start: { bits: [7], priority: 10 },
-      ad_watched: { bits: [0, 6], priority: 20 }
+      level_complete: { bits: [0], priority: 40, coarseValue: 'medium' as SKANCoarseValue },
+      tutorial_complete: { bits: [1], priority: 60, coarseValue: 'medium' as SKANCoarseValue },
+      purchase: { bits: [2], revenueBits: [3, 4, 5], priority: 100, coarseValue: 'high' as SKANCoarseValue, lockWindow: true },
+      achievement_unlocked: { bits: [6], priority: 30, coarseValue: 'low' as SKANCoarseValue },
+      session_start: { bits: [7], priority: 10, coarseValue: 'low' as SKANCoarseValue },
+      ad_watched: { bits: [0, 6], priority: 20, coarseValue: 'low' as SKANCoarseValue }
     }
   } as ConversionTemplate,
-  
+
+  // Subscription template - optimized for subscription apps
+  // SKAN 4.0: subscribe/upgrade lock window, trial is medium value
   subscription: {
     name: 'subscription',
     events: {
-      trial_start: { bits: [0], priority: 70 },
-      subscribe: { bits: [1], revenueBits: [2, 3, 4], priority: 100 },
-      upgrade: { bits: [1, 5], revenueBits: [2, 3, 4], priority: 90 },
-      cancel: { bits: [6], priority: 20 },
-      signup: { bits: [7], priority: 30 },
-      payment_method_added: { bits: [0, 7], priority: 50 }
+      trial_start: { bits: [0], priority: 70, coarseValue: 'medium' as SKANCoarseValue },
+      subscribe: { bits: [1], revenueBits: [2, 3, 4], priority: 100, coarseValue: 'high' as SKANCoarseValue, lockWindow: true },
+      upgrade: { bits: [1, 5], revenueBits: [2, 3, 4], priority: 90, coarseValue: 'high' as SKANCoarseValue, lockWindow: true },
+      cancel: { bits: [6], priority: 20, coarseValue: 'low' as SKANCoarseValue },
+      signup: { bits: [7], priority: 30, coarseValue: 'low' as SKANCoarseValue },
+      payment_method_added: { bits: [0, 7], priority: 50, coarseValue: 'medium' as SKANCoarseValue }
     }
   } as ConversionTemplate
 }; 

package/src/datalyr-sdk-expo.ts

@@ -30,6 +30,7 @@ import {
 import { createHttpClient, HttpClient } from './http-client';
 import { createEventQueue, EventQueue } from './event-queue';
 import { attributionManager, AttributionData } from './attribution';
+import { journeyManager } from './journey';
 import { createAutoEventsManager, AutoEventsManager } from './auto-events';
 import { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 import { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
@@ -115,6 +116,24 @@ export class DatalyrSDKExpo {
         await attributionManager.initialize();
       }
 
+      // Initialize journey tracking (for first-touch, last-touch, touchpoints)
+      await journeyManager.initialize();
+
+      // Record initial attribution to journey if this is a new session with attribution
+      const initialAttribution = attributionManager.getAttributionData();
+      if (initialAttribution.utm_source || initialAttribution.fbclid || initialAttribution.gclid || initialAttribution.lyr) {
+        await journeyManager.recordAttribution(this.state.sessionId, {
+          source: initialAttribution.utm_source || initialAttribution.campaign_source,
+          medium: initialAttribution.utm_medium || initialAttribution.campaign_medium,
+          campaign: initialAttribution.utm_campaign || initialAttribution.campaign_name,
+          fbclid: initialAttribution.fbclid,
+          gclid: initialAttribution.gclid,
+          ttclid: initialAttribution.ttclid,
+          clickIdType: initialAttribution.fbclid ? 'fbclid' : initialAttribution.gclid ? 'gclid' : initialAttribution.ttclid ? 'ttclid' : undefined,
+          lyr: initialAttribution.lyr,
+        });
+      }
+
       if (this.state.config.enableAutoEvents) {
         this.autoEventsManager = new AutoEventsManager(
           this.track.bind(this),
@@ -441,8 +460,32 @@ export class DatalyrSDKExpo {
     return this.state.anonymousId;
   }
 
-  getAttributionData(): AttributionData {
-    return attributionManager.getAttributionData();
+  /**
+   * Get detailed attribution data (includes journey tracking data)
+   */
+  getAttributionData(): AttributionData & Record<string, any> {
+    const attribution = attributionManager.getAttributionData();
+    const journeyData = journeyManager.getAttributionData();
+
+    // Merge attribution with journey data
+    return {
+      ...attribution,
+      ...journeyData,
+    };
+  }
+
+  /**
+   * Get journey tracking summary
+   */
+  getJourneySummary() {
+    return journeyManager.getJourneySummary();
+  }
+
+  /**
+   * Get full customer journey (all touchpoints)
+   */
+  getJourney() {
+    return journeyManager.getJourney();
   }
 
   async setAttributionData(data: Partial<AttributionData>): Promise<void> {
@@ -477,6 +520,10 @@ export class DatalyrSDKExpo {
     }
   }
 
+  /**
+   * Track event with automatic SKAdNetwork conversion value encoding
+   * Uses SKAN 4.0 on iOS 16.1+ with coarse values and lock window support
+   */
   async trackWithSKAdNetwork(event: string, properties?: EventData): Promise<void> {
     await this.track(event, properties);
 
@@ -487,13 +534,15 @@ export class DatalyrSDKExpo {
       return;
     }
 
-    const conversionValue = DatalyrSDKExpo.conversionEncoder.encode(event, properties);
+    // Use SKAN 4.0 encoding (includes coarse value and lock window)
+    const result = DatalyrSDKExpo.conversionEncoder.encodeWithSKAN4(event, properties);
 
-    if (conversionValue > 0) {
-      const success = await SKAdNetworkBridge.updateConversionValue(conversionValue);
+    if (result.fineValue > 0 || result.priority > 0) {
+      // Use SKAN 4.0 method (automatically falls back to SKAN 3.0 on older iOS)
+      const success = await SKAdNetworkBridge.updatePostbackConversionValue(result);
 
       if (DatalyrSDKExpo.debugEnabled) {
-        debugLog(`Event: ${event}, Conversion Value: ${conversionValue}, Success: ${success}`, properties);
+        debugLog(`SKAN: event=${event}, fine=${result.fineValue}, coarse=${result.coarseValue}, lock=${result.lockWindow}, success=${success}`, properties);
       }
     }
   }

package/src/datalyr-sdk.ts

@@ -27,10 +27,11 @@ import {
 import { createHttpClient, HttpClient } from './http-client';
 import { createEventQueue, EventQueue } from './event-queue';
 import { attributionManager, AttributionData } from './attribution';
+import { journeyManager } from './journey';
 import { createAutoEventsManager, AutoEventsManager, SessionData } from './auto-events';
 import { ConversionValueEncoder, ConversionTemplates } from './ConversionValueEncoder';
 import { SKAdNetworkBridge } from './native/SKAdNetworkBridge';
-import { metaIntegration, tiktokIntegration, appleSearchAdsIntegration } from './integrations';
+import { metaIntegration, tiktokIntegration, appleSearchAdsIntegration, playInstallReferrerIntegration } from './integrations';
 import { AppleSearchAdsAttribution } from './native/DatalyrNativeBridge';
 
 export class DatalyrSDK {
@@ -124,6 +125,24 @@ export class DatalyrSDK {
         await attributionManager.initialize();
       }
 
+      // Initialize journey tracking (for first-touch, last-touch, touchpoints)
+      await journeyManager.initialize();
+
+      // Record initial attribution to journey if this is a new session with attribution
+      const initialAttribution = attributionManager.getAttributionData();
+      if (initialAttribution.utm_source || initialAttribution.fbclid || initialAttribution.gclid || initialAttribution.lyr) {
+        await journeyManager.recordAttribution(this.state.sessionId, {
+          source: initialAttribution.utm_source || initialAttribution.campaign_source,
+          medium: initialAttribution.utm_medium || initialAttribution.campaign_medium,
+          campaign: initialAttribution.utm_campaign || initialAttribution.campaign_name,
+          fbclid: initialAttribution.fbclid,
+          gclid: initialAttribution.gclid,
+          ttclid: initialAttribution.ttclid,
+          clickIdType: initialAttribution.fbclid ? 'fbclid' : initialAttribution.gclid ? 'gclid' : initialAttribution.ttclid ? 'ttclid' : undefined,
+          lyr: initialAttribution.lyr,
+        });
+      }
+
       // Initialize auto-events manager (asynchronously to avoid blocking)
       if (this.state.config.enableAutoEvents) {
         this.autoEventsManager = new AutoEventsManager(
@@ -185,10 +204,14 @@ export class DatalyrSDK {
       // Initialize Apple Search Ads attribution (iOS only, auto-fetches on init)
       await appleSearchAdsIntegration.initialize(config.debug);
 
+      // Initialize Google Play Install Referrer (Android only)
+      await playInstallReferrerIntegration.initialize();
+
       debugLog('Platform integrations initialized', {
         meta: metaIntegration.isAvailable(),
         tiktok: tiktokIntegration.isAvailable(),
         appleSearchAds: appleSearchAdsIntegration.isAvailable(),
+        playInstallReferrer: playInstallReferrerIntegration.isAvailable(),
       });
 
       // SDK initialized successfully - set state before tracking install event
@@ -490,6 +513,7 @@ export class DatalyrSDK {
     currentUserId?: string;
     queueStats: any;
     attribution: any;
+    journey: any;
   } {
     return {
       initialized: this.state.initialized,
@@ -500,6 +524,7 @@ export class DatalyrSDK {
       currentUserId: this.state.currentUserId,
       queueStats: this.eventQueue.getStats(),
       attribution: attributionManager.getAttributionSummary(),
+      journey: journeyManager.getJourneySummary(),
     };
   }
 
@@ -511,10 +536,31 @@ export class DatalyrSDK {
   }
 
   /**
-   * Get detailed attribution data
+   * Get detailed attribution data (includes journey tracking data)
+   */
+  getAttributionData(): AttributionData & Record<string, any> {
+    const attribution = attributionManager.getAttributionData();
+    const journeyData = journeyManager.getAttributionData();
+
+    // Merge attribution with journey data
+    return {
+      ...attribution,
+      ...journeyData,
+    };
+  }
+
+  /**
+   * Get journey tracking summary
    */
-  getAttributionData(): AttributionData {
-    return attributionManager.getAttributionData();
+  getJourneySummary() {
+    return journeyManager.getJourneySummary();
+  }
+
+  /**
+   * Get full customer journey (all touchpoints)
+   */
+  getJourney() {
+    return journeyManager.getJourney();
   }
 
   /**
@@ -571,15 +617,16 @@ export class DatalyrSDK {
 
   /**
    * Track event with automatic SKAdNetwork conversion value encoding
+   * Uses SKAN 4.0 on iOS 16.1+ with coarse values and lock window support
    */
   async trackWithSKAdNetwork(
-    event: string, 
+    event: string,
     properties?: EventData
   ): Promise<void> {
     // Existing tracking (keep exactly as-is)
     await this.track(event, properties);
 
-    // NEW: Automatic SKAdNetwork encoding
+    // Automatic SKAdNetwork encoding with SKAN 4.0 support
     if (!DatalyrSDK.conversionEncoder) {
       if (DatalyrSDK.debugEnabled) {
         errorLog('SKAdNetwork encoder not initialized. Pass skadTemplate in initialize()');
@@ -587,13 +634,15 @@ export class DatalyrSDK {
       return;
     }
 
-    const conversionValue = DatalyrSDK.conversionEncoder.encode(event, properties);
-    
-    if (conversionValue > 0) {
-      const success = await SKAdNetworkBridge.updateConversionValue(conversionValue);
-      
+    // Use SKAN 4.0 encoding (includes coarse value and lock window)
+    const result = DatalyrSDK.conversionEncoder.encodeWithSKAN4(event, properties);
+
+    if (result.fineValue > 0 || result.priority > 0) {
+      // Use SKAN 4.0 method (automatically falls back to SKAN 3.0 on older iOS)
+      const success = await SKAdNetworkBridge.updatePostbackConversionValue(result);
+
       if (DatalyrSDK.debugEnabled) {
-        debugLog(`Event: ${event}, Conversion Value: ${conversionValue}, Success: ${success}`, properties);
+        debugLog(`SKAN: event=${event}, fine=${result.fineValue}, coarse=${result.coarseValue}, lock=${result.lockWindow}, success=${success}`, properties);
       }
     } else if (DatalyrSDK.debugEnabled) {
       debugLog(`No conversion value generated for event: ${event}`);
@@ -837,11 +886,12 @@ export class DatalyrSDK {
   /**
    * Get platform integration status
    */
-  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean } {
+  getPlatformIntegrationStatus(): { meta: boolean; tiktok: boolean; appleSearchAds: boolean; playInstallReferrer: boolean } {
     return {
       meta: metaIntegration.isAvailable(),
       tiktok: tiktokIntegration.isAvailable(),
       appleSearchAds: appleSearchAdsIntegration.isAvailable(),
+      playInstallReferrer: playInstallReferrerIntegration.isAvailable(),
     };
   }
 
@@ -853,6 +903,15 @@ export class DatalyrSDK {
     return appleSearchAdsIntegration.getAttributionData();
   }
 
+  /**
+   * Get Google Play Install Referrer attribution data (Android only)
+   * Returns referrer data if available, null otherwise
+   */
+  getPlayInstallReferrer(): Record<string, any> | null {
+    const data = playInstallReferrerIntegration.getReferrerData();
+    return data ? playInstallReferrerIntegration.getAttributionData() : null;
+  }
+
   /**
    * Update tracking authorization status on all platform SDKs
    * Call this AFTER the user responds to the ATT permission dialog

package/src/expo.ts

@@ -22,6 +22,10 @@ export * from './types';
 // Export attribution manager
 export { attributionManager } from './attribution';
 
+// Export journey tracking
+export { journeyManager } from './journey';
+export type { TouchAttribution, TouchPoint } from './journey';
+
 // Export auto-events
 export { createAutoEventsManager, AutoEventsManager } from './auto-events';
 

package/src/index.ts

@@ -12,6 +12,8 @@ export { Datalyr };
 // Export types and utilities
 export * from './types';
 export { attributionManager } from './attribution';
+export { journeyManager } from './journey';
+export type { TouchAttribution, TouchPoint } from './journey';
 export { createAutoEventsManager, AutoEventsManager } from './auto-events';
 
 // Re-export utilities for advanced usage

package/src/integrations/index.ts

@@ -1,8 +1,10 @@
 /**
  * Platform SDK Integrations
- * Meta (Facebook), TikTok, and Apple Search Ads SDK wrappers
+ * Meta (Facebook), TikTok, Apple Search Ads, and Google Play Install Referrer SDK wrappers
  */
 
 export { MetaIntegration, metaIntegration } from './meta-integration';
 export { TikTokIntegration, tiktokIntegration } from './tiktok-integration';
 export { AppleSearchAdsIntegration, appleSearchAdsIntegration } from './apple-search-ads-integration';
+export { playInstallReferrerIntegration } from './play-install-referrer';
+export type { PlayInstallReferrer } from './play-install-referrer';

package/src/integrations/meta-integration.ts

@@ -20,14 +20,15 @@ export class MetaIntegration {
 
   /**
    * Initialize Meta SDK with configuration
+   * Supported on both iOS and Android via native modules
    */
   async initialize(config: MetaConfig, debug: boolean = false): Promise<void> {
     this.debug = debug;
     this.config = config;
 
-    // Only available on iOS via native module
-    if (Platform.OS !== 'ios') {
-      this.log('Meta SDK only available on iOS');
+    // Only available on iOS and Android via native modules
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
+      this.log('Meta SDK only available on iOS and Android');
       return;
     }
 

package/src/integrations/play-install-referrer.ts

@@ -0,0 +1,203 @@
+/**
+ * Google Play Install Referrer Integration
+ *
+ * Provides Android install attribution via the Google Play Install Referrer API.
+ * This captures UTM parameters and click IDs passed through Google Play Store.
+ *
+ * How it works:
+ * 1. User clicks ad/link with UTM parameters
+ * 2. Google Play Store stores the referrer URL
+ * 3. On first app launch, SDK retrieves the referrer
+ * 4. Attribution data (utm_source, utm_medium, gclid, etc.) is extracted
+ *
+ * Requirements:
+ * - Android only (returns null on iOS)
+ * - Requires Google Play Install Referrer Library in build.gradle:
+ *   implementation 'com.android.installreferrer:installreferrer:2.2'
+ *
+ * Attribution data captured:
+ * - referrer_url: Full referrer URL from Play Store
+ * - referrer_click_timestamp: When the referrer link was clicked
+ * - install_begin_timestamp: When the install began
+ * - gclid: Google Ads click ID (if present)
+ * - utm_source, utm_medium, utm_campaign, etc.
+ */
+
+import { Platform, NativeModules } from 'react-native';
+import { debugLog, errorLog } from '../utils';
+
+export interface PlayInstallReferrer {
+  // Raw referrer URL from Play Store
+  referrerUrl: string;
+  // Timestamp when the referrer link was clicked (ms)
+  referrerClickTimestamp: number;
+  // Timestamp when the install began (ms)
+  installBeginTimestamp: number;
+  // Timestamp when install was completed (ms)
+  installCompleteTimestamp?: number;
+  // Google Ads click ID
+  gclid?: string;
+  // UTM Parameters
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  // Additional parameters
+  [key: string]: any;
+}
+
+interface PlayInstallReferrerModule {
+  getInstallReferrer(): Promise<PlayInstallReferrer | null>;
+  isAvailable(): Promise<boolean>;
+}
+
+const { DatalyrPlayInstallReferrer } = NativeModules as {
+  DatalyrPlayInstallReferrer?: PlayInstallReferrerModule;
+};
+
+/**
+ * Google Play Install Referrer Integration
+ *
+ * Retrieves install attribution data from Google Play Store.
+ * Only available on Android.
+ */
+class PlayInstallReferrerIntegration {
+  private referrerData: PlayInstallReferrer | null = null;
+  private initialized = false;
+
+  /**
+   * Check if Play Install Referrer is available
+   */
+  isAvailable(): boolean {
+    return Platform.OS === 'android' && !!DatalyrPlayInstallReferrer;
+  }
+
+  /**
+   * Initialize and fetch install referrer data
+   * Should be called once on first app launch
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    if (!this.isAvailable()) {
+      debugLog('[PlayInstallReferrer] Not available (iOS or native module missing)');
+      return;
+    }
+
+    try {
+      this.referrerData = await this.fetchInstallReferrer();
+      this.initialized = true;
+
+      if (this.referrerData) {
+        debugLog('[PlayInstallReferrer] Install referrer fetched:', {
+          utmSource: this.referrerData.utmSource,
+          utmMedium: this.referrerData.utmMedium,
+          hasGclid: !!this.referrerData.gclid,
+        });
+      }
+    } catch (error) {
+      errorLog('[PlayInstallReferrer] Failed to initialize:', error as Error);
+    }
+  }
+
+  /**
+   * Fetch install referrer from Play Store
+   */
+  async fetchInstallReferrer(): Promise<PlayInstallReferrer | null> {
+    if (!this.isAvailable()) {
+      return null;
+    }
+
+    try {
+      const referrer = await DatalyrPlayInstallReferrer!.getInstallReferrer();
+
+      if (!referrer) {
+        return null;
+      }
+
+      // Parse UTM parameters from referrer URL
+      const parsed = this.parseReferrerUrl(referrer.referrerUrl);
+
+      return {
+        ...referrer,
+        ...parsed,
+      };
+    } catch (error) {
+      errorLog('[PlayInstallReferrer] Error fetching referrer:', error as Error);
+      return null;
+    }
+  }
+
+  /**
+   * Parse referrer URL to extract UTM parameters and click IDs
+   */
+  private parseReferrerUrl(referrerUrl: string): Partial<PlayInstallReferrer> {
+    const params: Partial<PlayInstallReferrer> = {};
+
+    if (!referrerUrl) return params;
+
+    try {
+      // Referrer URL is URL-encoded, decode it first
+      const decoded = decodeURIComponent(referrerUrl);
+      const searchParams = new URLSearchParams(decoded);
+
+      // Extract UTM parameters
+      params.utmSource = searchParams.get('utm_source') || undefined;
+      params.utmMedium = searchParams.get('utm_medium') || undefined;
+      params.utmCampaign = searchParams.get('utm_campaign') || undefined;
+      params.utmTerm = searchParams.get('utm_term') || undefined;
+      params.utmContent = searchParams.get('utm_content') || undefined;
+
+      // Extract click IDs
+      params.gclid = searchParams.get('gclid') || undefined;
+
+      // Store any additional parameters
+      searchParams.forEach((value, key) => {
+        if (!key.startsWith('utm_') && key !== 'gclid') {
+          params[key] = value;
+        }
+      });
+
+      debugLog('[PlayInstallReferrer] Parsed referrer URL:', params);
+    } catch (error) {
+      errorLog('[PlayInstallReferrer] Error parsing referrer URL:', error as Error);
+    }
+
+    return params;
+  }
+
+  /**
+   * Get cached install referrer data
+   */
+  getReferrerData(): PlayInstallReferrer | null {
+    return this.referrerData;
+  }
+
+  /**
+   * Get attribution data in standard format
+   */
+  getAttributionData(): Record<string, any> {
+    if (!this.referrerData) return {};
+
+    return {
+      // Install referrer specific
+      install_referrer_url: this.referrerData.referrerUrl,
+      referrer_click_timestamp: this.referrerData.referrerClickTimestamp,
+      install_begin_timestamp: this.referrerData.installBeginTimestamp,
+
+      // Standard attribution fields
+      gclid: this.referrerData.gclid,
+      utm_source: this.referrerData.utmSource,
+      utm_medium: this.referrerData.utmMedium,
+      utm_campaign: this.referrerData.utmCampaign,
+      utm_term: this.referrerData.utmTerm,
+      utm_content: this.referrerData.utmContent,
+
+      // Source indicators
+      attribution_source: 'play_install_referrer',
+    };
+  }
+}
+
+export const playInstallReferrerIntegration = new PlayInstallReferrerIntegration();