@datalyr/react-native 1.2.1 → 1.3.0

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();

package/src/native/DatalyrNativeBridge.ts

@@ -1,12 +1,16 @@
 /**
- * Native Bridge for Meta, TikTok, and Apple Search Ads
+ * Native Bridge for Meta, TikTok, Apple Search Ads, and Play Install Referrer
  * Uses bundled native modules instead of separate npm packages
+ *
+ * Supported Platforms:
+ * - iOS: Meta SDK, TikTok SDK, Apple Search Ads (AdServices)
+ * - Android: Meta SDK, TikTok SDK, Play Install Referrer
  */
 
 import { NativeModules, Platform } from 'react-native';
 
 /**
- * Apple Search Ads attribution data returned from AdServices API
+ * Apple Search Ads attribution data returned from AdServices API (iOS only)
  */
 export interface AppleSearchAdsAttribution {
   attribution: boolean;
@@ -23,6 +27,25 @@ export interface AppleSearchAdsAttribution {
   countryOrRegion?: string;
 }
 
+/**
+ * Play Install Referrer data (Android only)
+ */
+export interface PlayInstallReferrerData {
+  referrerUrl: string;
+  referrerClickTimestamp: number;
+  installBeginTimestamp: number;
+  installCompleteTimestamp?: number;
+  gclid?: string;
+  fbclid?: string;
+  ttclid?: string;
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+  referrer?: string;
+}
+
 interface DatalyrNativeModule {
   // Meta SDK Methods
   initializeMetaSDK(
@@ -66,16 +89,29 @@ interface DatalyrNativeModule {
   logoutTikTok(): Promise<boolean>;
   updateTikTokTrackingAuthorization(enabled: boolean): Promise<boolean>;
 
-  // Apple Search Ads Methods
+  // Apple Search Ads Methods (iOS only)
   getAppleSearchAdsAttribution(): Promise<AppleSearchAdsAttribution | null>;
 
   // SDK Availability
-  getSDKAvailability(): Promise<{ meta: boolean; tiktok: boolean; appleSearchAds: boolean }>;
+  getSDKAvailability(): Promise<{
+    meta: boolean;
+    tiktok: boolean;
+    appleSearchAds: boolean;
+    playInstallReferrer?: boolean;
+  }>;
 }
 
-// Native module is only available on iOS
-const DatalyrNative: DatalyrNativeModule | null =
-  Platform.OS === 'ios' ? NativeModules.DatalyrNative : null;
+interface PlayInstallReferrerModule {
+  isAvailable(): Promise<boolean>;
+  getInstallReferrer(): Promise<PlayInstallReferrerData | null>;
+}
+
+// Native modules - available on both iOS and Android
+const DatalyrNative: DatalyrNativeModule | null = NativeModules.DatalyrNative ?? null;
+
+// Play Install Referrer - Android only
+const DatalyrPlayInstallReferrer: PlayInstallReferrerModule | null =
+  Platform.OS === 'android' ? NativeModules.DatalyrPlayInstallReferrer : null;
 
 /**
  * Check if native module is available
@@ -85,21 +121,34 @@ export const isNativeModuleAvailable = (): boolean => {
 };
 
 /**
- * Get SDK availability status
+ * Get SDK availability status for all platforms
  */
 export const getSDKAvailability = async (): Promise<{
   meta: boolean;
   tiktok: boolean;
   appleSearchAds: boolean;
+  playInstallReferrer: boolean;
 }> => {
+  const defaultAvailability = {
+    meta: false,
+    tiktok: false,
+    appleSearchAds: false,
+    playInstallReferrer: false,
+  };
+
   if (!DatalyrNative) {
-    return { meta: false, tiktok: false, appleSearchAds: false };
+    return defaultAvailability;
   }
 
   try {
-    return await DatalyrNative.getSDKAvailability();
+    const result = await DatalyrNative.getSDKAvailability();
+    return {
+      ...defaultAvailability,
+      ...result,
+      playInstallReferrer: Platform.OS === 'android' && DatalyrPlayInstallReferrer !== null,
+    };
   } catch {
-    return { meta: false, tiktok: false, appleSearchAds: false };
+    return defaultAvailability;
   }
 };
 
@@ -292,7 +341,7 @@ export const TikTokNativeBridge = {
   },
 };
 
-// MARK: - Apple Search Ads Bridge
+// MARK: - Apple Search Ads Bridge (iOS only)
 
 export const AppleSearchAdsNativeBridge = {
   /**
@@ -301,7 +350,7 @@ export const AppleSearchAdsNativeBridge = {
    * Returns null if user didn't come from Apple Search Ads or on older iOS
    */
   async getAttribution(): Promise<AppleSearchAdsAttribution | null> {
-    if (!DatalyrNative) return null;
+    if (!DatalyrNative || Platform.OS !== 'ios') return null;
 
     try {
       return await DatalyrNative.getAppleSearchAdsAttribution();
@@ -311,3 +360,40 @@ export const AppleSearchAdsNativeBridge = {
     }
   },
 };
+
+// MARK: - Play Install Referrer Bridge (Android only)
+
+export const PlayInstallReferrerNativeBridge = {
+  /**
+   * Check if Play Install Referrer is available
+   * Only available on Android with Google Play Services
+   */
+  async isAvailable(): Promise<boolean> {
+    if (!DatalyrPlayInstallReferrer || Platform.OS !== 'android') return false;
+
+    try {
+      return await DatalyrPlayInstallReferrer.isAvailable();
+    } catch {
+      return false;
+    }
+  },
+
+  /**
+   * Get install referrer data from Google Play
+   *
+   * Returns UTM parameters, click IDs (gclid, fbclid, ttclid), and timestamps
+   * from the Google Play Store referrer.
+   *
+   * Call this on first app launch to capture install attribution.
+   */
+  async getInstallReferrer(): Promise<PlayInstallReferrerData | null> {
+    if (!DatalyrPlayInstallReferrer || Platform.OS !== 'android') return null;
+
+    try {
+      return await DatalyrPlayInstallReferrer.getInstallReferrer();
+    } catch (error) {
+      console.error('[Datalyr/PlayInstallReferrer] Get referrer failed:', error);
+      return null;
+    }
+  },
+};

package/src/native/SKAdNetworkBridge.ts

@@ -1,14 +1,37 @@
 import { NativeModules, Platform } from 'react-native';
 
+// SKAN 4.0 coarse value type
+export type SKANCoarseValue = 'low' | 'medium' | 'high';
+
+// SKAN 4.0 conversion result
+export interface SKANConversionResult {
+  fineValue: number;      // 0-63
+  coarseValue: SKANCoarseValue;
+  lockWindow: boolean;
+  priority: number;
+}
+
 interface SKAdNetworkModule {
   updateConversionValue(value: number): Promise<boolean>;
+  updatePostbackConversionValue(
+    fineValue: number,
+    coarseValue: string,
+    lockWindow: boolean
+  ): Promise<boolean>;
+  isSKAN4Available(): Promise<boolean>;
 }
 
-const { DatalyrSKAdNetwork } = NativeModules as { 
-  DatalyrSKAdNetwork?: SKAdNetworkModule 
+const { DatalyrSKAdNetwork } = NativeModules as {
+  DatalyrSKAdNetwork?: SKAdNetworkModule
 };
 
 export class SKAdNetworkBridge {
+  private static _isSKAN4Available: boolean | null = null;
+
+  /**
+   * SKAN 3.0 - Update conversion value (0-63)
+   * @deprecated Use updatePostbackConversionValue for iOS 16.1+
+   */
   static async updateConversionValue(value: number): Promise<boolean> {
     if (Platform.OS !== 'ios') {
       return false; // Android doesn't support SKAdNetwork
@@ -29,6 +52,67 @@ export class SKAdNetworkBridge {
     }
   }
 
+  /**
+   * SKAN 4.0 - Update postback conversion value with coarse value and lock window
+   * Falls back to SKAN 3.0 on iOS 14.0-16.0
+   */
+  static async updatePostbackConversionValue(
+    result: SKANConversionResult
+  ): Promise<boolean> {
+    if (Platform.OS !== 'ios') {
+      return false; // Android doesn't support SKAdNetwork
+    }
+
+    if (!DatalyrSKAdNetwork) {
+      console.warn('[Datalyr] SKAdNetwork native module not found. Ensure native bridge is properly configured.');
+      return false;
+    }
+
+    try {
+      const success = await DatalyrSKAdNetwork.updatePostbackConversionValue(
+        result.fineValue,
+        result.coarseValue,
+        result.lockWindow
+      );
+
+      const isSKAN4 = await this.isSKAN4Available();
+      if (isSKAN4) {
+        console.log(`[Datalyr] SKAN 4.0 postback updated: fineValue=${result.fineValue}, coarseValue=${result.coarseValue}, lockWindow=${result.lockWindow}`);
+      } else {
+        console.log(`[Datalyr] SKAN 3.0 fallback: conversionValue=${result.fineValue}`);
+      }
+
+      return success;
+    } catch (error) {
+      console.warn('[Datalyr] Failed to update SKAdNetwork postback conversion value:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if SKAN 4.0 is available (iOS 16.1+)
+   */
+  static async isSKAN4Available(): Promise<boolean> {
+    if (Platform.OS !== 'ios') {
+      return false;
+    }
+
+    if (this._isSKAN4Available !== null) {
+      return this._isSKAN4Available;
+    }
+
+    if (!DatalyrSKAdNetwork?.isSKAN4Available) {
+      return false;
+    }
+
+    try {
+      this._isSKAN4Available = await DatalyrSKAdNetwork.isSKAN4Available();
+      return this._isSKAN4Available;
+    } catch {
+      return false;
+    }
+  }
+
   static isAvailable(): boolean {
     return Platform.OS === 'ios' && !!DatalyrSKAdNetwork;
   }