ainamika-sdk 1.2.7 → 1.2.9

package/README.md

@@ -8,6 +8,7 @@
 ## Features
 
 - **AI-Powered Auto-Configuration**: Automatically analyzes your DOM and generates semantic tracking configurations
+- **Session Start Tracking**: Captures device info, landing page, referrer, and UTM params immediately on load
 - **Web Vitals & Performance Tracking**: Core Web Vitals (LCP, FCP, FID, CLS, TTFB) and page load metrics
 - **Engagement Analytics**: Scroll depth, rage clicks, time on page, active/idle time tracking
 - **API Response Tracking**: Track and analyze API calls with timing and response data
@@ -15,6 +16,7 @@
 - **Page Context & Query Params**: Automatic capture of URL, path, query parameters, referrer with every event
 - **Extra Config Support**: Pass custom data (userId, deviceId, appVersion) that's included in all events
 - **Smart Event Naming**: AI generates semantic event names like `game_launch_cubeform` instead of generic names
+- **Framework Detection**: Detects click handlers from React, Vue, Angular, Svelte, and jQuery components
 - **User Journey Analysis**: Track complete user journeys for funnel optimization
 - **Sampling Support**: Server-side sampling to control data volume and costs
 - **Offline Support**: Queue events when offline and sync when back online
@@ -141,6 +143,58 @@ console.log(metrics);
 // }
 ```
 
+## Session Tracking
+
+The SDK automatically sends a `session_start` event immediately when it loads, before any other processing. This ensures you capture data from the moment a user lands on your app.
+
+### Session Start Event Data
+
+```javascript
+// Automatically sent on SDK initialization
+{
+  event: "session_start",
+  properties: {
+    // Device Information
+    userAgent: "Mozilla/5.0...",
+    language: "en-US",
+    languages: ["en-US", "en"],
+    platform: "MacIntel",
+    screenWidth: 1920,
+    screenHeight: 1080,
+    viewportWidth: 1440,
+    viewportHeight: 900,
+    devicePixelRatio: 2,
+    timezone: "America/New_York",
+    timezoneOffset: -300,
+    cookieEnabled: true,
+    onLine: true,
+
+    // Session Info
+    sessionId: "sess_abc123",
+    userIdentifier: "anon_xyz789",
+    isNewSession: true,
+    sdkVersion: "1.2.7",
+
+    // Landing Page
+    landingPage: "/products",
+    landingUrl: "https://example.com/products?ref=google",
+    referrer: "https://google.com",
+    entryTitle: "Products - My Store",
+
+    // UTM Parameters (if present)
+    utmSource: "google",
+    utmMedium: "cpc",
+    utmCampaign: "summer_sale"
+  }
+}
+```
+
+This gives you complete visibility into:
+- **Traffic sources**: Where users come from (referrer, UTM params)
+- **Device landscape**: Screen sizes, browsers, platforms
+- **Geographic distribution**: Timezone data
+- **Entry points**: Which pages users land on first
+
 ## Engagement Tracking
 
 Track how users interact with your pages:
@@ -492,10 +546,11 @@ new AInamikaSDK(config: AnalyticsConfig)
 
 | Category | Events |
 |----------|--------|
+| **Session** | `session_start` - Fires immediately on SDK load with device info, landing page, referrer, UTM params |
 | **Performance** | `performance_lcp`, `performance_fcp`, `performance_fid`, `performance_cls`, `performance_page_load` |
 | **Engagement** | `engagement_scroll_depth`, `engagement_rage_click`, `page_exit` |
 | **API** | `api_call` (when enabled) |
-| **DOM** | Click, submit, view, focus events based on auto-config |
+| **DOM** | Click, submit, view, focus, change events based on auto-config |
 
 ## Dashboard Queries