JavaScript Web SDK
Complete integration guide for the Encatch Web SDK — in-app feedback and survey collection for websites and web apps
The Encatch Web SDK lets you collect in-app feedback and surveys on your website. Display forms in a built-in modal iframe, identify users, track pages and events, and submit responses to the Encatch backend.
Overview
- Package:
@encatch/web-sdk - Version: 1.3.0
- Platforms: Modern browsers (Chrome, Firefox, Safari, Edge)
- Repository: github.com/get-encatch/web-sdk
Prerequisites
- Publishable SDK key — Create a key in Publishable SDK Keys. Your site's domain must be listed under Allowed Domains / Packages.
- Form ID — Use the form slug or ID from the Encatch dashboard in
showForm().
Installation
npm install @encatch/web-sdkyarn add @encatch/web-sdkpnpm add @encatch/web-sdkPin the CDN version to the same @encatch/web-sdk version you use from npm.
<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.3.0/dist/encatch.iife.js"></script>Call init() as early as possible in the page lifecycle. Commands issued before the remote implementation script loads are queued automatically.
Quick Start
1. Initialization
Initialize the SDK with your publishable API key, start a session, and show a form.
import { _encatch } from '@encatch/web-sdk';
_encatch.init('your-api-key');
_encatch.startSession();
_encatch.showForm('your-form-slug');<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.3.0/dist/encatch.iife.js"></script>
<script>
_encatch.init('your-api-key');
_encatch.startSession();
_encatch.showForm('your-form-slug');
</script>Only the first init() call runs — subsequent calls are ignored. After a successful identifyUser(), the SDK starts a session automatically; you do not need startSession() before identify.
Pass an optional config object to customize SDK behavior:
import { _encatch } from '@encatch/web-sdk';
_encatch.init('your-api-key', {
theme: 'system',
apiBaseUrl: 'https://app.encatch.com',
onBeforeShowForm: async (payload) => {
// Return false to prevent the built-in iframe from showing
return true;
},
});<script>
_encatch.init('your-api-key', {
theme: 'system',
apiBaseUrl: 'https://app.encatch.com',
onBeforeShowForm: async (payload) => {
return true;
},
});
</script>Prop
Type
2. Identify users
Identify the current user. The userName is required (can be a username, email, or unique identifier). Traits and options are optional.
_encatch.identifyUser('user@example.com');_encatch.identifyUser('user@example.com', {
$set: { name: 'Alice', plan: 'team' },
});_encatch.identifyUser('user@example.com', {
$set: { name: 'Alice', plan: 'team' },
$setOnce: { firstSeen: new Date().toISOString() },
$increment: { loginCount: 1 },
$decrement: { credits: 5 },
$unset: ['trialEndDate'],
});Prop
Type
User traits support the following operations:
| Operation | Description |
|---|---|
$set | Set user attributes (overwrites existing values) |
$setOnce | Set user attributes only if they don't already exist |
$increment | Increment numeric user attributes |
$decrement | Decrement numeric user attributes |
$unset | Remove user attributes |
Recommended
Using the secure option with a server-generated signature is recommended to verify that identification requests come from your backend. Keep your secret key on the server only — never expose it in client-side code.
Pass a server-generated HMAC signature so Encatch can validate the request. The generatedDateTimeinUTC timestamp limits the signature's lifespan.
_encatch.identifyUser('user@example.com', undefined, {
secure: {
signature: 'your-hmac-signature',
generatedDateTimeinUTC: '2025-03-13T12:00:00Z',
},
});3. Show a form manually
Show a specific form by slug or ID.
_encatch.showForm('feedback-form');
_encatch.showForm('feedback-form', { reset: 'always' });Prop
Type
Prop
Type
| Reset mode | Behavior |
|---|---|
'always' | Reset pre-fill and response data on every form display |
'on-complete' | Reset only after the form is completed |
'never' | Never reset response data |
Pass caller context when showing a form:
_encatch.showForm('feedback-form', {
reset: 'always',
context: { plan: 'team', feature: 'checkout' },
});The context object is exposed as context.* in Logic jumps Start conditions.
Other actions
Full-screen / Inline mode
Not available at the moment.
Build Your Own Form UX & UI
If your feedback flow uses a fixed, predictable question set — the same fields and workflow every time — you can build the form with your own HTML/CSS/JS and submit responses through the SDK. That keeps typography, spacing, colors, and interaction patterns aligned with the rest of your site, so the survey feels like part of your app rather than an embedded iframe.
Example coming soon.
Content Security Policy
If your site uses CSP headers, whitelist Encatch for SDK loading, HTTP API calls, and the form iframe. Add the CDN host only when you install through the script tag.
Content-Security-Policy:
script-src 'self' https://app.encatch.com https://cdn.jsdelivr.net;
connect-src 'self' https://app.encatch.com; /* fetch/XHR API calls */
frame-src 'self' https://app.encatch.com;The form's CSS loads inside the Encatch iframe. If your CSP blocks inline styles and the modal wrapper is not positioned correctly, allow inline styles in style-src for the host page.
If you configure a custom webHost, whitelist that host instead of https://app.encatch.com for script loading.
Support
- npm: @encatch/web-sdk
- Issues: github.com/get-encatch/web-sdk/issues
Was this page helpful?