@datalyr/web 1.0.4 → 1.0.6

package/README.md

@@ -504,6 +504,172 @@ export default function RootLayout({ children }) {
 }
 ```
 
+## Authentication & Attribution Tracking
+
+### ⚠️ Critical: Client-Side Identification for Attribution
+
+When implementing authentication flows (login, signup, OAuth), you **MUST** call identify on the client-side (browser) to preserve attribution data. Server-side identification creates new sessions and loses all attribution context.
+
+#### The Problem with Server-Side Identify
+
+```javascript
+// ❌ WRONG - Server-side identify breaks attribution
+app.post('/api/login', async (req, res) => {
+  const user = await authenticate(email, password);
+  
+  // This creates a NEW session without attribution data!
+  await serverAnalytics.identify({
+    userId: user.id,
+    traits: { email: user.email }
+  });
+  
+  res.json({ userId: user.id });
+});
+// Result: Lost UTM params, fbclid, gclid, referrer - all gone!
+```
+
+#### The Correct Solution
+
+```javascript
+// ✅ CORRECT - Client-side identification preserves attribution
+// React/Next.js example
+function LoginPage() {
+  const handleLogin = async () => {
+    // 1. Authenticate on server
+    const response = await fetch('/api/login', {
+      method: 'POST',
+      body: JSON.stringify({ email, password })
+    });
+    
+    const { userId, email, name } = await response.json();
+    
+    // 2. Identify in browser - this preserves attribution!
+    datalyr.identify(userId, {
+      email: email,
+      name: name,
+      login_method: 'email'
+    });
+    
+    // 3. Then redirect
+    router.push('/dashboard');
+  };
+}
+
+// Server endpoint - NO identify, just auth
+app.post('/api/login', async (req, res) => {
+  const user = await authenticate(email, password);
+  
+  // Just return user data for client-side identify
+  res.json({
+    userId: user.id,
+    email: user.email,
+    name: user.name
+  });
+});
+```
+
+### Why Client-Side Identification Matters
+
+1. **Attribution Preserved**: UTM params, fbclid, gclid, referrer all stay linked to the user
+2. **Session Continuity**: Links anonymous session (with all its context) to identified user
+3. **Cookie Access**: Can read and maintain browser session data
+4. **Accurate Journey**: Tracks the complete anonymous → identified user journey
+
+### Implementation Checklist
+
+Ensure you call identify **client-side** in these scenarios:
+
+- [ ] **After Signup Success**: When account creation API returns success
+- [ ] **After Login Success**: When authentication API returns success
+- [ ] **After OAuth Redirect**: When returning from OAuth provider
+- [ ] **After Magic Link Click**: When magic link is validated
+- [ ] **On App Load**: If user session exists, re-identify
+- [ ] **After Email Verification**: When user verifies their email
+- [ ] **Session Restore**: When detecting existing authenticated session
+
+### Example: Complete OAuth Implementation
+
+```javascript
+// Client-side: After OAuth redirect
+useEffect(() => {
+  // Check if we just came back from OAuth
+  if (window.location.search.includes('oauth=success')) {
+    // Get user data from your API/session
+    fetch('/api/me')
+      .then(res => res.json())
+      .then(user => {
+        // Identify in browser - preserves attribution!
+        datalyr.identify(user.id, {
+          email: user.email,
+          name: user.name,
+          auth_method: 'google',
+          signup_source: localStorage.getItem('signup_source') || 'organic'
+        });
+        
+        // Track the appropriate event
+        if (user.isNewUser) {
+          datalyr.track('Signup Completed', { method: 'oauth' });
+        } else {
+          datalyr.track('Login Successful', { method: 'oauth' });
+        }
+      });
+  }
+}, []);
+
+// Server-side: OAuth callback - NO identify!
+export async function GET(request: Request) {
+  const { user } = await validateOAuthCallback(request);
+  
+  const existingUser = await getUserByEmail(user.email);
+  
+  if (existingUser) {
+    // Set session, but DON'T identify
+    await createSession(existingUser.id);
+    return redirect('/dashboard?oauth=success');
+  } else {
+    // Create user, but DON'T identify
+    const newUser = await createUser(user);
+    await createSession(newUser.id);
+    return redirect('/dashboard?oauth=success&new=true');
+  }
+}
+```
+
+### Server-Side Events (Different from Identify!)
+
+Use server-side for **tracking events** with userId (not identify):
+
+```javascript
+// ✅ CORRECT - Server-side events with userId
+// Stripe webhook example
+app.post('/webhook/stripe', async (req, res) => {
+  const event = stripe.webhooks.constructEvent(req.body, sig, secret);
+  
+  if (event.type === 'checkout.session.completed') {
+    const session = event.data.object;
+    
+    // Track purchase event with userId (NOT identify)
+    await analytics.track({
+      userId: session.client_reference_id,  // Your user ID
+      event: 'Purchase Completed',
+      properties: {
+        amount: session.amount_total / 100,
+        currency: session.currency,
+        plan: session.metadata.plan
+      }
+    });
+  }
+});
+```
+
+### What Happens with Server-Side Identify (Wrong!)
+
+If you identify server-side:
+- **Lost Attribution**: New session created, no UTM params or click IDs
+- **Broken Journey**: Can't link anonymous browsing to identified user
+- **Multiple Sessions**: Each server identify creates disconnected session
+- **No Context**: Missing referrer, landing page, device info
+
 ## Best Practices
 
 ### 1. Initialize Early
@@ -557,15 +723,20 @@ datalyr.track('Product Viewed', {
 });
 ```
 
-### 4. Identify Users After Authentication
-Call identify as soon as you know who the user is:
+### 4. ALWAYS Identify in the Browser (Not Server)
+This is critical for attribution:
 
 ```javascript
-// After login
+// ✅ CORRECT - Browser identification
 async function handleLogin(email, password) {
-  const user = await loginUser(email, password);
+  const response = await fetch('/api/login', {
+    method: 'POST',
+    body: JSON.stringify({ email, password })
+  });
+  
+  const user = await response.json();
   
-  // Identify immediately after login
+  // Identify in browser - preserves attribution!
   datalyr.identify(user.id, {
     email: user.email,
     name: user.name,
@@ -573,13 +744,13 @@ async function handleLogin(email, password) {
   });
 }
 
-// After signup
-async function handleSignup(data) {
-  const user = await createUser(data);
+// ❌ WRONG - Server identification
+// This breaks attribution tracking!
+app.post('/api/login', async (req, res) => {
+  const user = await authenticate(req.body);
   
-  datalyr.identify(user.id, {
-    email: data.email,
-    name: data.name,
+  // DON'T DO THIS - Creates new session
+  await serverAnalytics.identify(user.id, {
     signup_date: new Date().toISOString()
   });
   

package/dist/datalyr.cjs.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.0.4
+ * @datalyr/web v1.0.6
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2025 Datalyr Inc.
  * Released under the MIT License

package/dist/datalyr.esm.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.0.4
+ * @datalyr/web v1.0.6
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2025 Datalyr Inc.
  * Released under the MIT License

package/dist/datalyr.js

@@ -1,5 +1,5 @@
 /**
- * @datalyr/web v1.0.4
+ * @datalyr/web v1.0.6
  * Datalyr Web SDK - Modern attribution tracking for web applications
  * (c) 2025 Datalyr Inc.
  * Released under the MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datalyr/web",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Datalyr Web SDK - Modern attribution tracking for web applications",
   "main": "dist/datalyr.js",
   "module": "dist/datalyr.esm.js",