@datalyr/react-native 1.4.9 → 1.5.0

package/README.md

@@ -19,6 +19,7 @@ Mobile analytics and attribution SDK for React Native and Expo. Track events, id
 - [Attribution](#attribution)
   - [Automatic Capture](#automatic-capture)
   - [Deferred Deep Links](#deferred-deep-links)
+  - [Web-to-App Attribution](#web-to-app-attribution)
 - [Event Queue](#event-queue)
 - [Auto Events](#auto-events)
 - [SKAdNetwork](#skadnetwork)
@@ -356,6 +357,23 @@ if (deferred) {
 }
 ```
 
+### Web-to-App Attribution
+
+Automatically recover attribution from a web prelander when users install the app from an ad.
+
+**How it works:**
+- **Android**: Attribution params are passed through the Play Store `referrer` URL parameter (set by the web SDK's `trackAppDownloadClick()`). The mobile SDK reads these via the Play Install Referrer API — deterministic, ~95% accuracy.
+- **iOS**: On first install, the SDK calls the Datalyr API to match the device's IP against recent `$app_download_click` web events within 24 hours — ~90%+ accuracy for immediate installs.
+
+No additional mobile code is needed. Attribution is recovered automatically during `initialize()` on first install, before the `app_install` event fires.
+
+After a match, the SDK:
+1. Merges web attribution (click IDs, UTMs, cookies) into the mobile session
+2. Tracks a `$web_attribution_matched` event for analytics
+3. All subsequent events (including purchases) carry the matched attribution
+
+**Fallback:** If IP matching misses (e.g., VPN toggle during install), email-based attribution is still recovered when `identify()` is called with the user's email.
+
 ### Manual Attribution
 
 Set attribution programmatically:

package/lib/datalyr-sdk.d.ts

@@ -34,6 +34,13 @@ export declare class DatalyrSDK {
      * Called automatically during identify() if email is provided
      */
     private fetchAndMergeWebAttribution;
+    /**
+     * Fetch deferred web attribution on first app install.
+     * Uses IP-based matching (iOS) or Play Store referrer (Android) to recover
+     * attribution data (fbclid, utm_*, etc.) from a prelander web visit.
+     * Called automatically during initialize() when a fresh install is detected.
+     */
+    private fetchDeferredWebAttribution;
     /**
      * Alias a user (connect anonymous user to known user)
      */

package/lib/datalyr-sdk.js

@@ -187,6 +187,11 @@ export class DatalyrSDK {
             this.state.initialized = true;
             // Check for app install (after SDK is marked as initialized)
             if (attributionManager.isInstall()) {
+                // iOS: Attempt deferred web-to-app attribution via IP matching before tracking install
+                // Android: Play Store referrer is handled by playInstallReferrerIntegration
+                if (Platform.OS === 'ios') {
+                    await this.fetchDeferredWebAttribution();
+                }
                 const installData = await attributionManager.trackInstall();
                 await this.track('app_install', {
                     platform: Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : 'android',
@@ -368,6 +373,77 @@ export class DatalyrSDK {
             // Non-blocking - continue even if attribution fetch fails
         }
     }
+    /**
+     * Fetch deferred web attribution on first app install.
+     * Uses IP-based matching (iOS) or Play Store referrer (Android) to recover
+     * attribution data (fbclid, utm_*, etc.) from a prelander web visit.
+     * Called automatically during initialize() when a fresh install is detected.
+     */
+    async fetchDeferredWebAttribution() {
+        var _a;
+        if (!((_a = this.state.config) === null || _a === void 0 ? void 0 : _a.apiKey)) {
+            debugLog('API key not available for deferred attribution fetch');
+            return;
+        }
+        try {
+            debugLog('Fetching deferred web attribution via IP matching...');
+            const baseUrl = this.state.config.endpoint || 'https://api.datalyr.com';
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 10000);
+            const response = await fetch(`${baseUrl}/attribution/deferred-lookup`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Datalyr-API-Key': this.state.config.apiKey,
+                },
+                body: JSON.stringify({ platform: Platform.OS }),
+                signal: controller.signal,
+            });
+            clearTimeout(timeout);
+            if (!response.ok) {
+                debugLog('Deferred attribution lookup failed:', response.status);
+                return;
+            }
+            const result = await response.json();
+            if (!result.found || !result.attribution) {
+                debugLog('No deferred web attribution found for this IP');
+                return;
+            }
+            const webAttribution = result.attribution;
+            debugLog('Deferred web attribution found:', {
+                visitor_id: webAttribution.visitor_id,
+                has_fbclid: !!webAttribution.fbclid,
+                has_gclid: !!webAttribution.gclid,
+                utm_source: webAttribution.utm_source,
+            });
+            // Merge web attribution into current session
+            attributionManager.mergeWebAttribution(webAttribution);
+            // Track match event for analytics
+            await this.track('$web_attribution_matched', {
+                web_visitor_id: webAttribution.visitor_id,
+                web_user_id: webAttribution.user_id,
+                fbclid: webAttribution.fbclid,
+                gclid: webAttribution.gclid,
+                ttclid: webAttribution.ttclid,
+                gbraid: webAttribution.gbraid,
+                wbraid: webAttribution.wbraid,
+                fbp: webAttribution.fbp,
+                fbc: webAttribution.fbc,
+                utm_source: webAttribution.utm_source,
+                utm_medium: webAttribution.utm_medium,
+                utm_campaign: webAttribution.utm_campaign,
+                utm_content: webAttribution.utm_content,
+                utm_term: webAttribution.utm_term,
+                web_timestamp: webAttribution.timestamp,
+                match_method: 'ip',
+            });
+            debugLog('Successfully merged deferred web attribution');
+        }
+        catch (error) {
+            errorLog('Error fetching deferred web attribution:', error);
+            // Non-blocking - email-based fallback will catch this on identify()
+        }
+    }
     /**
      * Alias a user (connect anonymous user to known user)
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/react-native",
-  "version": "1.4.9",
+  "version": "1.5.0",
   "description": "Datalyr SDK for React Native & Expo - Server-side attribution tracking with bundled Meta and TikTok SDKs for iOS and Android",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/datalyr-sdk.ts

@@ -243,6 +243,12 @@ export class DatalyrSDK {
 
       // Check for app install (after SDK is marked as initialized)
       if (attributionManager.isInstall()) {
+        // iOS: Attempt deferred web-to-app attribution via IP matching before tracking install
+        // Android: Play Store referrer is handled by playInstallReferrerIntegration
+        if (Platform.OS === 'ios') {
+          await this.fetchDeferredWebAttribution();
+        }
+
         const installData = await attributionManager.trackInstall();
         await this.track('app_install', {
           platform: Platform.OS === 'ios' || Platform.OS === 'android' ? Platform.OS : 'android',
@@ -453,6 +459,88 @@ export class DatalyrSDK {
     }
   }
 
+  /**
+   * Fetch deferred web attribution on first app install.
+   * Uses IP-based matching (iOS) or Play Store referrer (Android) to recover
+   * attribution data (fbclid, utm_*, etc.) from a prelander web visit.
+   * Called automatically during initialize() when a fresh install is detected.
+   */
+  private async fetchDeferredWebAttribution(): Promise<void> {
+    if (!this.state.config?.apiKey) {
+      debugLog('API key not available for deferred attribution fetch');
+      return;
+    }
+
+    try {
+      debugLog('Fetching deferred web attribution via IP matching...');
+
+      const baseUrl = this.state.config.endpoint || 'https://api.datalyr.com';
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), 10000);
+
+      const response = await fetch(`${baseUrl}/attribution/deferred-lookup`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Datalyr-API-Key': this.state.config.apiKey,
+        },
+        body: JSON.stringify({ platform: Platform.OS }),
+        signal: controller.signal,
+      });
+
+      clearTimeout(timeout);
+
+      if (!response.ok) {
+        debugLog('Deferred attribution lookup failed:', response.status);
+        return;
+      }
+
+      const result = await response.json() as { found: boolean; attribution?: any };
+
+      if (!result.found || !result.attribution) {
+        debugLog('No deferred web attribution found for this IP');
+        return;
+      }
+
+      const webAttribution = result.attribution;
+      debugLog('Deferred web attribution found:', {
+        visitor_id: webAttribution.visitor_id,
+        has_fbclid: !!webAttribution.fbclid,
+        has_gclid: !!webAttribution.gclid,
+        utm_source: webAttribution.utm_source,
+      });
+
+      // Merge web attribution into current session
+      attributionManager.mergeWebAttribution(webAttribution);
+
+      // Track match event for analytics
+      await this.track('$web_attribution_matched', {
+        web_visitor_id: webAttribution.visitor_id,
+        web_user_id: webAttribution.user_id,
+        fbclid: webAttribution.fbclid,
+        gclid: webAttribution.gclid,
+        ttclid: webAttribution.ttclid,
+        gbraid: webAttribution.gbraid,
+        wbraid: webAttribution.wbraid,
+        fbp: webAttribution.fbp,
+        fbc: webAttribution.fbc,
+        utm_source: webAttribution.utm_source,
+        utm_medium: webAttribution.utm_medium,
+        utm_campaign: webAttribution.utm_campaign,
+        utm_content: webAttribution.utm_content,
+        utm_term: webAttribution.utm_term,
+        web_timestamp: webAttribution.timestamp,
+        match_method: 'ip',
+      });
+
+      debugLog('Successfully merged deferred web attribution');
+
+    } catch (error) {
+      errorLog('Error fetching deferred web attribution:', error as Error);
+      // Non-blocking - email-based fallback will catch this on identify()
+    }
+  }
+
   /**
    * Alias a user (connect anonymous user to known user)
    */