Web SDK Reference

Auto-generated from libs/web-sdk/src/ — version 1.14.1.

This reference is generated at build time from the SDK source code. Method signatures are always in sync with the latest published version.

Core methods (`Aegis`)

Method	Signature	Description
`init`	`async init(writeKey: string, config?: Partial<AegisConfig>): Promise<void>`	Initialize the SDK with your write key and optional config.
`track`	`track(eventName: string, properties?: Record<string, any>): void`	Track a custom event with optional properties.
`identify`	`identify(userId: string, traits?: Record<string, any>): void`	Identify a user by ID and set traits (name, email, etc.).
`page`	`page(name?: string, properties?: Record<string, any>): void`	Track a page view. Called automatically if `auto_page_view` is enabled.
`group`	`group(groupId: string, traits?: Record<string, any>): void`	Associate the current user with a group (company, account).
`alias`	`alias(newUserId: string): void`	Merge an anonymous session with an identified user ID.
`reset`	`reset(): void`	Clear the current user identity and start a fresh anonymous session.
`flush`	`async flush(): Promise<void>`	Manually flush all queued events to the server.
`getAnonymousId`	`getAnonymousId(): string	null`
`getUserId`	`getUserId(): string	null`
`getSessionId`	`getSessionId(): string	null`
`debug`	`debug(enable?: boolean): void`	Enable or disable console debug logging.
`use`	`use(plugin: Plugin): void`	Register a plugin for event transformation.
`setWorkspace`	`setWorkspace(code: string): void`	(1.14.0) Pin the runtime workspace code; persists in sessionStorage.
`clearWorkspace`	`clearWorkspace(): void`	(1.14.0) Clear the runtime workspace and remove the sessionStorage entry.
`ingestWorkspaceCodes`	`ingestWorkspaceCodes(codes: string[]): void`	(1.14.0) Seed the workspace-code allowlist used for URL-path-segment resolution. Bootstrap fills this automatically.
`getEffectiveWorkspaceId`	`getEffectiveWorkspaceId(): string \| undefined`	(1.14.0) Return the workspace ID resolved through the cascade (config → ?ws= → URL path → runtime → sessionStorage).
`setConsent`	`setConsent(preferences: Partial<ConsentPreferences>): void`	Set consent preferences (analytics, marketing, functional).
`grantConsent`	`grantConsent(category?: ConsentCategory): void`	Grant consent for a specific category or all categories.
`denyConsent`	`denyConsent(category?: ConsentCategory): void`	Deny consent for a specific category or all categories.
`hasConsent`	`hasConsent(category: ConsentCategory): boolean`	Check if consent is granted for a specific category.
`getConsentPreferences`	`getConsentPreferences(): ConsentPreferences	null`
`onConsentChange`	`onConsentChange(callback: (prefs: ConsentPreferences) => void): () => void`	Register a callback for consent preference changes. Returns an unsubscribe function.
`destroy`	`destroy(): void`	Tear down the SDK — flush events, clear timers, remove listeners.

E-commerce tracking (`Aegis.ecommerce`)

Access via Aegis.ecommerce.productViewed(...) after initialization.

Method	Signature	Description
`productViewed`	`productViewed(product: EcommerceProduct): void`	Track a product detail page view.
`productListViewed`	`productListViewed(list: EcommerceProductList): void`	Track a product list/category view.
`productClicked`	`productClicked(product: EcommerceProduct, source?): void`	Track a product click from a list.
`searchPerformed`	`searchPerformed(search: EcommerceSearch): void`	Track a site search query.
`addToCart`	`addToCart(product: EcommerceProduct): void`	Track an add-to-cart action.
`removeFromCart`	`removeFromCart(product: EcommerceProduct): void`	Track a remove-from-cart action.
`cartViewed`	`cartViewed(cart: EcommerceCart): void`	Track a cart page view.
`checkoutStarted`	`checkoutStarted(checkout: EcommerceCheckout): void`	Track checkout initiation.
`orderCompleted`	`orderCompleted(order: EcommerceOrder): void`	Track a completed order.
`orderRefunded`	`orderRefunded(orderId: string, value?: number): void`	Track an order refund.
`couponApplied`	`couponApplied(coupon: EcommerceCoupon): void`	Track a coupon/promo code application.
`wishlistItemAdded`	`wishlistItemAdded(wishlist: EcommerceWishlist): void`	Track adding an item to a wishlist.
`promotionViewed`	`promotionViewed(promo: EcommercePromotion): void`	Track a promotion banner view.
`promotionClicked`	`promotionClicked(promo: EcommercePromotion): void`	Track a promotion banner click.

Web Push (`AegisWebPush`)

Import from @active-reach/web-sdk/push.

Method	Signature	Description
`initialize`	`async initialize(): Promise<void>`	Initialize web push — registers service worker and checks permission.
`requestPermission`	`async requestPermission(): Promise<boolean>`	Request push notification permission from the user.
`identify`	`async identify(params: ContactIdentity): Promise<void>`	Associate the push subscription with a contact identity.
`logout`	`async logout(): Promise<void>`	Unlink the push subscription from the current user.

React integration

Import from @active-reach/web-sdk/react.

Method	Signature	Description
`AegisProvider`	`React.FC<{ writeKey, config, children }>`	React context provider — wraps your app and initializes the SDK.
`useAegis`	`(): AegisContextValue`	Hook to access the SDK instance and user identity.
`useTrackEvent`	`(): (event: string, props?) => void`	Hook that returns a `track()` function bound to the current SDK instance.
`usePageView`	`(name?, props?, deps?) => void`	Hook that fires `page()` on mount and when dependencies change.
`useIdentifyUser`	`(): (userId: string, traits?) => void`	Hook that returns an `identify()` function bound to the current SDK instance.

Configuration options

Passed to Aegis.init(writeKey, config).

Option	Type	Default	Description
`workspace_id`	`string`	`Required`	Your workspace ID from Settings → Developer
`api_host`	`string`	`Auto-detected`	API endpoint — resolved per region automatically
`preferred_region`	`string`	`Auto`	Data residency region (IN, US, EU, APAC)
`auto_region_detection`	`boolean`	`true`	Detect region from Cloudflare headers
`batch_size`	`number`	`10`	Events per batch before sending
`batch_interval`	`number`	`1000`	Milliseconds between batch sends
`capture_utm`	`boolean`	`true`	Auto-capture UTM parameters from URL
`capture_referrer`	`boolean`	`true`	Auto-capture document referrer
`auto_page_view`	`boolean`	`false`	Automatically track page views on navigation
`session_timeout`	`number`	`30`	Session timeout in minutes
`debug`	`boolean`	`false`	Enable console debug logging
`respect_dnt`	`boolean`	`true`	Honor browser Do Not Track signal
`cross_domain_tracking`	`boolean`	`false`	Enable cross-domain user tracking
`cookie_domain`	`string`	`Current domain`	Cookie domain for cross-subdomain tracking
`secure_cookie`	`boolean`	`true`	Set Secure + HttpOnly flags on cookies
`enable_offline_mode`	`boolean`	`true`	Queue events when the browser is offline
`max_offline_events`	`number`	`100`	Max queued events during offline mode
`retry_failed_requests`	`boolean`	`true`	Auto-retry failed event batches
`max_retries`	`number`	`3`	Max retry attempts per failed batch
`retry_backoff_multiplier`	`number`	`2`	Exponential backoff multiplier between retries
`request_timeout`	`number`	`5000`	HTTP request timeout in milliseconds
`rate_limit_burst`	`number`	`100`	Client-side rate limiter — burst capacity (token bucket)
`rate_limit_per_second`	`number`	`20`	Client-side rate limiter — sustained tokens per second
`wait_for_consent`	`boolean`	`false`	Defer all event sending until consent is granted
`enable_consent_mode`	`boolean`	`false`	Enable GDPR/CCPA consent mode
`integrate_onetrust`	`boolean`	`false`	Auto-integrate with OneTrust consent manager
`integrate_cookiebot`	`boolean`	`false`	Auto-integrate with Cookiebot consent manager
`integrate_google_consent_mode`	`boolean`	`false`	Auto-integrate with Google Consent Mode v2
`push.vapidPublicKey`	`string`	`—`	VAPID public key for Web Push subscription
`push.autoPrompt`	`boolean`	`false`	Automatically prompt for push permission
`push.promptDelay`	`number`	`5000`	Delay in ms before auto-prompt appears
`push.serviceWorkerPath`	`string`	`'/aegis-sw.js'`	Path to the push service worker file

In-app messaging + widgets

The single entry point is AegisMessageRuntime. Construct once per page, call initialize(), swap identity with updateContactId(id), and tear down with destroy(). The runtime exposes the in-app and widget managers as readonly props — they are intentionally NOT barrel-exported.


import { AegisMessageRuntime } from '@active-reach/web-sdk';
 
const runtime = new AegisMessageRuntime({ /* config */ });
await runtime.initialize();
 
runtime.inApp.show('campaign_123');
runtime.widgets.render(/* widget config */);
runtime.notifyConversion('checkout'); // G1 frequency_cap seam — also silences
                                      // journey-queued cart-recovery touches.

Campaign types (impression): modal, banner, tooltip, full_screen, half_interstitial, alert, pip.

Interactive: spin_wheel, scratch_card, nps_survey, quiz, countdown_offer, star_rating, quick_poll, multi_step_form.

Contextual: carousel_cards, sticky_bar, progress_bar, coachmark_tour, product_recommendation.

Placements

The AegisPlacementManager renders inline content in DOM slots. Content types: banner, card, carousel, video, html, dynamic_injection.

Trigger engine

Client-side triggers that fire actions based on user behavior: scroll_depth, time_on_page, exit_intent, inactivity, scroll_velocity, visibility_change, back_button.

Last generated: 2026-04-17T08:57:03.098Z