@datalyr/web 1.0.3 → 1.0.5

package/README.md

@@ -504,6 +504,128 @@ export default function RootLayout({ children }) {
 }
 ```
 
+## Authentication & Server-Side Tracking
+
+### ⚠️ Critical: Server-Side Identification for Authentication
+
+When implementing authentication flows (login, signup, OAuth), you **MUST** call identify on the server-side before redirecting. Client-side identification during auth flows is unreliable and will cause attribution data loss.
+
+#### The Problem
+
+```javascript
+// ❌ WRONG - Client-side only (unreliable for auth flows)
+function LoginPage() {
+  const handleLogin = async () => {
+    await login(email, password);
+    datalyr.identify(userId); // May not execute before redirect!
+    router.push('/dashboard'); // User redirects, identify never completes
+  };
+}
+```
+
+#### The Solution
+
+```javascript
+// ✅ CORRECT - Server-side identification
+// Next.js Server Action example
+async function loginAction(email: string, password: string) {
+  const user = await authenticate(email, password);
+  
+  // Critical: Identify BEFORE redirect
+  await fetch('https://datalyr.com/api/v1/events', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.DATALYR_API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      event_name: '$identify',
+      user_id: user.id,
+      workspace_id: process.env.DATALYR_WORKSPACE_ID,
+      properties: {
+        email: user.email,
+        source: 'login'
+      }
+    })
+  });
+  
+  redirect('/dashboard');
+}
+
+// For signup
+async function signupAction(email: string, password: string) {
+  const user = await createUser(email, password);
+  
+  // Identify new user server-side
+  await identifyUserServer(user.id, {
+    email: user.email,
+    created_at: new Date().toISOString(),
+    source: 'signup'
+  });
+  
+  redirect('/onboarding');
+}
+```
+
+### Why Server-Side Identification Matters
+
+1. **Attribution Tracking**: Links anonymous visitors who clicked ads (with fbclid, gclid, etc.) to authenticated users
+2. **Cross-Device Tracking**: Connects users across different devices and browsers
+3. **Reliability**: Guarantees execution before redirects, unlike client-side
+4. **OAuth Compatibility**: Works with complex OAuth redirect chains
+
+### Implementation Checklist
+
+Ensure you call identify server-side in ALL these scenarios:
+
+- [ ] **Email Signup**: Call identify when creating new accounts
+- [ ] **Email Login**: Call identify for returning users
+- [ ] **OAuth Signup**: Call identify in OAuth callback for new users
+- [ ] **OAuth Login**: Call identify in OAuth callback for existing users  
+- [ ] **Magic Links**: Call identify when validating magic link tokens
+- [ ] **Password Reset**: Call identify after successful password reset
+- [ ] **Session Restore**: Call identify when validating existing sessions on app load
+
+### Example: Complete OAuth Implementation
+
+```javascript
+// app/auth/callback/route.ts
+export async function GET(request: Request) {
+  const { user } = await validateOAuthCallback(request);
+  
+  const existingUser = await getUserByEmail(user.email);
+  
+  if (existingUser) {
+    // Existing user logging in
+    await identifyUserServer(existingUser.id, {
+      email: existingUser.email,
+      source: 'oauth_login',
+      provider: 'google'
+    });
+    await trackEventServer('login', { method: 'oauth' });
+  } else {
+    // New user signing up
+    const newUser = await createUser(user);
+    await identifyUserServer(newUser.id, {
+      email: newUser.email,
+      source: 'oauth_signup',
+      provider: 'google'
+    });
+    await trackEventServer('signup', { method: 'oauth' });
+  }
+  
+  return redirect('/dashboard');
+}
+```
+
+### What Happens Without Server-Side Identify
+
+Without proper server-side identification:
+- **Lost Attribution**: Ad clicks (fbclid, gclid) won't be associated with conversions
+- **Broken Cross-Device**: Users on multiple devices won't be linked
+- **Incomplete Funnels**: User journeys will appear fragmented
+- **Inaccurate Analytics**: Conversion rates and ROI calculations will be wrong
+
 ## Best Practices
 
 ### 1. Initialize Early

package/dist/attribution.d.ts

@@ -41,6 +41,18 @@ export declare class AttributionManager {
      * Get customer journey
      */
     getJourney(): TouchPoint[];
+    /**
+     * Capture advertising platform cookies
+     */
+    private captureAdCookies;
+    /**
+     * Check if we have a specific click ID in current params
+     */
+    private hasClickId;
+    /**
+     * Get current fbclid from URL if present
+     */
+    private getCurrentFbclid;
     /**
      * Get attribution data for event
      */

package/dist/attribution.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,UAAU,CAA2E;IAE7F,OAAO,CAAC,SAAS,CAgBf;IAEF,OAAO,CAAC,sBAAsB,CAO5B;gBAEU,OAAO,GAAE;QACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB;IAMN;;OAEG;IACH,kBAAkB,IAAI,WAAW;IAwDjC;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAU/C;;OAEG;IACH,aAAa,IAAI,WAAW,GAAG,IAAI;IAInC;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAO9C;;OAEG;IACH,YAAY,IAAI,WAAW,GAAG,IAAI;IAIlC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI;IAqBhE;;OAEG;IACH,UAAU,IAAI,UAAU,EAAE;IAI1B;;OAEG;IACH,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAgDzC;;OAEG;IACH,OAAO,CAAC,eAAe;IA6CvB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO;IAKvD;;OAEG;IACH,uBAAuB,IAAI,IAAI;CAYhC"}
+{"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../src/attribution.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEvD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,aAAa,CAAW;IAChC,OAAO,CAAC,UAAU,CAA2E;IAE7F,OAAO,CAAC,SAAS,CAgBf;IAEF,OAAO,CAAC,sBAAsB,CAO5B;gBAEU,OAAO,GAAE;QACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB;IAMN;;OAEG;IACH,kBAAkB,IAAI,WAAW;IAwDjC;;OAEG;IACH,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAU/C;;OAEG;IACH,aAAa,IAAI,WAAW,GAAG,IAAI;IAInC;;OAEG;IACH,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAO9C;;OAEG;IACH,YAAY,IAAI,WAAW,GAAG,IAAI;IAIlC;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,IAAI;IAqBhE;;OAEG;IACH,UAAU,IAAI,UAAU,EAAE;IAI1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA8CxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAKlB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;IACH,kBAAkB,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAsDzC;;OAEG;IACH,OAAO,CAAC,eAAe;IA6CvB;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,oBAAoB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO;IAKvD;;OAEG;IACH,uBAAuB,IAAI,IAAI;CAYhC"}

package/dist/datalyr.cjs.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.0.3
+ * @datalyr/web v1.0.5
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2025 Datalyr Inc.
  * Released under the MIT License
@@ -942,6 +942,59 @@ class AttributionManager {
     getJourney() {
         return storage.get('dl_journey', []);
     }
+    /**
+     * Capture advertising platform cookies
+     */
+    captureAdCookies() {
+        const adCookies = {};
+        // Facebook/Meta cookies
+        adCookies._fbp = cookies.get('_fbp');
+        adCookies._fbc = cookies.get('_fbc');
+        // Google Ads cookies
+        adCookies._gcl_aw = cookies.get('_gcl_aw');
+        adCookies._gcl_dc = cookies.get('_gcl_dc');
+        adCookies._gcl_gb = cookies.get('_gcl_gb');
+        adCookies._gcl_ha = cookies.get('_gcl_ha');
+        adCookies._gac = cookies.get('_gac');
+        // Google Analytics cookies
+        adCookies._ga = cookies.get('_ga');
+        adCookies._gid = cookies.get('_gid');
+        // TikTok cookies
+        adCookies._ttp = cookies.get('_ttp');
+        adCookies._ttc = cookies.get('_ttc');
+        // Generate _fbp if missing (Facebook browser ID)
+        if (!adCookies._fbp && (this.hasClickId('fbclid') || adCookies._fbc)) {
+            const timestamp = Date.now();
+            const randomId = Math.random().toString(36).substring(2, 15);
+            adCookies._fbp = `fb.1.${timestamp}.${randomId}`;
+            // Optionally set the cookie for future use
+            cookies.set('_fbp', adCookies._fbp, 90);
+        }
+        // Generate _fbc if we have fbclid but no _fbc
+        const fbclid = this.getCurrentFbclid();
+        if (fbclid && !adCookies._fbc) {
+            const timestamp = Math.floor(Date.now() / 1000);
+            adCookies._fbc = `fb.1.${timestamp}.${fbclid}`;
+            // Optionally set the cookie for future use
+            cookies.set('_fbc', adCookies._fbc, 90);
+        }
+        // Filter out null values for cleaner data
+        return Object.fromEntries(Object.entries(adCookies).filter(([_, value]) => value !== null));
+    }
+    /**
+     * Check if we have a specific click ID in current params
+     */
+    hasClickId(clickIdType) {
+        const params = getAllQueryParams();
+        return !!params[clickIdType];
+    }
+    /**
+     * Get current fbclid from URL if present
+     */
+    getCurrentFbclid() {
+        const params = getAllQueryParams();
+        return params.fbclid || null;
+    }
     /**
      * Get attribution data for event
      */
@@ -950,6 +1003,8 @@ class AttributionManager {
         const lastTouch = this.getLastTouch();
         const journey = this.getJourney();
         const current = this.captureAttribution();
+        // Capture advertising cookies automatically
+        const adCookies = this.captureAdCookies();
         // Update first/last touch if needed
         if (!firstTouch && Object.keys(current).length > 1) {
             this.storeFirstTouch(current);
@@ -957,7 +1012,7 @@ class AttributionManager {
         if (Object.keys(current).length > 1) {
             this.storeLastTouch(current);
         }
-        return Object.assign(Object.assign({}, current), { 
+        return Object.assign(Object.assign(Object.assign({}, current), adCookies), { 
             // First touch (with snake_case 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 (with snake_case aliases)