@datalyr/react-native 1.2.1 → 1.3.0

package/lib/index.d.ts

@@ -3,6 +3,8 @@ export declare const datalyr: DatalyrSDK;
 export { Datalyr };
 export * from './types';
 export { attributionManager } from './attribution';
+export { journeyManager } from './journey';
+export type { TouchAttribution, TouchPoint } from './journey';
 export { createAutoEventsManager, AutoEventsManager } from './auto-events';
 export * from './utils';
 export * from './http-client';

package/lib/index.js

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

package/lib/integrations/index.d.ts

@@ -1,7 +1,9 @@
 /**
  * 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/lib/integrations/index.js

@@ -1,7 +1,8 @@
 /**
  * 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';

package/lib/integrations/meta-integration.d.ts

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

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,74 @@
+/**
+ * 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.
+ */
+export interface PlayInstallReferrer {
+    referrerUrl: string;
+    referrerClickTimestamp: number;
+    installBeginTimestamp: number;
+    installCompleteTimestamp?: number;
+    gclid?: 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,156 @@
+/**
+ * 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';
+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,
+                });
+            }
+        }
+        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
+            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);
+        }
+        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,
+            // 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();

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;