@datalyr/web 1.2.2 → 1.3.0

package/README.md

@@ -19,6 +19,7 @@ Browser analytics and attribution SDK for web applications. Track events, identi
 - [Attribution](#attribution)
   - [Automatic Capture](#automatic-capture)
   - [Custom Parameters](#custom-parameters)
+- [Web-to-App Attribution](#web-to-app-attribution)
 - [Event Queue](#event-queue)
 - [Offline Support](#offline-support)
 - [Privacy and Consent](#privacy-and-consent)
@@ -340,6 +341,50 @@ datalyr.init({
 
 ---
 
+## Web-to-App Attribution
+
+Track users who click a "Download App" button on your website and attribute their app install back to the original ad click.
+
+### How It Works
+
+1. User clicks an ad → lands on your prelander page (web SDK loaded, captures `fbclid`, UTMs, IP)
+2. User clicks "Download App" → `trackAppDownloadClick()` fires event with full attribution
+3. User installs from App Store / Play Store
+4. First app open → mobile SDK recovers the web attribution:
+   - **Android**: Deterministic match via Play Store `referrer` URL parameter (~95% accuracy)
+   - **iOS**: IP-based match against recent web events within 24 hours (~90%+ accuracy)
+
+### Usage
+
+```javascript
+// On your prelander "Download" button click handler
+document.querySelector('#download-btn').addEventListener('click', () => {
+  datalyr.trackAppDownloadClick({
+    targetPlatform: 'ios',  // or 'android'
+    appStoreUrl: 'https://apps.apple.com/app/your-app/id123456789',
+  });
+});
+```
+
+For Android, pass the Play Store URL and the SDK will automatically encode attribution params into the `referrer` parameter:
+
+```javascript
+datalyr.trackAppDownloadClick({
+  targetPlatform: 'android',
+  appStoreUrl: 'https://play.google.com/store/apps/details?id=com.yourapp',
+});
+```
+
+The method fires a `$app_download_click` event (with all attribution data), flushes the event queue via `sendBeacon`, then redirects the user to the store URL.
+
+### Requirements
+
+- Web SDK must be initialized on the prelander page
+- Mobile SDK (`@datalyr/react-native` or `@datalyr/swift`) must be installed in the app
+- Attribution is recovered automatically on first app launch — no additional mobile code needed
+
+---
+
 ## Event Queue
 
 Events are batched for efficiency.

package/dist/datalyr.cjs.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.2.2
+ * @datalyr/web v1.3.0
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2026 Datalyr Inc.
  * Released under the MIT License
@@ -3558,6 +3558,60 @@ class Datalyr {
             this.trackError(error, { event: eventName });
         }
     }
+    /**
+     * Track an app download click and redirect to the app store.
+     * Fires a $app_download_click event with full attribution data,
+     * then redirects the user to the appropriate store URL.
+     * For Android, encodes attribution params into the Play Store referrer
+     * so the mobile SDK can retrieve them deterministically after install.
+     */
+    trackAppDownloadClick(options) {
+        if (!this.initialized) {
+            console.warn('[Datalyr] SDK not initialized. Call init() first.');
+            return;
+        }
+        if (!this.shouldTrack())
+            return;
+        // Fire the event with target platform info — attribution data is
+        // automatically merged by createEventPayload via getAttributionData()
+        this.track('$app_download_click', {
+            target_platform: options.targetPlatform,
+            app_store_url: options.appStoreUrl,
+        });
+        // Flush immediately via sendBeacon before page navigates away
+        this.queue.forceFlush();
+        // For Android: append referrer param to Play Store URL with click attribution
+        if (options.targetPlatform === 'android' && options.appStoreUrl.includes('play.google.com')) {
+            const lastTouch = this.attribution.getLastTouch();
+            const referrerParams = new URLSearchParams();
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.clickId)
+                referrerParams.set('dl_click_id', lastTouch.clickId);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.clickIdType)
+                referrerParams.set('dl_click_id_type', lastTouch.clickIdType);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.source)
+                referrerParams.set('utm_source', lastTouch.source);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.medium)
+                referrerParams.set('utm_medium', lastTouch.medium);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.campaign)
+                referrerParams.set('utm_campaign', lastTouch.campaign);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.content)
+                referrerParams.set('utm_content', lastTouch.content);
+            if (lastTouch === null || lastTouch === void 0 ? void 0 : lastTouch.term)
+                referrerParams.set('utm_term', lastTouch.term);
+            try {
+                const url = new URL(options.appStoreUrl);
+                url.searchParams.set('referrer', referrerParams.toString());
+                window.location.href = url.toString();
+            }
+            catch (_a) {
+                // If URL parsing fails, redirect without referrer
+                window.location.href = options.appStoreUrl;
+            }
+        }
+        else {
+            window.location.href = options.appStoreUrl;
+        }
+    }
     /**
      * Identify a user
      */