@datalyr/react-native 1.2.1 → 1.3.1

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

@@ -0,0 +1,218 @@
+/**
+ * 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 (standard)
+ * - gbraid: Google Ads privacy-safe click ID (iOS App campaigns)
+ * - wbraid: Google Ads privacy-safe click ID (Web-to-App campaigns)
+ * - 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;
+  // Google Ads privacy-safe click IDs (iOS App campaigns)
+  gbraid?: string;
+  // Google Ads privacy-safe click IDs (Web-to-App campaigns)
+  wbraid?: 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,
+          hasGbraid: !!this.referrerData.gbraid,
+          hasWbraid: !!this.referrerData.wbraid,
+        });
+      }
+    } 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 (gclid, gbraid, wbraid)
+      params.gclid = searchParams.get('gclid') || undefined;
+      params.gbraid = searchParams.get('gbraid') || undefined;
+      params.wbraid = searchParams.get('wbraid') || undefined;
+
+      // Store any additional parameters
+      const knownParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'gclid', 'gbraid', 'wbraid'];
+      searchParams.forEach((value, key) => {
+        if (!knownParams.includes(key) && !key.startsWith('utm_')) {
+          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,
+
+      // Google Ads click IDs (gclid is standard, gbraid/wbraid are privacy-safe alternatives)
+      gclid: this.referrerData.gclid,
+      gbraid: this.referrerData.gbraid,
+      wbraid: this.referrerData.wbraid,
+
+      // UTM parameters
+      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();

package/src/integrations/tiktok-integration.ts

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

package/src/journey.ts

@@ -0,0 +1,338 @@
+/**
+ * Journey Tracking Module for React Native
+ * Mirrors the Web SDK's journey tracking capabilities:
+ * - First-touch attribution with 90-day expiration
+ * - Last-touch attribution with 90-day expiration
+ * - Up to 30 touchpoints stored
+ */
+
+import { Storage, debugLog, errorLog } from './utils';
+
+// Storage keys for journey data
+const JOURNEY_STORAGE_KEYS = {
+  FIRST_TOUCH: '@datalyr/first_touch',
+  LAST_TOUCH: '@datalyr/last_touch',
+  JOURNEY: '@datalyr/journey',
+};
+
+// 90-day attribution window (matching web SDK)
+const ATTRIBUTION_WINDOW_MS = 90 * 24 * 60 * 60 * 1000;
+
+// Maximum touchpoints to store
+const MAX_TOUCHPOINTS = 30;
+
+/**
+ * Attribution data for a touch
+ */
+export interface TouchAttribution {
+  timestamp: number;
+  expires_at: number;
+  captured_at: number;
+
+  // Source attribution
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  term?: string;
+  content?: string;
+
+  // Click IDs
+  clickId?: string;
+  clickIdType?: string;
+  fbclid?: string;
+  gclid?: string;
+  ttclid?: string;
+  gbraid?: string;
+  wbraid?: string;
+
+  // LYR tag
+  lyr?: string;
+
+  // Context
+  landingPage?: string;
+  referrer?: string;
+}
+
+/**
+ * A single touchpoint in the customer journey
+ */
+export interface TouchPoint {
+  timestamp: number;
+  sessionId: string;
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  clickIdType?: string;
+}
+
+/**
+ * Journey manager for tracking customer touchpoints
+ */
+export class JourneyManager {
+  private firstTouch: TouchAttribution | null = null;
+  private lastTouch: TouchAttribution | null = null;
+  private journey: TouchPoint[] = [];
+  private initialized = false;
+
+  /**
+   * Initialize journey tracking by loading persisted data
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    try {
+      debugLog('Initializing journey manager...');
+
+      // Load first touch
+      const savedFirstTouch = await Storage.getItem<TouchAttribution>(JOURNEY_STORAGE_KEYS.FIRST_TOUCH);
+      if (savedFirstTouch && !this.isExpired(savedFirstTouch)) {
+        this.firstTouch = savedFirstTouch;
+      } else if (savedFirstTouch) {
+        // Expired, clear it
+        await Storage.removeItem(JOURNEY_STORAGE_KEYS.FIRST_TOUCH);
+      }
+
+      // Load last touch
+      const savedLastTouch = await Storage.getItem<TouchAttribution>(JOURNEY_STORAGE_KEYS.LAST_TOUCH);
+      if (savedLastTouch && !this.isExpired(savedLastTouch)) {
+        this.lastTouch = savedLastTouch;
+      } else if (savedLastTouch) {
+        await Storage.removeItem(JOURNEY_STORAGE_KEYS.LAST_TOUCH);
+      }
+
+      // Load journey
+      const savedJourney = await Storage.getItem<TouchPoint[]>(JOURNEY_STORAGE_KEYS.JOURNEY);
+      if (savedJourney) {
+        this.journey = savedJourney;
+      }
+
+      this.initialized = true;
+      debugLog('Journey manager initialized', {
+        hasFirstTouch: !!this.firstTouch,
+        hasLastTouch: !!this.lastTouch,
+        touchpointCount: this.journey.length,
+      });
+    } catch (error) {
+      errorLog('Failed to initialize journey manager:', error as Error);
+    }
+  }
+
+  /**
+   * Check if attribution has expired
+   */
+  private isExpired(attribution: TouchAttribution): boolean {
+    return Date.now() >= attribution.expires_at;
+  }
+
+  /**
+   * Store first touch attribution (only if not already set or expired)
+   */
+  async storeFirstTouch(attribution: Partial<TouchAttribution>): Promise<void> {
+    try {
+      // Only store if no valid first touch exists
+      if (this.firstTouch && !this.isExpired(this.firstTouch)) {
+        debugLog('First touch already exists, not overwriting');
+        return;
+      }
+
+      const now = Date.now();
+      this.firstTouch = {
+        ...attribution,
+        timestamp: attribution.timestamp || now,
+        captured_at: now,
+        expires_at: now + ATTRIBUTION_WINDOW_MS,
+      } as TouchAttribution;
+
+      await Storage.setItem(JOURNEY_STORAGE_KEYS.FIRST_TOUCH, this.firstTouch);
+      debugLog('First touch stored:', this.firstTouch);
+    } catch (error) {
+      errorLog('Failed to store first touch:', error as Error);
+    }
+  }
+
+  /**
+   * Get first touch attribution (null if expired)
+   */
+  getFirstTouch(): TouchAttribution | null {
+    if (this.firstTouch && this.isExpired(this.firstTouch)) {
+      this.firstTouch = null;
+      Storage.removeItem(JOURNEY_STORAGE_KEYS.FIRST_TOUCH).catch(() => {});
+    }
+    return this.firstTouch;
+  }
+
+  /**
+   * Store last touch attribution (always updates)
+   */
+  async storeLastTouch(attribution: Partial<TouchAttribution>): Promise<void> {
+    try {
+      const now = Date.now();
+      this.lastTouch = {
+        ...attribution,
+        timestamp: attribution.timestamp || now,
+        captured_at: now,
+        expires_at: now + ATTRIBUTION_WINDOW_MS,
+      } as TouchAttribution;
+
+      await Storage.setItem(JOURNEY_STORAGE_KEYS.LAST_TOUCH, this.lastTouch);
+      debugLog('Last touch stored:', this.lastTouch);
+    } catch (error) {
+      errorLog('Failed to store last touch:', error as Error);
+    }
+  }
+
+  /**
+   * Get last touch attribution (null if expired)
+   */
+  getLastTouch(): TouchAttribution | null {
+    if (this.lastTouch && this.isExpired(this.lastTouch)) {
+      this.lastTouch = null;
+      Storage.removeItem(JOURNEY_STORAGE_KEYS.LAST_TOUCH).catch(() => {});
+    }
+    return this.lastTouch;
+  }
+
+  /**
+   * Add a touchpoint to the customer journey
+   */
+  async addTouchpoint(sessionId: string, attribution: Partial<TouchAttribution>): Promise<void> {
+    try {
+      const touchpoint: TouchPoint = {
+        timestamp: Date.now(),
+        sessionId,
+        source: attribution.source,
+        medium: attribution.medium,
+        campaign: attribution.campaign,
+        clickIdType: attribution.clickIdType,
+      };
+
+      this.journey.push(touchpoint);
+
+      // Keep only last MAX_TOUCHPOINTS
+      if (this.journey.length > MAX_TOUCHPOINTS) {
+        this.journey = this.journey.slice(-MAX_TOUCHPOINTS);
+      }
+
+      await Storage.setItem(JOURNEY_STORAGE_KEYS.JOURNEY, this.journey);
+      debugLog('Touchpoint added, total:', this.journey.length);
+    } catch (error) {
+      errorLog('Failed to add touchpoint:', error as Error);
+    }
+  }
+
+  /**
+   * Get customer journey (all touchpoints)
+   */
+  getJourney(): TouchPoint[] {
+    return [...this.journey];
+  }
+
+  /**
+   * Record attribution from a deep link or install
+   * Updates first-touch (if not set), last-touch, and adds touchpoint
+   */
+  async recordAttribution(sessionId: string, attribution: Partial<TouchAttribution>): Promise<void> {
+    // Only process if we have meaningful attribution data
+    const hasAttribution = attribution.source || attribution.clickId || attribution.campaign || attribution.lyr;
+
+    if (!hasAttribution) {
+      debugLog('No attribution data to record');
+      return;
+    }
+
+    // Store first touch if not set
+    if (!this.getFirstTouch()) {
+      await this.storeFirstTouch(attribution);
+    }
+
+    // Always update last touch
+    await this.storeLastTouch(attribution);
+
+    // Add touchpoint
+    await this.addTouchpoint(sessionId, attribution);
+  }
+
+  /**
+   * Get attribution data for events (mirrors Web SDK format)
+   */
+  getAttributionData(): Record<string, any> {
+    const firstTouch = this.getFirstTouch();
+    const lastTouch = this.getLastTouch();
+    const journey = this.getJourney();
+
+    return {
+      // First touch (with snake_case and camelCase aliases)
+      first_touch_source: firstTouch?.source,
+      first_touch_medium: firstTouch?.medium,
+      first_touch_campaign: firstTouch?.campaign,
+      first_touch_timestamp: firstTouch?.timestamp,
+      firstTouchSource: firstTouch?.source,
+      firstTouchMedium: firstTouch?.medium,
+      firstTouchCampaign: firstTouch?.campaign,
+
+      // Last touch
+      last_touch_source: lastTouch?.source,
+      last_touch_medium: lastTouch?.medium,
+      last_touch_campaign: lastTouch?.campaign,
+      last_touch_timestamp: lastTouch?.timestamp,
+      lastTouchSource: lastTouch?.source,
+      lastTouchMedium: lastTouch?.medium,
+      lastTouchCampaign: lastTouch?.campaign,
+
+      // Journey metrics
+      touchpoint_count: journey.length,
+      touchpointCount: journey.length,
+      days_since_first_touch: firstTouch?.timestamp
+        ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+        : 0,
+      daysSinceFirstTouch: firstTouch?.timestamp
+        ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+        : 0,
+    };
+  }
+
+  /**
+   * Clear all journey data (for testing/reset)
+   */
+  async clearJourney(): Promise<void> {
+    this.firstTouch = null;
+    this.lastTouch = null;
+    this.journey = [];
+
+    await Promise.all([
+      Storage.removeItem(JOURNEY_STORAGE_KEYS.FIRST_TOUCH),
+      Storage.removeItem(JOURNEY_STORAGE_KEYS.LAST_TOUCH),
+      Storage.removeItem(JOURNEY_STORAGE_KEYS.JOURNEY),
+    ]);
+
+    debugLog('Journey data cleared');
+  }
+
+  /**
+   * Get journey summary for debugging
+   */
+  getJourneySummary(): {
+    hasFirstTouch: boolean;
+    hasLastTouch: boolean;
+    touchpointCount: number;
+    daysSinceFirstTouch: number;
+    sources: string[];
+  } {
+    const firstTouch = this.getFirstTouch();
+    const journey = this.getJourney();
+    const sources = [...new Set(journey.map(t => t.source).filter(Boolean))] as string[];
+
+    return {
+      hasFirstTouch: !!firstTouch,
+      hasLastTouch: !!this.getLastTouch(),
+      touchpointCount: journey.length,
+      daysSinceFirstTouch: firstTouch?.timestamp
+        ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+        : 0,
+      sources,
+    };
+  }
+}
+
+// Export singleton instance
+export const journeyManager = new JourneyManager();