JavaScript Web SDK
A lightweight, type-safe JavaScript SDK for integrating Encatch forms and surveys into your web application
A lightweight, type-safe JavaScript SDK for integrating Encatch forms and surveys into your web application.
Installation
npm install @encatch/web-sdk<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.0.0-beta.7/dist/encatch.iife.js"></script>Quick Start
import { _encatch } from '@encatch/web-sdk';
// Initialize with your API key
_encatch.init('YOUR_PUBLISHABLE_SDK_KEY');
// Identify the user
_encatch.identifyUser('user-123', {
$set: {
email: 'user@example.com',
name: 'John Doe',
},
});<script src="https://cdn.jsdelivr.net/npm/@encatch/web-sdk@1.0.0-beta.7/dist/encatch.iife.js"></script>
<script>
// The SDK is available as window._encatch
_encatch.init('YOUR_PUBLISHABLE_SDK_KEY');
_encatch.identifyUser('user-123', {
$set: {
email: 'user@example.com',
name: 'John Doe',
},
});
</script>API Reference
Initialization
Initialize the SDK with your API key. This must be called before any other methods. It triggers the loading of the remote implementation script.
_encatch.init('YOUR_PUBLISHABLE_SDK_KEY', {
webHost: 'https://custom-cdn.example.com',
theme: 'dark',
apiBaseUrl: 'https://app.encatch.com',
isFullScreen: false,
});Prop
Type
Prop
Type
User Identification
Identify the current user. The userName is required (can be a username, email, or unique identifier). Traits and options are optional.
// Simple — just ID
_encatch.identifyUser('user-123');// With traits
_encatch.identifyUser('user-123', {
$set: {
email: 'user@example.com',
name: 'John Doe',
plan: 'premium',
signed_up_at: new Date(),
},
});// With multiple operations
_encatch.identifyUser('user-123', {
$set: { email: 'user@example.com', name: 'John Doe' },
$setOnce: { firstSeenAt: new Date() },
$increment: { loginCount: 1 },
$unset: ['oldField'],
});// With options
_encatch.identifyUser('user-123', traits, {
locale: 'fr,en,es',
country: 'US',
});Prop
Type
User traits support nested 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 |
Prop
Type
Secure Identification
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.
Use the secure option when you need to verify that the identification request comes from your backend. Pass a server-generated signature (and optionally generatedDateTimeinUTC) so Encatch can validate the request. The generatedDateTimeinUTC value — the timestamp used during signature generation — ensures the signature is limited to a defined lifespan.
_encatch.identifyUser('user-123', traits, {
secure: {
signature: 'server-generated-signature',
generatedDateTimeinUTC: '2025-03-13T14:30:00.000Z', // Optional — timestamp used during signature generation; limits signature to a defined lifespan
},
});Locale
When using our centralized translation interface or language targeting, you can manually set the language of a user. If you don't set the language, the preferred web-browser languages are used instead.
The expected format is a comma-separated list of two-character ISO 639-1 codes.
As an alternative to the setLocale method, you can provide a locale option when identifying a user.
_encatch.setLocale('fr,en,es'); // Comma-separated two-character ISO 639-1 codes_encatch.identifyUser('user-123', {}, {
locale: 'fr,en,es'
});Country
When using country targeting, the country of a user is by default detected automatically using their IP address. You can choose to manually set the country of a user and thus deactivate the IP address lookup.
The expected format of the country variable is a two-character ISO 3166 country code.
We recommend calling the setCountry method right before the identifyUser method.
As an alternative to the setCountry method, you can also provide a country option when identifying a user.
_encatch.setCountry('in'); // ISO 3166 country code_encatch.identifyUser('user-123', {}, {
country: 'in'
});Theme
Set the theme for forms and surveys. Default is 'system'.
_encatch.setTheme('dark'); // 'light', 'dark', or 'system'
_encatch.setTheme('light');
_encatch.setTheme('system'); // Follows system preferenceEvent Tracking
Track a custom event.
_encatch.trackEvent('button_clicked');
_encatch.trackEvent('purchase_completed');Screen Tracking
Track a screen view.
_encatch.trackScreen('Dashboard');
_encatch.trackScreen('Checkout');Session
Manually start a new session. Useful after user login to reset session timing.
_encatch.startSession();Prop
Type
Reset User
Reset the current user (logout). Reverts the SDK to anonymous mode.
_encatch.resetUser();Show Form
Show a specific form by ID.
_encatch.showForm('form-abc-123');
_encatch.showForm('form-abc-123', { reset: 'never' });Prop
Type
Show form options:
Prop
Type
Dismiss Form
Dismiss a form and report to the server. Closes the iframe if open and calls the dismiss-form endpoint.
_encatch.dismissForm('form-config-123');Prepopulate Response
Prepopulate a form response.
_encatch.addToResponse('question-1', 'Pre-filled answer');
_encatch.addToResponse('question-2', ['option-a', 'option-b']);Event Subscription
Subscribe to all form events. The callback receives every form event with the event type and payload. Returns an unsubscribe function.
const unsubscribe = _encatch.on((eventType, payload) => {
console.log(`[Encatch] ${eventType}:`, payload);
});
// Later, to unsubscribe:
unsubscribe();| Event | Description |
|---|---|
form:show | Fired when a form is displayed |
form:started | Fired when a form is started |
form:submit | Fired when a form is submitted |
form:complete | Fired when a form is completed |
form:close | Fired when a form is closed |
form:dismissed | Fired when a form is dismissed |
form:error | Fired when an error occurs |
form:section:change | Fired when the user changes sections |
form:answered | Fired when a question is answered |
Event payload structure:
interface EventPayload {
formId?: string;
timestamp: number;
data?: Record<string, unknown>;
}Raising Issues
Github Issue Link: https://github.com/get-encatch/web-sdk