@datalyr/web 1.2.1 → 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.1
+ * @datalyr/web v1.3.0
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2026 Datalyr Inc.
  * Released under the MIT License
@@ -731,8 +731,36 @@ function getRootDomain() {
         // Handle .co.uk, .com.au, etc
         const tld = parts[parts.length - 1];
         const sld = parts[parts.length - 2];
-        // Common two-part TLDs
-        const twoPartTlds = ['co.uk', 'com.au', 'co.nz', 'co.jp', 'co.in', 'co.za'];
+        // Common two-part TLDs (country-specific domains)
+        // Note: The CookieStorage.getAutoDomain() probe method handles unknown TLDs dynamically,
+        // but this list provides faster resolution for known patterns
+        const twoPartTlds = [
+            // United Kingdom
+            'co.uk', 'org.uk', 'net.uk', 'ac.uk', 'gov.uk', 'me.uk',
+            // Australia
+            'com.au', 'net.au', 'org.au', 'edu.au', 'gov.au',
+            // New Zealand
+            'co.nz', 'net.nz', 'org.nz', 'govt.nz',
+            // Japan
+            'co.jp', 'ne.jp', 'or.jp', 'ac.jp', 'go.jp',
+            // India
+            'co.in', 'net.in', 'org.in', 'gov.in', 'ac.in',
+            // South Africa
+            'co.za', 'net.za', 'org.za', 'gov.za',
+            // Brazil
+            'com.br', 'net.br', 'org.br', 'gov.br', 'edu.br',
+            // South Korea
+            'co.kr', 'ne.kr', 'or.kr', 'go.kr', 'ac.kr',
+            // China
+            'com.cn', 'net.cn', 'org.cn', 'gov.cn', 'edu.cn',
+            // Other Asia-Pacific
+            'co.id', 'co.th', 'com.sg', 'com.my', 'com.ph', 'com.vn',
+            'com.tw', 'com.hk',
+            // Latin America
+            'com.mx', 'com.ar', 'com.co', 'com.pe', 'com.cl',
+            // Europe
+            'co.il', 'co.at', 'co.hu', 'co.pl'
+        ];
         const lastTwo = `${sld}.${tld}`;
         if (twoPartTlds.includes(lastTwo) && parts.length >= 3) {
             return '.' + parts.slice(-3).join('.');
@@ -804,6 +832,22 @@ class IdentityManager {
      * Get or create anonymous ID (device/browser identifier)
      */
     getOrCreateAnonymousId() {
+        // 0. Check URL parameter first (cross-domain linking via _dl_vid)
+        // This enables tracking continuity when users navigate between different root domains
+        try {
+            const urlParams = new URLSearchParams(window.location.search);
+            const urlVisitorId = urlParams.get('_dl_vid');
+            if (urlVisitorId && urlVisitorId.startsWith('anon_')) {
+                // Valid visitor ID from URL - use it and persist
+                this.setRootDomainCookie('__dl_visitor_id', urlVisitorId);
+                storage.set('dl_anonymous_id', urlVisitorId);
+                return urlVisitorId;
+            }
+        }
+        catch (e) {
+            // URL parsing failed - continue with cookie/localStorage checks
+            console.warn('[Datalyr] Failed to parse URL for _dl_vid:', e);
+        }
         // 1. Check root domain cookie first (works across subdomains)
         let anonymousId = cookies.get('__dl_visitor_id');
         if (anonymousId) {
@@ -3514,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
      */