@encatch/web-sdk 0.0.13

package/README.md

@@ -0,0 +1,756 @@
+# Encatch Web SDK
+
+A powerful, lightweight JavaScript SDK for collecting user feedback and running surveys on web applications. Built with Preact and TypeScript, the Encatch Web SDK provides intelligent trigger-based feedback collection with advanced targeting and frequency control.
+
+## Features
+
+- **Intelligent Triggers**: Automatically display feedback based on user behavior
+  - Page load triggers
+  - Custom event triggers
+  - Scroll-based triggers
+  - Time-delayed triggers
+- **User Session Management**: Track and manage user sessions with device fingerprinting
+- **Frequency Control**: Configure feedback display frequency and scheduling
+- **Multi-language Support**: Display feedback in multiple languages
+- **Theme Support**: Light and dark mode with custom CSS
+- **Prepopulated Answers**: Pre-fill feedback forms with known data
+- **Event Tracking**: Track user interactions and custom events
+- **TypeScript Support**: Fully typed API for better developer experience
+- **Lightweight**: Minimal bundle size with optimized performance
+
+## Installation
+
+### Via Script Tag (Recommended)
+
+Add the following script to your HTML file before the closing `</head>` tag:
+
+```html
+<script>
+  !function(){if(!window.encatch){var e={_i:[],apiKey:"",config:{host:"https://your-host.com",autoStartEnabled:!1,autoStartSessionDisabled:!0,themeMode:"light",language:"en",customCssLink:""},initialized:!1,chunkUrlLoader:function(e){return window.encatch.config.host+e},init:function(n,t){if(!("initialized"in window.encatch&&window.encatch.initialized)){if(window.encatch.apiKey=n,t?.host&&(window.encatch.config.host=t.host),t?.identity&&(window.encatch.config.identity=t.identity),void 0!==t?.autoStartSessionDisabled&&(window.encatch.config.autoStartSessionDisabled=t.autoStartSessionDisabled),void 0!==t?.processAfterIdentitySet?window.encatch.config.processAfterIdentitySet=t.processAfterIdentitySet:window.encatch.config.processAfterIdentitySet=!1,void 0!==t?.autoStartEnabled&&(window.encatch.config.autoStartEnabled=t.autoStartEnabled),t?.themeMode?window.encatch.config.themeMode=t.themeMode:window.encatch.config.themeMode="light",t?.language?window.encatch.config.language=t.language:window.encatch.config.language="en",t?.customCssLink&&(window.encatch.config.customCssLink=t.customCssLink),t?.setUser&&(window.encatch.config.setUser=t.setUser),window.encatch.initialized=!0,!import.meta.env.VITE_PATH_PREFIX||import.meta.env.VITE_PATH_PREFIX.startsWith("/")||(import.meta.env.VITE_PATH_PREFIX="/"+import.meta.env.VITE_PATH_PREFIX),import.meta.env.VITE_PATH_PREFIX=import.meta.env.VITE_PATH_PREFIX.replace(/\/+$/,""),scriptSrc=`${window.encatch.config.host}${import.meta.env.VITE_PATH_PREFIX||""}/encatch-web-sdk.js`,(script=document.createElement("script")).src=scriptSrc,script.type="module",script.async=!0,firstHeadElement=document.head.firstChild)firstHeadElement?document.head.insertBefore(script,firstHeadElement):document.head.appendChild(script);var o=document.createElement("div");o.id="enisght-root",document.body.appendChild(o)}}};window.encatch=e,["trackEvent","stop","start","setUser","setThemeMode","setLanguage","openFeedbackById","openFeedbackByName","verifyFeedbackIds","forceFetchEligibleFeedbacks","capturePageScrollEvent"].forEach((function(n){e[n]=function(){for(var t=arguments.length,o=new Array(t),i=0;i<t;i++)o[i]=arguments[i];window.encatch._i.push([n].concat(o))}}))}}();
+</script>
+```
+
+Then initialize the SDK:
+
+```html
+<script>
+  encatch.init('YOUR_API_KEY', {
+    host: 'https://your-host.com',
+    autoStartEnabled: true
+  });
+</script>
+```
+
+### Via NPM (For Module Bundlers)
+
+```bash
+npm install @encatch/web-sdk
+```
+
+```javascript
+import '@encatch/web-sdk';
+
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true
+});
+```
+
+## Quick Start
+
+### Basic Setup
+
+```javascript
+// Initialize the SDK
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  themeMode: 'light',
+  language: 'en'
+});
+
+// Set user identity (optional)
+encatch.setUser('user-123', {
+  $set: {
+    email: 'user@example.com',
+    name: 'John Doe',
+    plan: 'premium'
+  }
+});
+
+// Track custom events
+encatch.trackEvent('button_clicked', {
+  path: '/dashboard',
+  button_id: 'upgrade-button'
+});
+```
+
+### Manual Trigger
+
+```javascript
+// Open feedback by ID
+encatch.openFeedbackById('feedback-config-id-123');
+
+// Open feedback by name
+encatch.openFeedbackByName('Customer Satisfaction Survey');
+
+// With theme and language override
+encatch.openFeedbackById('feedback-config-id-123', 'dark', 'es');
+```
+
+## Configuration Options
+
+### Initialization Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | `string` | - | **Required**. The host URL for the Encatch API |
+| `autoStartEnabled` | `boolean` | `false` | Automatically start fetching eligible feedbacks |
+| `autoStartSessionDisabled` | `boolean` | `true` | Disable automatic session management |
+| `processAfterIdentitySet` | `boolean` | `false` | Wait for user identity before processing |
+| `themeMode` | `'light' \| 'dark'` | `'light'` | Default theme mode |
+| `language` | `string` | `'en'` | Default language code |
+| `customCssLink` | `string` | - | URL to custom CSS file |
+| `setUser` | `UserInfo` | - | Initial user identity |
+| `customProperties` | `Record<string, string>` | - | Custom properties for targeting |
+| `onSessionDisabled` | `(action, message) => void` | - | Callback when session functions are disabled |
+
+### Example: Complete Configuration
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  autoStartSessionDisabled: false,
+  themeMode: 'light',
+  language: 'en',
+  customCssLink: 'https://your-cdn.com/custom-theme.css',
+  setUser: {
+    userId: 'user-123',
+    traits: {
+      $set: {
+        email: 'user@example.com',
+        plan: 'premium'
+      }
+    }
+  },
+  onSessionDisabled: (action, message) => {
+    console.warn(`Session action blocked: ${action} - ${message}`);
+  }
+});
+```
+
+## API Reference
+
+### `init(apiKey, options)`
+
+Initialize the Encatch SDK.
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true
+});
+```
+
+### `start(userId?, traits?)`
+
+Start the SDK and optionally set user identity. Useful when `autoStartEnabled: false`.
+
+```javascript
+// Start without user
+encatch.start();
+
+// Start with user identity
+encatch.start('user-123', {
+  $set: {
+    email: 'user@example.com',
+    name: 'John Doe'
+  }
+});
+```
+
+### `stop()`
+
+Stop the SDK. Behavior depends on initialization:
+
+- If initialized with `autoStartEnabled: false`: Clears all data, feedbacks, and frequency tracking
+- If initialized with `autoStartEnabled: true`: Makes user anonymous but retains feedbacks
+
+```javascript
+encatch.stop();
+```
+
+### `setUser(userId?, traits?)`
+
+Set or update user identity.
+
+```javascript
+// Set user identity
+encatch.setUser('user-123', {
+  $set: { email: 'user@example.com', plan: 'premium' },
+  $set_once: { signup_date: '2024-01-01' },
+  $counter: { logins: 1 },
+  $unset: ['temp_property']
+});
+
+// Make user anonymous
+encatch.setUser();
+```
+
+#### User Traits Operators
+
+- `$set`: Set property value (overwrites existing)
+- `$set_once`: Set only if property doesn't exist
+- `$counter`: Increment counter by value
+- `$unset`: Remove properties (array of property names)
+
+### `trackEvent(eventName, properties?)`
+
+Track custom events for trigger matching.
+
+```javascript
+encatch.trackEvent('purchase_completed', {
+  path: '/checkout/success',
+  product_id: 'prod-123',
+  amount: 99.99
+});
+```
+
+### `openFeedbackById(feedbackConfigId, theme?, language?, event?, customProperties?, prepopulatedAnswers?)`
+
+Manually open a feedback form by its configuration ID.
+
+```javascript
+// Basic usage
+encatch.openFeedbackById('feedback-config-id-123');
+
+// With theme and language override
+encatch.openFeedbackById('feedback-config-id-123', 'dark', 'es');
+
+// With prepopulated answers
+encatch.openFeedbackById('feedback-config-id-123', 'light', 'en', undefined, undefined, [
+  {
+    sectionIndex: 0,
+    questionIndex: 0,
+    value: { text: 'Pre-filled answer' }
+  }
+]);
+```
+
+### `openFeedbackByName(feedbackName, theme?, language?, event?, customProperties?, prepopulatedAnswers?)`
+
+Manually open a feedback form by its name.
+
+```javascript
+encatch.openFeedbackByName('Customer Satisfaction Survey');
+
+// With options
+encatch.openFeedbackByName('NPS Survey', 'dark', 'es');
+```
+
+### `setThemeMode(theme)`
+
+Change the theme mode dynamically.
+
+```javascript
+encatch.setThemeMode('dark');
+encatch.setThemeMode('light');
+```
+
+### `setLanguage(language)`
+
+Change the language dynamically.
+
+```javascript
+encatch.setLanguage('es'); // Spanish
+encatch.setLanguage('fr'); // French
+encatch.setLanguage('en'); // English
+```
+
+### `forceFetchEligibleFeedbacks()`
+
+Force refresh the list of eligible feedbacks.
+
+```javascript
+await encatch.forceFetchEligibleFeedbacks();
+```
+
+### `verifyFeedbackIds(feedbackIds)`
+
+Verify which feedback IDs are currently eligible.
+
+```javascript
+const validIds = encatch.verifyFeedbackIds([
+  'feedback-id-1',
+  'feedback-id-2',
+  'feedback-id-3'
+]);
+console.log('Valid feedback IDs:', validIds);
+```
+
+### `capturePageScrollEvent(scrollPercent)`
+
+Manually trigger scroll-based feedback.
+
+```javascript
+// Track scroll percentage
+window.addEventListener('scroll', () => {
+  const scrollPercent = (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100;
+  encatch.capturePageScrollEvent(`${scrollPercent}%`);
+});
+```
+
+## Event Tracking
+
+### Automatic Page Tracking
+
+The SDK automatically tracks page changes in single-page applications:
+
+```javascript
+// Page changes are tracked automatically
+// Triggers "pageLoad" event for configured triggers
+```
+
+### Custom Events
+
+Track custom events for business logic:
+
+```javascript
+// E-commerce example
+encatch.trackEvent('product_viewed', {
+  path: '/products/123',
+  category: 'electronics',
+  price: 299.99
+});
+
+encatch.trackEvent('add_to_cart', {
+  path: '/products/123',
+  product_id: 'prod-123'
+});
+
+encatch.trackEvent('checkout_started', {
+  path: '/checkout',
+  cart_value: 599.98
+});
+```
+
+### Scroll Tracking
+
+```javascript
+// Automatic scroll tracking (if configured in feedback triggers)
+// Or manual tracking:
+let scrollTriggered = false;
+
+window.addEventListener('scroll', () => {
+  const scrollPercent = (window.scrollY / (document.documentElement.scrollHeight - window.innerHeight)) * 100;
+
+  if (scrollPercent > 50 && !scrollTriggered) {
+    encatch.capturePageScrollEvent('50%');
+    scrollTriggered = true;
+  }
+});
+```
+
+## Advanced Usage
+
+### Prepopulated Answers
+
+Pre-fill feedback forms with known data:
+
+```javascript
+encatch.openFeedbackById('feedback-config-id', 'light', 'en', undefined, undefined, [
+  {
+    sectionIndex: 0,  // First section
+    questionIndex: 0, // First question
+    value: { text: 'Pre-filled text answer' }
+  },
+  {
+    sectionIndex: 0,
+    questionIndex: 1,
+    value: { rating: 5 }
+  }
+]);
+```
+
+### Custom Properties for Targeting
+
+Pass custom properties for advanced targeting:
+
+```javascript
+encatch.openFeedbackById(
+  'feedback-config-id',
+  'light',
+  'en',
+  undefined,
+  {
+    user_segment: 'premium',
+    feature_flag: 'beta_features',
+    experiment_group: 'variant_a'
+  }
+);
+```
+
+### Session Management
+
+```javascript
+// Disable automatic session management
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartSessionDisabled: false
+});
+
+// Manual session control (when autoStartSessionDisabled: false)
+encatch.start(); // Start a new session
+encatch.stop();  // End current session
+```
+
+### Dynamic Theme Switching
+
+```javascript
+// Listen to system theme changes
+const darkModeQuery = window.matchMedia('(prefers-color-scheme: dark)');
+
+darkModeQuery.addEventListener('change', (e) => {
+  encatch.setThemeMode(e.matches ? 'dark' : 'light');
+});
+
+// Or use a theme toggle
+function toggleTheme() {
+  const currentTheme = getCurrentTheme(); // Your theme logic
+  encatch.setThemeMode(currentTheme === 'dark' ? 'light' : 'dark');
+}
+```
+
+### Custom CSS Styling
+
+```javascript
+// Option 1: Provide custom CSS URL during initialization
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  customCssLink: 'https://your-cdn.com/custom-encatch-theme.css'
+});
+
+// Option 2: Configure custom CSS per feedback in the Encatch dashboard
+```
+
+### Conditional Feedback Display
+
+```javascript
+// Only show feedback to premium users
+if (user.plan === 'premium') {
+  encatch.openFeedbackById('premium-user-feedback');
+}
+
+// Show different feedback based on user journey
+if (isNewUser) {
+  encatch.openFeedbackByName('Onboarding Feedback');
+} else {
+  encatch.openFeedbackByName('Feature Usage Survey');
+}
+```
+
+## Form Event Listeners
+
+The SDK provides two approaches for listening to feedback form events: **config-based** and **runtime-based**.
+
+### Available Form Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `form:submit` | `{ feedbackIdentifier: string, feedbackConfigurationId: string, completionTimeInSeconds: number, response: Object }` | Emitted when the user completes and submits the feedback form |
+| `form:view` | `{ feedbackIdentifier: string, feedbackConfigurationId: string }` | Emitted when the feedback form is displayed to the user |
+| `form:close` | `{ feedbackIdentifier: string, feedbackConfigurationId: string }` | Emitted when the user closes the feedback form (with or without submitting) |
+| `form:questionAnswered` | `{ questionId: string, answer: Object }` | Emitted when the user answers a question |
+| `form:sectionChange` | `{ sectionIndex: number }` | Emitted when the user navigates to a different section |
+| `form:error` | `{ error: string }` | Emitted when an error occurs during form interaction |
+
+### Approach 1: Config-Based (Recommended)
+
+Define event handlers during SDK initialization using the `onFormEvent` callback:
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  onFormEvent: (formEvent) => {
+    // Listen to form submission
+    formEvent.onSubmit((data) => {
+      console.log('Form submitted:', data);
+      console.log('Feedback ID:', data.feedbackIdentifier);
+      console.log('Config ID:', data.feedbackConfigurationId);
+      console.log('Completion time:', data.completionTimeInSeconds);
+
+      // Send to analytics
+      analytics.track('Feedback Submitted', {
+        feedbackId: data.feedbackIdentifier,
+        configId: data.feedbackConfigurationId
+      });
+    });
+
+    // Listen to form view
+    formEvent.onView((data) => {
+      console.log('Form viewed:', data);
+    });
+
+    // Listen to form close
+    formEvent.onClose((data) => {
+      console.log('Form closed:', data);
+    });
+
+    // Listen to question answered
+    formEvent.onQuestionAnswered((data) => {
+      console.log('Question answered:', data.questionId, data.answer);
+    });
+
+    // Listen to section change
+    formEvent.onSectionChange((data) => {
+      console.log('Section changed to:', data.sectionIndex);
+    });
+
+    // Listen to errors
+    formEvent.onError((data) => {
+      console.error('Form error:', data.error);
+    });
+  }
+});
+```
+
+### Approach 2: Runtime-Based
+
+Subscribe to events at runtime using the `encatch.on()` method:
+
+```javascript
+// Subscribe to form submission
+const unsubscribeSubmit = encatch.on('form:submit', (data) => {
+  console.log('Form submitted:', data);
+  alert(`Feedback submitted! ID: ${data.feedbackIdentifier}`);
+});
+
+// Subscribe to form view
+const unsubscribeView = encatch.on('form:view', (data) => {
+  console.log('Form viewed:', data);
+});
+
+// Subscribe to form close
+const unsubscribeClose = encatch.on('form:close', (data) => {
+  console.log('Form closed:', data);
+});
+
+// Subscribe to question answered
+const unsubscribeQuestion = encatch.on('form:questionAnswered', (data) => {
+  console.log('Question answered:', data);
+});
+
+// Subscribe to section change
+const unsubscribeSection = encatch.on('form:sectionChange', (data) => {
+  console.log('Section changed:', data);
+});
+
+// Subscribe to errors
+const unsubscribeError = encatch.on('form:error', (data) => {
+  console.error('Form error:', data);
+});
+
+// Unsubscribe when no longer needed
+unsubscribeSubmit();
+unsubscribeView();
+```
+
+### Integration Examples
+
+#### Google Analytics Integration
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  onFormEvent: (formEvent) => {
+    formEvent.onView((data) => {
+      gtag('event', 'feedback_viewed', {
+        feedback_id: data.feedbackIdentifier,
+        config_id: data.feedbackConfigurationId
+      });
+    });
+
+    formEvent.onSubmit((data) => {
+      gtag('event', 'feedback_submitted', {
+        feedback_id: data.feedbackIdentifier,
+        config_id: data.feedbackConfigurationId,
+        completion_time: data.completionTimeInSeconds
+      });
+    });
+
+    formEvent.onClose((data) => {
+      gtag('event', 'feedback_closed', {
+        feedback_id: data.feedbackIdentifier
+      });
+    });
+  }
+});
+```
+
+#### Segment Analytics Integration
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  onFormEvent: (formEvent) => {
+    formEvent.onSubmit((data) => {
+      analytics.track('Feedback Completed', {
+        feedbackId: data.feedbackIdentifier,
+        configId: data.feedbackConfigurationId,
+        duration: data.completionTimeInSeconds
+      });
+    });
+
+    formEvent.onQuestionAnswered((data) => {
+      analytics.track('Question Answered', {
+        questionId: data.questionId,
+        answerType: data.answer.answer_type
+      });
+    });
+  }
+});
+```
+
+#### Custom Data Layer (GTM)
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  onFormEvent: (formEvent) => {
+    formEvent.onSubmit((data) => {
+      window.dataLayer = window.dataLayer || [];
+      window.dataLayer.push({
+        event: 'feedback_submitted',
+        feedbackId: data.feedbackIdentifier,
+        configId: data.feedbackConfigurationId,
+        completionTime: data.completionTimeInSeconds
+      });
+    });
+  }
+});
+```
+
+#### CRM Integration (e.g., Salesforce, HubSpot)
+
+```javascript
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  onFormEvent: (formEvent) => {
+    formEvent.onSubmit(async (data) => {
+      // Send to your CRM
+      await fetch('https://your-crm.com/api/feedback', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          feedbackId: data.feedbackIdentifier,
+          userId: window.currentUserId,
+          response: data.response,
+          timestamp: new Date().toISOString()
+        })
+      });
+    });
+  }
+});
+```
+
+## TypeScript Support
+
+The SDK is fully typed. TypeScript definitions are included:
+
+```typescript
+import '@encatch/web-sdk';
+
+// All methods are typed
+encatch.init('YOUR_API_KEY', {
+  host: 'https://your-host.com',
+  autoStartEnabled: true,
+  themeMode: 'light', // Type: 'light' | 'dark'
+  language: 'en'
+});
+
+// User traits are typed
+encatch.setUser('user-123', {
+  $set: { email: 'user@example.com' },
+  $set_once: { signup_date: '2024-01-01' },
+  $counter: { logins: 1 },
+  $unset: ['temp_field']
+});
+
+// Event properties are typed
+encatch.trackEvent('custom_event', {
+  path: '/page',
+  event: 'click'
+});
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- pnpm
+
+### Setup
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+### Project Structure
+
+```
+packages/web-sdk/
+├── src/
+│   ├── @types/          # TypeScript type definitions
+│   ├── hooks/           # Preact hooks for functionality
+│   ├── utils/           # Utility functions
+│   ├── index.tsx        # Main SDK initialization
+│   ├── core-wrapper.tsx # Core SDK logic
+│   └── surveySDK.ts     # Event SDK
+├── dist-sdk/            # Build output
+├── package.json
+├── vite.config.ts       # Vite configuration
+└── README.md
+```
+
+### Build Output
+
+The build produces:
+
+- `encatch-web-sdk.js` - Main SDK bundle
+- `encatch-web-sdk.css` - Default styles
+- `preview-sdk.js` - Preview/demo version
+- `embedded-sdk.js` - Embedded version
+
+## Browser Support
+
+- Chrome 62+
+- Firefox 59+
+- Safari 12+
+- iOS Safari 10.3+
+- Opera 50+
+- Edge (Chromium-based)
+
+## License
+
+Private - Copyright (c) Encatch
+
+## Support
+
+For issues, questions, or feature requests, please contact your Encatch account manager or visit the [Encatch Dashboard](https://app.encatch.com).