featurely-site-manager 1.1.4 → 1.1.6

package/README.md

@@ -63,9 +63,11 @@ siteManager.init();
 
 ### 📊 Analytics
 
+- Automatic page view tracking (SPA-compatible)
+- Session start and end tracking
+- User login event tracking
+- Page exit tracking with time-on-page duration
 - Track custom events
-- Automatic feature flag usage tracking
-- Session management
 - User identification
 
 ## 📖 Usage
@@ -216,6 +218,7 @@ const manager = new SiteManager({
 });
 
 manager.init();
+// Automatically tracks: session_start, page_view, page_exit on every navigation
 
 // Track custom events
 manager.trackEvent("button_clicked", {
@@ -223,12 +226,25 @@ manager.trackEvent("button_clicked", {
   page: "/home",
 });
 
-manager.trackEvent("feature_used", {
-  feature: "dark_mode",
-  enabled: true,
+manager.trackEvent("purchase_completed", {
+  amount: 99.99,
+  plan: "pro",
 });
 ```
 
+#### Automatic Events
+
+When `enableAnalytics` is `true` (default), the SDK automatically tracks:
+
+| Event | When | Properties |
+| --- | --- | --- |
+| `session_start` | On first page load | `path`, `title`, `referrer` |
+| `page_view` | On every page navigation | `path`, `title`, `referrer`, `isLoggedIn`, `userId?`, `userEmail?` |
+| `page_exit` | When navigating away from a page | `path`, `durationSeconds` |
+| `user_login` | First time `setUser()` is called with a userId | `userId`, `userEmail?`, `userName?` |
+
+Page tracking is SPA-compatible — it patches `history.pushState` and `history.replaceState` and listens to `popstate` so navigations in React, Next.js, Vue, and similar frameworks are captured automatically.
+
 ### Custom Poll Interval
 
 ```typescript
@@ -280,12 +296,12 @@ Initialize and start the site manager.
 await manager.init();
 ```
 
-#### `setUser(email: string, userId?: string)`
+#### `setUser(email: string, userId?: string, userName?: string)`
 
-Update user email and ID for whitelist and targeting.
+Update user context for whitelist, targeting, and analytics. If `userId` is provided for the first time, a `user_login` analytics event is fired automatically.
 
 ```typescript
-manager.setUser("user@example.com", "user_123");
+manager.setUser("user@example.com", "user_123", "Jane Doe");
 ```
 
 #### `refresh()`
@@ -464,56 +480,29 @@ const manager = new SiteManager({
 manager.init();
 ```
 
-## 🔧 Configuration
+## 🔒 Content Security Policy (CSP)
 
-### SiteManagerConfig
-
-| Option                  | Type            | Required | Default                   | Description                   |
-| ----------------------- | --------------- | -------- | ------------------------- | ----------------------------- |
-| `apiKey`                | `string`        | ✅       | -                         | Your Featurely API key        |
-| `projectId`             | `string`        | ✅       | -                         | Your Featurely project ID     |
-| `apiUrl`                | `string`        | ❌       | `'https://featurely.no'` | Custom API endpoint           |
-| `pollInterval`          | `number`        | ❌       | `60000`                   | Polling interval in ms        |
-| `userEmail`             | `string`        | ❌       | -                         | User email for whitelist      |
-| `bypassCheck`           | `() => boolean` | ❌       | -                         | Custom bypass function        |
-| `onMaintenanceEnabled`  | `function`      | ❌       | -                         | Maintenance enabled callback  |
-| `onMaintenanceDisabled` | `function`      | ❌       | -                         | Maintenance disabled callback |
-| `onMessageReceived`     | `function`      | ❌       | -                         | Message received callback     |
-| `onMessageDismissed`    | `function`      | ❌       | -                         | Message dismissed callback    |
-| `onError`               | `function`      | ❌       | -                         | Error callback                |
-
-## 🎯 API Methods
+If your site uses a `Content-Security-Policy` header, you must allow connections to `https://www.featurely.no`. Without this, all API calls (config polling, analytics, feature flags) will be silently blocked.
 
-### `init()`
+Add the following to your `connect-src` directive:
 
-Initialize and start the site manager.
-
-```typescript
-await manager.init();
 ```
-
-### `setUser(email: string)`
-
-Update user email for whitelist checks.
-
-```typescript
-manager.setUser("user@example.com");
+connect-src 'self' https://www.featurely.no;
 ```
 
-### `refresh()`
-
-Manually refresh configuration from server.
+**Next.js example** (`next.config.js`):
 
-```typescript
-await manager.refresh();
+```javascript
+const cspHeader = `
+  connect-src 'self' https://www.featurely.no;
+`.trim();
 ```
 
-### `destroy()`
-
-Stop the manager and clean up.
+If the SDK is being blocked by CSP, you will see a message like this in the browser console:
 
-```typescript
-manager.destroy();
+```
+[SiteManager] ⚠️ Connection to Featurely was blocked — check your Content-Security-Policy.
+Add "https://www.featurely.no" to your connect-src directive.
 ```
 
 ## 🎨 Maintenance Mode

package/dist/index.d.mts

@@ -103,6 +103,9 @@ declare class SiteManager {
     private analyticsFlushIntervalId;
     private sessionId;
     private consecutiveFetchFailures;
+    private pageTrackingSetup;
+    private currentPagePath;
+    private pageEntryTime;
     private static readonly MAX_CONSECUTIVE_FAILURES;
     private lastVersionCheck;
     constructor(config: SiteManagerConfig);
@@ -123,6 +126,9 @@ declare class SiteManager {
     private startAnalyticsFlushing;
     private stopAnalyticsFlushing;
     private flushAnalytics;
+    private setupPageTracking;
+    private trackPageView;
+    private onNavigate;
     private generateSessionId;
     checkVersion(currentVersion?: string): Promise<VersionCheckResponse | null>;
     getLastVersionCheck(): VersionCheckResponse | null;

package/dist/index.d.ts

@@ -103,6 +103,9 @@ declare class SiteManager {
     private analyticsFlushIntervalId;
     private sessionId;
     private consecutiveFetchFailures;
+    private pageTrackingSetup;
+    private currentPagePath;
+    private pageEntryTime;
     private static readonly MAX_CONSECUTIVE_FAILURES;
     private lastVersionCheck;
     constructor(config: SiteManagerConfig);
@@ -123,6 +126,9 @@ declare class SiteManager {
     private startAnalyticsFlushing;
     private stopAnalyticsFlushing;
     private flushAnalytics;
+    private setupPageTracking;
+    private trackPageView;
+    private onNavigate;
     private generateSessionId;
     checkVersion(currentVersion?: string): Promise<VersionCheckResponse | null>;
     getLastVersionCheck(): VersionCheckResponse | null;

package/dist/index.js

@@ -48,6 +48,9 @@ var _SiteManager = class _SiteManager {
     this.analyticsFlushIntervalId = null;
     this.sessionId = this.generateSessionId();
     this.consecutiveFetchFailures = 0;
+    this.pageTrackingSetup = false;
+    this.currentPagePath = "";
+    this.pageEntryTime = 0;
     this.lastVersionCheck = null;
     var _a, _b, _c, _d, _e;
     if (!config.apiKey) {
@@ -95,6 +98,7 @@ var _SiteManager = class _SiteManager {
     this.startPolling();
     if (this.config.enableAnalytics) {
       this.startAnalyticsFlushing();
+      this.setupPageTracking();
     }
     if (this.config.enableVersionCheck && this.config.appVersion) {
       await this.checkVersion();
@@ -117,10 +121,17 @@ var _SiteManager = class _SiteManager {
    */
   setUser(email, userId) {
     var _a;
+    const wasLoggedIn = !!this.config.userId;
     this.config.userEmail = email;
     if (userId) {
       this.config.userId = userId;
     }
+    if (!wasLoggedIn && this.config.userId && this.config.enableAnalytics) {
+      this.trackEvent("user_login", {
+        userId: this.config.userId,
+        ...this.config.userEmail ? { userEmail: this.config.userEmail } : {}
+      });
+    }
     if ((_a = this.siteConfig) == null ? void 0 : _a.maintenance.enabled) {
       this.checkMaintenanceMode();
     }
@@ -399,6 +410,74 @@ var _SiteManager = class _SiteManager {
       }
     }
   }
+  setupPageTracking() {
+    if (this.pageTrackingSetup) return;
+    this.pageTrackingSetup = true;
+    this.trackEvent("session_start", {
+      referrer: document.referrer || "",
+      language: navigator.language,
+      screenWidth: window.screen.width,
+      screenHeight: window.screen.height,
+      isLoggedIn: !!this.config.userId
+    });
+    this.currentPagePath = window.location.pathname;
+    this.pageEntryTime = Date.now();
+    this.trackPageView();
+    const originalPushState = history.pushState.bind(history);
+    const originalReplaceState = history.replaceState.bind(history);
+    const self = this;
+    history.pushState = function(...args) {
+      originalPushState(...args);
+      self.onNavigate();
+    };
+    history.replaceState = function(...args) {
+      originalReplaceState(...args);
+      if (window.location.pathname !== self.currentPagePath) {
+        self.onNavigate();
+      }
+    };
+    window.addEventListener("popstate", () => this.onNavigate());
+    window.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        const duration = Math.round((Date.now() - this.pageEntryTime) / 1e3);
+        if (duration > 0) {
+          this.trackEvent("page_exit", {
+            path: this.currentPagePath,
+            durationSeconds: duration
+          });
+          this.flushAnalytics();
+        }
+      } else if (document.visibilityState === "visible") {
+        this.pageEntryTime = Date.now();
+      }
+    });
+  }
+  trackPageView() {
+    const props = {
+      path: this.currentPagePath,
+      title: document.title,
+      referrer: document.referrer || "",
+      isLoggedIn: !!this.config.userId
+    };
+    if (this.config.userId) props.userId = this.config.userId;
+    if (this.config.userEmail) props.userEmail = this.config.userEmail;
+    this.trackEvent("page_view", props);
+  }
+  onNavigate() {
+    const newPath = window.location.pathname;
+    if (this.currentPagePath && this.pageEntryTime > 0) {
+      const duration = Math.round((Date.now() - this.pageEntryTime) / 1e3);
+      if (duration > 0) {
+        this.trackEvent("page_exit", {
+          path: this.currentPagePath,
+          durationSeconds: duration
+        });
+      }
+    }
+    this.currentPagePath = newPath;
+    this.pageEntryTime = Date.now();
+    setTimeout(() => this.trackPageView(), 100);
+  }
   generateSessionId() {
     if (typeof crypto !== "undefined" && crypto.getRandomValues) {
       const array = new Uint8Array(16);

package/dist/index.mjs

@@ -13,6 +13,9 @@ var _SiteManager = class _SiteManager {
     this.analyticsFlushIntervalId = null;
     this.sessionId = this.generateSessionId();
     this.consecutiveFetchFailures = 0;
+    this.pageTrackingSetup = false;
+    this.currentPagePath = "";
+    this.pageEntryTime = 0;
     this.lastVersionCheck = null;
     var _a, _b, _c, _d, _e;
     if (!config.apiKey) {
@@ -60,6 +63,7 @@ var _SiteManager = class _SiteManager {
     this.startPolling();
     if (this.config.enableAnalytics) {
       this.startAnalyticsFlushing();
+      this.setupPageTracking();
     }
     if (this.config.enableVersionCheck && this.config.appVersion) {
       await this.checkVersion();
@@ -82,10 +86,17 @@ var _SiteManager = class _SiteManager {
    */
   setUser(email, userId) {
     var _a;
+    const wasLoggedIn = !!this.config.userId;
     this.config.userEmail = email;
     if (userId) {
       this.config.userId = userId;
     }
+    if (!wasLoggedIn && this.config.userId && this.config.enableAnalytics) {
+      this.trackEvent("user_login", {
+        userId: this.config.userId,
+        ...this.config.userEmail ? { userEmail: this.config.userEmail } : {}
+      });
+    }
     if ((_a = this.siteConfig) == null ? void 0 : _a.maintenance.enabled) {
       this.checkMaintenanceMode();
     }
@@ -364,6 +375,74 @@ var _SiteManager = class _SiteManager {
       }
     }
   }
+  setupPageTracking() {
+    if (this.pageTrackingSetup) return;
+    this.pageTrackingSetup = true;
+    this.trackEvent("session_start", {
+      referrer: document.referrer || "",
+      language: navigator.language,
+      screenWidth: window.screen.width,
+      screenHeight: window.screen.height,
+      isLoggedIn: !!this.config.userId
+    });
+    this.currentPagePath = window.location.pathname;
+    this.pageEntryTime = Date.now();
+    this.trackPageView();
+    const originalPushState = history.pushState.bind(history);
+    const originalReplaceState = history.replaceState.bind(history);
+    const self = this;
+    history.pushState = function(...args) {
+      originalPushState(...args);
+      self.onNavigate();
+    };
+    history.replaceState = function(...args) {
+      originalReplaceState(...args);
+      if (window.location.pathname !== self.currentPagePath) {
+        self.onNavigate();
+      }
+    };
+    window.addEventListener("popstate", () => this.onNavigate());
+    window.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") {
+        const duration = Math.round((Date.now() - this.pageEntryTime) / 1e3);
+        if (duration > 0) {
+          this.trackEvent("page_exit", {
+            path: this.currentPagePath,
+            durationSeconds: duration
+          });
+          this.flushAnalytics();
+        }
+      } else if (document.visibilityState === "visible") {
+        this.pageEntryTime = Date.now();
+      }
+    });
+  }
+  trackPageView() {
+    const props = {
+      path: this.currentPagePath,
+      title: document.title,
+      referrer: document.referrer || "",
+      isLoggedIn: !!this.config.userId
+    };
+    if (this.config.userId) props.userId = this.config.userId;
+    if (this.config.userEmail) props.userEmail = this.config.userEmail;
+    this.trackEvent("page_view", props);
+  }
+  onNavigate() {
+    const newPath = window.location.pathname;
+    if (this.currentPagePath && this.pageEntryTime > 0) {
+      const duration = Math.round((Date.now() - this.pageEntryTime) / 1e3);
+      if (duration > 0) {
+        this.trackEvent("page_exit", {
+          path: this.currentPagePath,
+          durationSeconds: duration
+        });
+      }
+    }
+    this.currentPagePath = newPath;
+    this.pageEntryTime = Date.now();
+    setTimeout(() => this.trackPageView(), 100);
+  }
   generateSessionId() {
     if (typeof crypto !== "undefined" && crypto.getRandomValues) {
       const array = new Uint8Array(16);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "featurely-site-manager",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "Complete site management SDK for maintenance mode, status messages, feature flags, version checking, and analytics",
   "main": "dist/index.js",
   "module": "dist/index.mjs",