Welcome to Encatch Docs
SDK Guide

JavaScript Web SDK

Complete integration guide for the encatch JavaScript SDK with advanced configuration options and best practices

The encatch JavaScript SDK provides seamless integration for web applications, enabling automated feedback collection and analytics with minimal setup.

Quick Start

Get encatch running in your application in under 5 minutes with below steps.

Installation & Initialization

Install the encatch JavaScript SDK using your preferred package manager:

npm install @encatch/web-sdk

After installation, import and initialize the SDK in your application:

import { Encatch } from '@encatch/web-sdk';

// Initialize the SDK
const encatch = new Encatch();
encatch.init('<YOUR_PROJECT_API_KEY>');

Add the following script to the <head> section of your HTML, preferably just before the closing </head> tag. Replace <your_project_api_key> with your actual project API key from the encatch dashboard.

<html>
    <head>
        ....other head content
        <script type="module">
            (function(){window.encatch||(window.encatch={_i:[],apiKey:"",config:{host:void 0,isAutoCaptureEnabled:!0,themeMode:"light",language:"en"},initialized:!1,chunkUrlLoader:i=>window.encatch.config.host+i,init(i,e){if(window.encatch.initialized)return;window.encatch.apiKey=i,e!=null&&e.host&&(window.encatch.config.host=e.host),e!=null&&e.identity&&(window.encatch.config.identity=e.identity),(e==null?void 0:e.processAfterIdentitySet)!==void 0?window.encatch.config.processAfterIdentitySet=e.processAfterIdentitySet:window.encatch.config.processAfterIdentitySet=!1,(e==null?void 0:e.isAutoCaptureEnabled)!==void 0&&(window.encatch.config.isAutoCaptureEnabled=e.isAutoCaptureEnabled),e!=null&&e.themeMode?window.encatch.config.themeMode=e.themeMode:window.encatch.config.themeMode="light",e!=null&&e.language?window.encatch.config.language=e.language:window.encatch.config.language="en",window.encatch.initialized=!0;const g=`${window.encatch.config.host}/plugin/sdk/encatch-web-sdk.js`,t=document.createElement("script");t.src=g,t.type="module",t.async=!0;const n=document.head.firstChild;n?document.head.insertBefore(t,n):document.head.appendChild(t);const d=document.createElement("div");d.id="enisght-root",document.body.appendChild(d)}},["trackEvent","stopSession","identify","resetSession","openFeedbackById","openFeedbackByName","setThemeMode","setLanguage","verifyFeedbackIds","forceFetchEligibleFeedbacks","capturePageScrollEvent"].forEach(i=>{window.encatch[i]=(...e)=>{window.encatch._i.push([i,...e])}}))})();
            encatch.init('<YOUR_PROJECT_API_KEY>');
        </script>
    </head>
<body>
    ....other body content
</body>
</html>

Note on Server Side Rendering Frameworks (SSR)

encatch web is a client side SDK and relies on window object to be available. So ensure it is not used in server side components.

For enterprise version

encatch.init('<YOUR_PROJECT_API_KEY>', {
  host: 'https://your-encatch-instance'
});

How to use

Getting the encatch instance

Post Initialization, you need to get the encatch instance.

const encatch = Encatch.getInstance();

SDK Lifecycle Management

The Encatch Web SDK provides flexible lifecycle control through the autoStartEnabled configuration flag and the start() / stop() methods.

User Identification

The Encatch Web SDK provides a powerful user identification system through the setUser() method. This allows you to track users across sessions, associate feedback with specific users, and manage user properties with advanced operators for counters, one-time values, and property removal.

Method: encatch.setUser(userId?, traits?)

Identifies a user or makes them anonymous.

Parameters:

Prop

Type

User Identity Structure

Every user in Encatch has two components:

{
  userName: string,      // Unique identifier (typically email or user ID)
  properties: {          // User traits and attributes
    $set?: {...},        // Properties to set/update
    $set_once?: {...},   // Properties to set only once
    $counter?: {...},    // Numeric counters (increment/decrement)
    $unset?: [...],      // Properties to remove
  }
}

Anonymous vs Identified Users

  • Anonymous User: No userName or userName: "" - feedback is tracked but not associated with a specific identity
  • Identified User: Has a userName - feedback is associated with this user across sessions and devices
// Basic identification with just user ID
encatch.setUser("user_12345");

// Identification with email
encatch.setUser("user@example.com");
// Call setUser() with no parameters
encatch.setUser();

// Or explicitly pass undefined
encatch.setUser(undefined);

What happens:

  • User identification is cleared
  • User becomes anonymous: { userName: "", properties: {} }
  • Feedback configuration is re-fetched for anonymous context
  • Previous user data is removed from localStorage
// Identification with properties
encatch.setUser("user@example.com", {
  $set: {
    name: "John Doe",
    plan: "premium",
    email: "user@example.com"
  }
});

Set or Update Properties

Sets properties on the user profile. If the property already exists, it will be overwritten.

encatch.setUser("user@example.com", {
  $set: {
    name: "John Doe",
    email: "user@example.com",
    plan: "premium",
    lastLogin: "2024-01-15T10:30:00Z",
    preferences: {
      theme: "dark",
      language: "en",
      notifications: true
    },
    metadata: {
      source: "web",
      version: "2.1.0"
    }
  }
});

Use Cases:

  • User profile information (name, email, company)
  • Current subscription tier or plan
  • User preferences and settings
  • Last activity timestamps
  • Any property that should be updated on each call

Behavior:

  • Overwrites existing values
  • Creates new properties if they don't exist
  • Supports nested objects
  • Supports any data type (string, number, boolean, object, array)

Set Properties Only Once

Sets properties only if they don't already exist. Will NOT overwrite existing values.

encatch.setUser("user@example.com", {
  $set_once: {
    firstSeen: "2024-01-01T00:00:00Z",
    signupMethod: "oauth",
    registrationSource: "google",
    originalReferrer: "https://google.com",
    initialPlan: "free"
  }
});

Use Cases:

  • First seen / registration date
  • Signup method (oauth, email, etc.)
  • Original traffic source / UTM parameters
  • Initial subscription tier
  • Any immutable property that should never change

Behavior:

  • Sets value only if property doesn't exist
  • Does NOT overwrite if property already exists
  • Perfect for tracking "first time" data

Example Sequence:

// First call - sets the property
encatch.setUser("user@example.com", {
  $set_once: { signupMethod: "email" }
});
// Result: signupMethod = "email"

// Second call - does NOT overwrite
encatch.setUser("user@example.com", {
  $set_once: { signupMethod: "oauth" }
});
// Result: signupMethod = "email" (unchanged)

Increment/Decrement Numeric Values

Maintains numeric counters that can be incremented or decremented.

encatch.setUser("user@example.com", {
  $counter: {
    feedbackCount: 1,      // Increment by 1
    loginCount: 1,         // Increment by 1
    pageViews: 5,          // Increment by 5
    sessionCount: 1,       // Increment by 1
    errorCount: -1         // Decrement by 1
  }
});

Use Cases:

  • Track number of feedbacks submitted
  • Count login sessions
  • Track page views
  • Count feature usage
  • Track errors or failures (using negative values to decrement)

Behavior:

  • Adds to existing value (or creates with initial value if doesn't exist)
  • Supports positive values (increment)
  • Supports negative values (decrement)
  • Server-side aggregation ensures accurate counts

Example Sequence:

// Initial call
encatch.setUser("user@example.com", {
  $counter: { loginCount: 1 }
});
// Result: loginCount = 1

// Second call
encatch.setUser("user@example.com", {
  $counter: { loginCount: 1 }
});
// Result: loginCount = 2

// Decrementing
encatch.setUser("user@example.com", {
  $counter: { credits: 10 }
});
// Result: credits = 10

encatch.setUser("user@example.com", {
  $counter: { credits: -3 }
});
// Result: credits = 7

Remove Properties

Removes properties from the user profile.

encatch.setUser("user@example.com", {
  $unset: ["trialFlag", "onboardingComplete", "temporaryData"]
});

Use Cases:

  • Remove temporary flags
  • Clean up completed onboarding state
  • Remove expired trial indicators
  • Delete obsolete properties

Behavior:

  • Removes specified properties from user profile
  • No error if property doesn't exist
  • Accepts array of property names (strings)

You can use multiple operators in a single setUser() call:

encatch.setUser("user@example.com", {
  // Set regular properties
  $set: {
    lastLogin: new Date().toISOString(),
    currentPlan: "premium",
    status: "active"
  },

  // Set properties only once
  $set_once: {
    firstSeen: "2024-01-01T00:00:00Z",
    signupMethod: "oauth"
  },

  // Increment counters
  $counter: {
    loginCount: 1,
    pageViews: 1,
    sessionCount: 1
  },

  // Remove obsolete properties
  $unset: ["trialExpired", "onboardingStep"]
});

Custom Properties with Feedback Submission

Attach custom metadata to feedback submissions. Send additional context like feature names, user segments, experiment IDs, or any key-value data with each feedback.

Important: All property values must be strings. Convert numbers, booleans, and other types to strings before passing them.

Triggers

The encatch SDK provides comprehensive event tracking capabilities with four distinct approaches: automatic event capture for common interactions, custom event tracking for business-specific metrics, scroll event tracking for engagement analysis, and manual feedback control for programmatic trigger management.

UI Customization

Dynamically control the appearance and localization of feedback forms and interfaces.

Feedback Event Listeners

Listen to form interactions in real-time. Track when users view, submit, close forms, change sections, answer questions, or encounter errors.

Two Ways to Subscribe:

  1. Configuration-time - Register during SDK initialization (simple, automatic cleanup)
  2. Runtime - Register anytime with encatch.on() (flexible, component-scoped)

Custom CSS Styling

Customize the appearance of feedback forms by providing your own CSS stylesheet URL. Override default styles to match your brand's design system.

Prepopulated Answers

Override default form behavior by prepopulating questions with predefined answers. Useful for carrying context from your application into the feedback form.

Note: Prepopulated answers are displayed to users as editable values. Users can modify or keep the prepopulated data before submitting the form.

Advanced SDK Methods

How is this guide?

Quick Start

Welcome to Encatch! This guide will help you get started with our comprehensive development platform. Choose your path below to begin building powerful applications with our tools and services.

Flutter SDK

Complete integration guide for the encatch Flutter SDK with comprehensive features for user feedback collection, analytics, and session management

On this page

Quick StartInstallation & InitializationFor enterprise versionHow to useGetting the encatch instanceSDK Lifecycle ManagementUser IdentificationCustom Properties with Feedback SubmissionTriggersUI CustomizationFeedback Event ListenersCustom CSS StylingPrepopulated AnswersAdvanced SDK Methods