@webengage/web-sdk

Official WebEngage SDK for JavaScript/TypeScript web applications. Easily integrate WebEngage's analytics, user management, in-app notifications, surveys, web personalization, and web push into your project.

Installation

npm install @webengage/web-sdk

Quick Start

1. Initialize

Call init() once in your application's entry point (e.g., main.ts, index.js, App.tsx).

import webengage from '@webengage/web-sdk';

webengage.init('YOUR_LICENSE_CODE', 'US');

Supported Environments

| Environment | Region | |-------------|--------| | US | United States | | IN | India | | KSA | Saudi Arabia | | IRAN | Iran |

Options

You can pass an optional configuration object as the third argument:

webengage.init('YOUR_LICENSE_CODE', 'IN', {
  is_spa: true,
  direction: 'ltr',
});

| Option | Type | Description | |--------|------|-------------| | is_spa | boolean | Enable Single Page Application mode | | direction | 'ltr' \| 'rtl' | Text direction | | delay | number | Delay SDK load (ms) | | proxyUrl | string | Custom proxy URL | | is_csp | boolean | Enable Content Security Policy mode | | multiSite | boolean | Enable multi-site tracking | | httpFetch | boolean | Use HTTP fetch for requests | | visitorConsent | object | Consent settings ({ ut: boolean, aa: boolean \| string }) |

2. Use Anywhere

After initialization, import and use webengage in any file — no need to re-initialize.

import webengage from '@webengage/web-sdk';

webengage.track('Product Viewed', { productId: 'SKU123', price: 29.99 });

Note: Any calls made before init() completes are automatically queued and executed once initialization is done.

API Reference

Event Tracking

webengage.track('Event Name', { key: 'value' });

Screen Tracking

Track a screen or page view. screen() accepts either a screen name or screen/rule data:

// Screen name only
webengage.screen('Screen Name');

// Screen name with data
webengage.screen('Screen Name', { key: 'value' });

// Object as the first argument — treated as screen/rule data (no explicit name)
webengage.screen({ data: 'page' });

Note: When the first argument is a string, it is used as the screen name. When the first argument is an object, it is treated as screen/rule data used for targeting rules.

Reload

Reloads the WebEngage SDK. Useful for Single Page Applications when you need to re-evaluate targeting rules after a route change.

webengage.reload();

User

// Identify a user
webengage.user.identify('user_123');

// Login
webengage.user.login('user_123');
webengage.user.login('user_123', 'jwt_token');

// Logout
webengage.user.logout();

// Set user attributes
webengage.user.setAttribute('email', '[email protected]');
webengage.user.setAttribute({ age: 25, city: 'Mumbai' });

In-App Notifications

webengage.notification.render();
webengage.notification.clear();
webengage.notification.options('notificationId', 'NOTIFICATION_ID');

// Lifecycle callbacks
webengage.notification.onPrepare((data) => { /* notification preparing */ });
webengage.notification.onOpen((data) => { /* notification opened */ });
webengage.notification.onClick((data) => { /* notification clicked */ });
webengage.notification.onClose((data) => { /* notification closed */ });
webengage.notification.onSubmit((data) => { /* notification submitted */ });
webengage.notification.onComplete((data) => { /* notification completed */ });

Web Personalization

webengage.webpersonalization.render();
webengage.webpersonalization.clear();
webengage.webpersonalization.options('key', 'value');

// Lifecycle callbacks
webengage.webpersonalization.onPrepare((data) => {});
webengage.webpersonalization.onRender((data) => {});
webengage.webpersonalization.onView((data) => {});
webengage.webpersonalization.onOpen((data) => {});
webengage.webpersonalization.onClick((data) => {});
webengage.webpersonalization.onClose((data) => {});
webengage.webpersonalization.onSubmit((data) => {});
webengage.webpersonalization.onComplete((data) => {});

Surveys

webengage.survey.render();
webengage.survey.clear();
webengage.survey.options('surveyId', 'SURVEY_ID');

// Lifecycle callbacks
webengage.survey.onPrepare((data) => {});
webengage.survey.onOpen((data) => {});
webengage.survey.onClick((data) => {});
webengage.survey.onClose((data) => {});
webengage.survey.onSubmit((data) => {});
webengage.survey.onComplete((data) => {});

Web Push

webengage.webpush.prompt();
webengage.webpush.isSubscribed();
webengage.webpush.onSubscribe(() => { /* user subscribed */ });
webengage.webpush.isPushNotificationsSupported((supported) => { /* check support */ });

Lifecycle Hooks

webengage.onReady(() => {
  console.log('WebEngage SDK is ready');
});

webengage.onSessionStarted(() => {
  console.log('Session started');
});

Framework Examples

Angular

main.ts

import webengage from '@webengage/web-sdk';

webengage.init('YOUR_LICENSE_CODE', 'IN', { is_spa: true });

bootstrapApplication(AppComponent);

webengage.service.ts

import { Injectable } from '@angular/core';
import webengage from '@webengage/web-sdk';

@Injectable({ providedIn: 'root' })
export class WebengageService {
  track(event: string, attributes?: Record<string, any>) {
    webengage.track(event, attributes);
  }

  screen(name: string, data?: Record<string, any>) {
    webengage.screen(name, data);
  }
}

React

main.tsx

import webengage from '@webengage/web-sdk';

webengage.init('YOUR_LICENSE_CODE', 'US', { is_spa: true });

createRoot(document.getElementById('root')!).render(<App />);

Any component

import webengage from '@webengage/web-sdk';

function ProductPage() {
  useEffect(() => {
    webengage.track('Product Viewed', { productId: '123' });
    webengage.screen('Product Page');
  }, []);
}

Vanilla JavaScript

<script type="module">
  import webengage from '@webengage/web-sdk';

  webengage.init('YOUR_LICENSE_CODE', 'US');
  webengage.track('Page Loaded');
</script>

Documentation

For more details, check WebEngage Documentation.

License

ISC