cuoral-ionic 0.0.5 → 0.0.6

package/dist/intelligence.js

@@ -1,5 +1,6 @@
 import { Capacitor } from '@capacitor/core';
 import { registerPlugin } from '@capacitor/core';
+import * as rrweb from 'rrweb';
 // Register the Cuoral plugin for native error capture
 const CuoralPlugin = registerPlugin('CuoralPlugin');
 export class CuoralIntelligence {
@@ -8,11 +9,13 @@ export class CuoralIntelligence {
             consoleErrorBackendUrl: 'https://api.cuoral.com/customer-intelligence/console-error',
             pageViewBackendUrl: 'https://api.cuoral.com/customer-intelligence/page-view',
             apiResponseBackendUrl: 'https://api.cuoral.com/customer-intelligence/api-response',
+            sessionReplayBackendUrl: 'https://api.cuoral.com/customer-intelligence/session-recording/batch',
             batchSize: 10,
             batchInterval: 2000,
             maxQueueSize: 30,
             retryAttempts: 1,
             retryDelay: 2000,
+            sessionReplayBatchInterval: 10000, // 10 seconds
         };
         this.queues = {
             console_error: [],
@@ -29,6 +32,14 @@ export class CuoralIntelligence {
         // Network monitoring state
         this.originalFetch = null;
         this.originalXMLHttpRequest = null;
+        // Session replay state
+        this.rrwebStopFn = null;
+        this.rrwebEvents = [];
+        this.customEvents = [];
+        this.sessionReplayTimer = null;
+        this.clickTimestamps = new Map();
+        this.rageClickThreshold = 5; // 5 rapid clicks
+        this.rageClickWindowMs = 2000; // Within 2 seconds
         this.sessionId = sessionId;
     }
     /**
@@ -43,6 +54,7 @@ export class CuoralIntelligence {
         this.setupNetworkMonitoring();
         this.setupAppStateListener();
         this.setupNativeErrorCapture();
+        this.setupSessionReplay();
         this.isInitialized = true;
         this.flushPendingEvents();
     }
@@ -90,6 +102,17 @@ export class CuoralIntelligence {
                 delete this.batchTimers[type];
             }
         });
+        // Stop session replay
+        if (this.rrwebStopFn) {
+            this.rrwebStopFn();
+            this.rrwebStopFn = null;
+        }
+        if (this.sessionReplayTimer) {
+            clearInterval(this.sessionReplayTimer);
+            this.sessionReplayTimer = null;
+        }
+        // Flush remaining session replay data
+        this.flushSessionReplayBatch();
         // Restore original functions
         if (this.originalFetch) {
             window.fetch = this.originalFetch;
@@ -505,4 +528,269 @@ export class CuoralIntelligence {
             // Silently fail if plugin is not available
         }
     }
+    /**
+     * Setup session replay with rrweb
+     */
+    setupSessionReplay() {
+        if (!this.sessionId) {
+            console.warn('[Cuoral Intelligence] Session replay requires a session ID');
+            return;
+        }
+        // Start rrweb recording
+        this.rrwebStopFn = rrweb.record({
+            emit: (event) => {
+                this.rrwebEvents.push(event);
+            },
+            checkoutEveryNms: 60000, // Full snapshot every minute
+            sampling: {
+                scroll: 150, // Throttle scroll events
+                media: 800,
+                input: 'last', // Only record final input value (privacy)
+            },
+            maskAllInputs: true, // Mask sensitive inputs (privacy)
+            blockClass: 'cuoral-block',
+            ignoreClass: 'cuoral-ignore',
+        });
+        // Setup custom event tracking
+        this.setupClickTracking();
+        this.setupScrollTracking();
+        this.setupFormTracking();
+        // Start batch timer (send every ~10 seconds)
+        this.sessionReplayTimer = setInterval(() => {
+            this.flushSessionReplayBatch();
+        }, this.config.sessionReplayBatchInterval);
+    }
+    /**
+     * Setup click tracking (including rage clicks)
+     */
+    setupClickTracking() {
+        document.addEventListener('click', (event) => {
+            const target = event.target;
+            if (!target)
+                return;
+            const selector = this.getElementSelector(target);
+            const elementText = target.textContent?.trim().substring(0, 100) || '';
+            const url = window.location.href;
+            const now = Date.now();
+            // Track regular click
+            this.addCustomEvent({
+                name: 'click',
+                category: 'interaction',
+                url,
+                element_selector: selector,
+                element_text: elementText,
+                event_timestamp: new Date(now).toISOString(),
+                session_id: this.sessionId,
+                properties: this.getMetadata(),
+            });
+            // Track rage click detection
+            const clicks = this.clickTimestamps.get(selector) || [];
+            clicks.push(now);
+            // Remove old clicks outside the time window
+            const recentClicks = clicks.filter(timestamp => now - timestamp < this.rageClickWindowMs);
+            this.clickTimestamps.set(selector, recentClicks);
+            // If 5+ clicks within 2 seconds = rage click
+            if (recentClicks.length >= this.rageClickThreshold) {
+                this.addCustomEvent({
+                    name: 'rage_click',
+                    category: 'frustration',
+                    url,
+                    element_selector: selector,
+                    element_text: elementText,
+                    event_timestamp: new Date(now).toISOString(),
+                    session_id: this.sessionId,
+                    properties: {
+                        ...this.getMetadata(),
+                        click_count: recentClicks.length,
+                    },
+                });
+                // Clear after detecting rage click
+                this.clickTimestamps.delete(selector);
+            }
+        }, true);
+    }
+    /**
+     * Setup scroll depth tracking
+     */
+    setupScrollTracking() {
+        let scrollDepths = new Set();
+        let ticking = false;
+        const trackScroll = () => {
+            const scrollPercentage = Math.round((window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100);
+            // Track milestones: 25%, 50%, 75%, 100%
+            const milestones = [25, 50, 75, 100];
+            for (const milestone of milestones) {
+                if (scrollPercentage >= milestone && !scrollDepths.has(milestone)) {
+                    scrollDepths.add(milestone);
+                    this.addCustomEvent({
+                        name: 'scroll_depth',
+                        category: 'engagement',
+                        url: window.location.href,
+                        event_timestamp: new Date().toISOString(),
+                        session_id: this.sessionId,
+                        properties: {
+                            ...this.getMetadata(),
+                            percentage: milestone,
+                        },
+                    });
+                }
+            }
+            ticking = false;
+        };
+        window.addEventListener('scroll', () => {
+            if (!ticking) {
+                window.requestAnimationFrame(trackScroll);
+                ticking = true;
+            }
+        });
+    }
+    /**
+     * Setup form tracking
+     */
+    setupFormTracking() {
+        const trackedForms = new WeakSet();
+        // Track form starts
+        document.addEventListener('focusin', (event) => {
+            const target = event.target;
+            if (!target)
+                return;
+            const form = target.closest('form');
+            if (form && !trackedForms.has(form)) {
+                trackedForms.add(form);
+                this.addCustomEvent({
+                    name: 'form_started',
+                    category: 'form',
+                    url: window.location.href,
+                    element_selector: this.getElementSelector(form),
+                    event_timestamp: new Date().toISOString(),
+                    session_id: this.sessionId,
+                    properties: this.getMetadata(),
+                });
+            }
+        }, true);
+        // Track form submissions
+        document.addEventListener('submit', (event) => {
+            const form = event.target;
+            if (!form)
+                return;
+            this.addCustomEvent({
+                name: 'form_submitted',
+                category: 'form',
+                url: window.location.href,
+                element_selector: this.getElementSelector(form),
+                event_timestamp: new Date().toISOString(),
+                session_id: this.sessionId,
+                properties: this.getMetadata(),
+            });
+        }, true);
+        // Track form abandonment (on page exit with incomplete forms)
+        window.addEventListener('beforeunload', () => {
+            document.querySelectorAll('form').forEach((form) => {
+                const inputs = form.querySelectorAll('input, textarea, select');
+                const hasValue = Array.from(inputs).some((input) => input.value);
+                if (hasValue && !trackedForms.has(form)) {
+                    this.addCustomEvent({
+                        name: 'form_abandoned',
+                        category: 'form',
+                        url: window.location.href,
+                        element_selector: this.getElementSelector(form),
+                        event_timestamp: new Date().toISOString(),
+                        session_id: this.sessionId,
+                        properties: this.getMetadata(),
+                    });
+                }
+            });
+        });
+    }
+    /**
+     * Track custom business events (flows, features, etc.)
+     */
+    trackCustomEvent(name, category, properties = {}, elementSelector, elementText) {
+        this.addCustomEvent({
+            name,
+            category,
+            url: window.location.href,
+            element_selector: elementSelector,
+            element_text: elementText,
+            event_timestamp: new Date().toISOString(),
+            session_id: this.sessionId,
+            properties: {
+                ...this.getMetadata(),
+                ...properties,
+            },
+        });
+    }
+    /**
+     * Add a custom event to the buffer
+     */
+    addCustomEvent(event) {
+        this.customEvents.push(event);
+    }
+    /**
+     * Flush session replay batch
+     */
+    flushSessionReplayBatch() {
+        if (!this.sessionId)
+            return;
+        const eventsToSend = [...this.rrwebEvents];
+        const customEventsToSend = [...this.customEvents];
+        // Clear buffers
+        this.rrwebEvents = [];
+        this.customEvents = [];
+        // Only send if there's data
+        if (eventsToSend.length === 0 && customEventsToSend.length === 0) {
+            return;
+        }
+        const batch = {
+            session_id: this.sessionId,
+            events: eventsToSend,
+            custom_events: customEventsToSend,
+        };
+        this.sendSessionReplayBatch(batch);
+    }
+    /**
+     * Send session replay batch to backend
+     */
+    async sendSessionReplayBatch(batch) {
+        try {
+            const response = await fetch(this.config.sessionReplayBackendUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(batch),
+            });
+            if (!response.ok) {
+                console.warn('[Cuoral Intelligence] Failed to send session replay batch');
+            }
+        }
+        catch (error) {
+            console.warn('[Cuoral Intelligence] Error sending session replay batch:', error);
+        }
+    }
+    /**
+     * Get element selector (CSS selector)
+     */
+    getElementSelector(element) {
+        if (element.id) {
+            return `#${element.id}`;
+        }
+        if (element.className && typeof element.className === 'string') {
+            const classes = element.className.split(' ').filter(c => c).join('.');
+            if (classes) {
+                return `${element.tagName.toLowerCase()}.${classes}`;
+            }
+        }
+        return element.tagName.toLowerCase();
+    }
+    /**
+     * Get metadata (user agent, screen resolution, viewport)
+     */
+    getMetadata() {
+        return {
+            user_agent: navigator.userAgent,
+            screen_resolution: `${screen.width}x${screen.height}`,
+            viewport_size: `${window.innerWidth}x${window.innerHeight}`,
+        };
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cuoral-ionic",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Cuoral Ionic Framework Library - Proactive customer success platform with support ticketing, customer intelligence, screen recording, and engagement tools",
   "type": "module",
   "main": "dist/index.js",
@@ -51,7 +51,9 @@
     "rollup-plugin-typescript2": "^0.36.0",
     "typescript": "^5.0.0"
   },
-  "dependencies": {},
+  "dependencies": {
+    "rrweb": "^1.1.3"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/cuoral/cuoral-ionic.git"

package/src/cuoral.ts

@@ -205,6 +205,32 @@ export class Cuoral {
     }
   }
 
+  /**
+   * Start native screen recording programmatically
+   * @returns Promise<boolean> - true if recording started successfully
+   */
+  public async startRecording(): Promise<boolean> {
+    try {
+      return await this.recorder.startRecording();
+    } catch (error) {
+      console.error('[Cuoral] Failed to start recording:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Stop native screen recording programmatically
+   * @returns Promise<{filePath?: string; duration?: number} | null> - Recording result or null if failed
+   */
+  public async stopRecording(): Promise<{filePath?: string; duration?: number} | null> {
+    try {
+      return await this.recorder.stopRecording();
+    } catch (error) {
+      console.error('[Cuoral] Failed to stop recording:', error);
+      return null;
+    }
+  }
+
   /**
    * Open the widget modal
    */