@datalyr/react-native 1.2.1 → 1.3.1

package/lib/integrations/meta-integration.js

@@ -18,14 +18,15 @@ export class MetaIntegration {
     }
     /**
      * Initialize Meta SDK with configuration
+     * Supported on both iOS and Android via native modules
      */
     async initialize(config, debug = false) {
         var _a;
         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;
         }
         this.available = isNativeModuleAvailable();

package/lib/integrations/play-install-referrer.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+export interface PlayInstallReferrer {
+    referrerUrl: string;
+    referrerClickTimestamp: number;
+    installBeginTimestamp: number;
+    installCompleteTimestamp?: number;
+    gclid?: string;
+    gbraid?: string;
+    wbraid?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmTerm?: string;
+    utmContent?: string;
+    [key: string]: any;
+}
+/**
+ * Google Play Install Referrer Integration
+ *
+ * Retrieves install attribution data from Google Play Store.
+ * Only available on Android.
+ */
+declare class PlayInstallReferrerIntegration {
+    private referrerData;
+    private initialized;
+    /**
+     * Check if Play Install Referrer is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Initialize and fetch install referrer data
+     * Should be called once on first app launch
+     */
+    initialize(): Promise<void>;
+    /**
+     * Fetch install referrer from Play Store
+     */
+    fetchInstallReferrer(): Promise<PlayInstallReferrer | null>;
+    /**
+     * Parse referrer URL to extract UTM parameters and click IDs
+     */
+    private parseReferrerUrl;
+    /**
+     * Get cached install referrer data
+     */
+    getReferrerData(): PlayInstallReferrer | null;
+    /**
+     * Get attribution data in standard format
+     */
+    getAttributionData(): Record<string, any>;
+}
+export declare const playInstallReferrerIntegration: PlayInstallReferrerIntegration;
+export {};

package/lib/integrations/play-install-referrer.js

@@ -0,0 +1,166 @@
+/**
+ * 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';
+const { DatalyrPlayInstallReferrer } = NativeModules;
+/**
+ * Google Play Install Referrer Integration
+ *
+ * Retrieves install attribution data from Google Play Store.
+ * Only available on Android.
+ */
+class PlayInstallReferrerIntegration {
+    constructor() {
+        this.referrerData = null;
+        this.initialized = false;
+    }
+    /**
+     * Check if Play Install Referrer is available
+     */
+    isAvailable() {
+        return Platform.OS === 'android' && !!DatalyrPlayInstallReferrer;
+    }
+    /**
+     * Initialize and fetch install referrer data
+     * Should be called once on first app launch
+     */
+    async initialize() {
+        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);
+        }
+    }
+    /**
+     * Fetch install referrer from Play Store
+     */
+    async fetchInstallReferrer() {
+        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);
+            return null;
+        }
+    }
+    /**
+     * Parse referrer URL to extract UTM parameters and click IDs
+     */
+    parseReferrerUrl(referrerUrl) {
+        const params = {};
+        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);
+        }
+        return params;
+    }
+    /**
+     * Get cached install referrer data
+     */
+    getReferrerData() {
+        return this.referrerData;
+    }
+    /**
+     * Get attribution data in standard format
+     */
+    getAttributionData() {
+        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/lib/integrations/tiktok-integration.d.ts

@@ -14,6 +14,7 @@ export declare class TikTokIntegration {
     private debug;
     /**
      * Initialize TikTok SDK with configuration
+     * Supported on both iOS and Android via native modules
      */
     initialize(config: TikTokConfig, debug?: boolean): Promise<void>;
     /**

package/lib/integrations/tiktok-integration.js

@@ -41,13 +41,14 @@ export class TikTokIntegration {
     }
     /**
      * Initialize TikTok SDK with configuration
+     * Supported on both iOS and Android via native modules
      */
     async initialize(config, debug = false) {
         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;
         }
         this.available = isNativeModuleAvailable();

package/lib/journey.d.ts

@@ -0,0 +1,106 @@
+/**
+ * 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
+ */
+/**
+ * Attribution data for a touch
+ */
+export interface TouchAttribution {
+    timestamp: number;
+    expires_at: number;
+    captured_at: number;
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+    clickId?: string;
+    clickIdType?: string;
+    fbclid?: string;
+    gclid?: string;
+    ttclid?: string;
+    gbraid?: string;
+    wbraid?: string;
+    lyr?: string;
+    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 declare class JourneyManager {
+    private firstTouch;
+    private lastTouch;
+    private journey;
+    private initialized;
+    /**
+     * Initialize journey tracking by loading persisted data
+     */
+    initialize(): Promise<void>;
+    /**
+     * Check if attribution has expired
+     */
+    private isExpired;
+    /**
+     * Store first touch attribution (only if not already set or expired)
+     */
+    storeFirstTouch(attribution: Partial<TouchAttribution>): Promise<void>;
+    /**
+     * Get first touch attribution (null if expired)
+     */
+    getFirstTouch(): TouchAttribution | null;
+    /**
+     * Store last touch attribution (always updates)
+     */
+    storeLastTouch(attribution: Partial<TouchAttribution>): Promise<void>;
+    /**
+     * Get last touch attribution (null if expired)
+     */
+    getLastTouch(): TouchAttribution | null;
+    /**
+     * Add a touchpoint to the customer journey
+     */
+    addTouchpoint(sessionId: string, attribution: Partial<TouchAttribution>): Promise<void>;
+    /**
+     * Get customer journey (all touchpoints)
+     */
+    getJourney(): TouchPoint[];
+    /**
+     * Record attribution from a deep link or install
+     * Updates first-touch (if not set), last-touch, and adds touchpoint
+     */
+    recordAttribution(sessionId: string, attribution: Partial<TouchAttribution>): Promise<void>;
+    /**
+     * Get attribution data for events (mirrors Web SDK format)
+     */
+    getAttributionData(): Record<string, any>;
+    /**
+     * Clear all journey data (for testing/reset)
+     */
+    clearJourney(): Promise<void>;
+    /**
+     * Get journey summary for debugging
+     */
+    getJourneySummary(): {
+        hasFirstTouch: boolean;
+        hasLastTouch: boolean;
+        touchpointCount: number;
+        daysSinceFirstTouch: number;
+        sources: string[];
+    };
+}
+export declare const journeyManager: JourneyManager;

package/lib/journey.js

@@ -0,0 +1,258 @@
+/**
+ * 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;
+/**
+ * Journey manager for tracking customer touchpoints
+ */
+export class JourneyManager {
+    constructor() {
+        this.firstTouch = null;
+        this.lastTouch = null;
+        this.journey = [];
+        this.initialized = false;
+    }
+    /**
+     * Initialize journey tracking by loading persisted data
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        try {
+            debugLog('Initializing journey manager...');
+            // Load first touch
+            const savedFirstTouch = await Storage.getItem(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(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(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);
+        }
+    }
+    /**
+     * Check if attribution has expired
+     */
+    isExpired(attribution) {
+        return Date.now() >= attribution.expires_at;
+    }
+    /**
+     * Store first touch attribution (only if not already set or expired)
+     */
+    async storeFirstTouch(attribution) {
+        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,
+            };
+            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);
+        }
+    }
+    /**
+     * Get first touch attribution (null if expired)
+     */
+    getFirstTouch() {
+        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) {
+        try {
+            const now = Date.now();
+            this.lastTouch = {
+                ...attribution,
+                timestamp: attribution.timestamp || now,
+                captured_at: now,
+                expires_at: now + ATTRIBUTION_WINDOW_MS,
+            };
+            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);
+        }
+    }
+    /**
+     * Get last touch attribution (null if expired)
+     */
+    getLastTouch() {
+        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, attribution) {
+        try {
+            const 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);
+        }
+    }
+    /**
+     * Get customer journey (all touchpoints)
+     */
+    getJourney() {
+        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, attribution) {
+        // 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() {
+        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 === null || firstTouch === void 0 ? void 0 : firstTouch.source,
+            first_touch_medium: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.medium,
+            first_touch_campaign: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.campaign,
+            first_touch_timestamp: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.timestamp,
+            firstTouchSource: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.source,
+            firstTouchMedium: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.medium,
+            firstTouchCampaign: firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.campaign,
+            // Last touch
+            last_touch_source: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.source,
+            last_touch_medium: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.medium,
+            last_touch_campaign: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.campaign,
+            last_touch_timestamp: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.timestamp,
+            lastTouchSource: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.source,
+            lastTouchMedium: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.medium,
+            lastTouchCampaign: lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.campaign,
+            // Journey metrics
+            touchpoint_count: journey.length,
+            touchpointCount: journey.length,
+            days_since_first_touch: (firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.timestamp)
+                ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+                : 0,
+            daysSinceFirstTouch: (firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.timestamp)
+                ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+                : 0,
+        };
+    }
+    /**
+     * Clear all journey data (for testing/reset)
+     */
+    async clearJourney() {
+        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() {
+        const firstTouch = this.getFirstTouch();
+        const journey = this.getJourney();
+        const sources = [...new Set(journey.map(t => t.source).filter(Boolean))];
+        return {
+            hasFirstTouch: !!firstTouch,
+            hasLastTouch: !!this.getLastTouch(),
+            touchpointCount: journey.length,
+            daysSinceFirstTouch: (firstTouch === null || firstTouch === void 0 ? void 0 : firstTouch.timestamp)
+                ? Math.floor((Date.now() - firstTouch.timestamp) / 86400000)
+                : 0,
+            sources,
+        };
+    }
+}
+// Export singleton instance
+export const journeyManager = new JourneyManager();