@active-reach/web-sdk 1.14.1 → 1.19.0

package/README.md

@@ -1,6 +1,6 @@
 # @active-reach/web-sdk
 
-Web SDK for **Active Reach Intelligence** — lightweight event tracking, identity resolution, in-app messaging, web push, and inline content placements.
+Web SDK for **Active Reach Intelligence** — lightweight event tracking, identity resolution, in-app messaging (overlays, embedded cards, interactive widgets), and web push.
 
 **12KB gzipped** | **<1KB async loader** | **Zero impact on page load**
 
@@ -426,90 +426,71 @@ Copy `dist/aegis-sw.js` to your `public/` directory so the service worker is ser
 
 ---
 
-## In-App Messaging
+## In-App Messaging & Widgets
+
+Every in-app format — modals, banners, tooltips, full-screen takeovers, bottom sheets, and interactive widgets (spin-the-wheel, scratch cards, NPS/CSAT surveys, quizzes, countdown offers, star ratings, polls, multi-step forms) — is delivered through a **single entry point**: `AegisMessageRuntime`.
 
 ```typescript
-import { AegisInAppManager } from '@active-reach/web-sdk';
+import { AegisMessageRuntime } from '@active-reach/web-sdk';
 
-const inApp = new AegisInAppManager({
+const runtime = new AegisMessageRuntime({
   writeKey: 'YOUR_WRITE_KEY',
   apiHost: 'https://YOUR_CELL.activereach.ai',
-  contactId: 'user_123',
+  contactId: 'user_123',     // optional — set once the visitor is known
   organizationId: 'org_456',
+  propertyId: 'prop_789',    // the SDK install (website/app) this page is
 });
 
-await inApp.initialize();
+await runtime.initialize();
 ```
 
-Campaign display rules (modal, banner, tooltip, slide-in) are configured server-side. The SDK evaluates client-side triggers (scroll depth, time on page, exit intent, inactivity) and renders campaigns automatically.
+> **Migrating from an older version?** `AegisInAppManager`, `AegisWidgetManager`, and `AegisPlacementManager` are no longer part of the public API — `AegisMessageRuntime` is the one supported entry point and renders all formats. The standalone "placement" system has been removed; inline content is now delivered as **embedded cards** (see below).
 
----
+Campaign content, audience, schedule, and frequency caps are configured server-side in the dashboard (**In-App Personalization**). The SDK evaluates client-side triggers (scroll depth, time on page, exit intent, inactivity, custom events) and renders the matching campaign automatically.
 
-## Inline Content Placements
+### Drive triggers & identity from your app
 
 ```typescript
-import { AegisPlacementManager } from '@active-reach/web-sdk';
-
-const placements = new AegisPlacementManager({
-  writeKey: 'YOUR_WRITE_KEY',
-  apiHost: 'https://YOUR_CELL.activereach.ai',
-  contactId: 'user_123',
-  organizationId: 'org_456',
-  enableSSE: true,
-});
-
-await placements.initialize();
-
-// Register a slot in your page
-placements.registerSlot({
-  placementId: 'homepage_hero',
-  containerId: 'aegis-hero-slot',
-  fallbackContent: '<p>Loading...</p>',
-});
+runtime.track('added_to_cart');         // fire event-based display triggers
+runtime.notifyConversion('purchase');   // suppress a campaign after it converts
+await runtime.updateContactId('contact_42'); // re-evaluate once the visitor signs in
 ```
 
-Placements support banner, card, carousel, video, and HTML content types. Content is managed server-side and delivered via SSE for real-time updates.
+### Placement — how a campaign reaches the customer
 
-> **HTML Placements:** For full HTML content rendering, add [DOMPurify](https://github.com/cure53/DOMPurify) to your page. Without it, HTML placements fall back to text-only rendering.
->
-> ```html
-> <script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/3.2.4/purify.min.js"></script>
-> ```
+Each campaign picks one or more **delivery modes** in the dashboard's **Placement** tab. They are not mutually exclusive:
 
----
+| Delivery mode | What it is | What you do on your site |
+|---|---|---|
+| **Pop up (overlay)** | A modal / banner / etc. the SDK renders over the page at runtime | Nothing — `runtime.initialize()` shows it when the trigger matches |
+| **Embedded card** | The campaign renders *inline*, inside a slot you place on the page | Add an empty `<div data-aegis-slot="…">` where you want it |
+| **Standalone page** | The campaign gets its own tokenized URL (great for SMS / email / QR) | Link to the URL shown in the dashboard |
 
-## Widgets (Exit Intent, Surveys, Gamification)
+#### Embedded cards (inline placement)
 
-```typescript
-import { AegisWidgetManager, TriggerEngine } from '@active-reach/web-sdk';
+Drop an empty element wherever you want the card to appear. Its `data-aegis-slot` value must equal the campaign's **category** (`widget_category` in the dashboard). On load, the SDK fills the first eligible campaign for that category:
 
-const triggerEngine = new TriggerEngine();
-const widgets = new AegisWidgetManager({
-  writeKey: 'YOUR_WRITE_KEY',
-  apiHost: 'https://YOUR_CELL.activereach.ai',
-  contactId: 'user_123',
-  organizationId: 'org_456',
-  triggerEngine,
-  enablePrefetch: true,
-});
-
-await widgets.initialize();
+```html
+<!-- Renders the active "promo" campaign here, inline in your page -->
+<div data-aegis-slot="promo"></div>
 ```
 
-### Cart Recovery (Platform Auto-Detection)
+No per-slot script and no manual registration — `runtime.initialize()` scans for every `[data-aegis-slot]` element and fills it. It re-scans on each SSE/poll refresh and skips slots it has already filled.
+
+### Cart recovery (platform auto-detection)
 
-The SDK auto-detects cart data from:
+For cart-abandonment campaigns the widget subsystem auto-detects cart data:
 
-| Platform | Detection Method | Setup |
+| Platform | Detection method | Setup |
 |----------|-----------------|-------|
 | **Shopify** | `window.Shopify.checkout` / DOM `#cart-json` | None |
 | **WooCommerce** | `window.aegis_cart` (injected by plugin) | Install WP plugin |
 | **Magento 2** | `localStorage['mage-cache-storage']` | None |
-| **Custom / Mobile** | Manual via `setCartData()` | Required |
+| **Custom / Mobile** | Manual | Call `setCartData()` |
 
 ```typescript
-// For custom platforms only
-widgets.setCartData({
+// Custom platforms only — reach the widget subsystem via runtime.widgets
+runtime.widgets.setCartData({
   cart_id: 'cart_123',
   cart_total: 149.99,
   cart_currency: 'INR',

package/dist/aegis-sw.js

@@ -1 +1 @@
-!function(){"use strict";function i(i){self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(t=>{for(const a of t)a.postMessage(i)}).catch(()=>{})}self.addEventListener("install",()=>{self.skipWaiting()}),self.addEventListener("activate",i=>{i.waitUntil(self.clients.claim())}),self.addEventListener("push",t=>{var a,n;if(!t.data)return;let o;try{o=t.data.json()}catch{o={title:t.data.text()||"Notification"}}const e=o.title||"Notification",c={campaign_id:o.campaign_id,action_url:o.action_url||o.url,action_type:null==(a=o.data)?void 0:a.action_type,action_payload:null==(n=o.data)?void 0:n.action_payload,timestamp:Date.now()},s={body:o.body||"",icon:o.icon||void 0,badge:o.badge||void 0,image:o.image||void 0,tag:o.tag||o.campaign_id||void 0,data:c,...Array.isArray(o.actions)&&o.actions.length>0?{actions:o.actions.slice(0,2)}:{},requireInteraction:o.require_interaction??!1};t.waitUntil(self.registration.showNotification(e,s).then(()=>{i({type:"push.delivered",campaign_id:o.campaign_id})}).catch(t=>(console.error("[aegis-sw] showNotification failed, retrying minimal:",t),self.registration.showNotification(e,{body:o.body||"",data:c}).then(()=>{i({type:"push.delivered",campaign_id:o.campaign_id,degraded:!0})}).catch(i=>{console.error("[aegis-sw] minimal showNotification also failed:",i)}))))}),self.addEventListener("notificationclick",t=>{t.notification.close();const a=t.notification.data||{},n=a.action_url||"/";let o=n;if(t.action&&Array.isArray(t.notification.actions)){if(t.notification.actions.find(i=>i.action===t.action)){const i=a.action_urls||{};o=i[t.action]||n}}t.waitUntil(self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(n=>{const e=n.find(i=>new URL(i.url).origin===self.location.origin);return e?(e.postMessage({type:"push.clicked",campaign_id:a.campaign_id,action_url:o,action:t.action||"default",action_type:a.action_type,action_payload:a.action_payload}),e.focus()):(i({type:"push.clicked",campaign_id:a.campaign_id,action_url:o,action:t.action||"default",action_type:a.action_type,action_payload:a.action_payload}),self.clients.openWindow(o))}))}),self.addEventListener("notificationclose",t=>{i({type:"push.dismissed",campaign_id:(t.notification.data||{}).campaign_id})}),self.addEventListener("pushsubscriptionchange",t=>{var a,n;t.waitUntil(self.registration.pushManager.subscribe({userVisibleOnly:!0,applicationServerKey:(null==(n=null==(a=t.oldSubscription)?void 0:a.options)?void 0:n.applicationServerKey)||void 0}).then(t=>{i({type:"push.resubscribed",subscription:t.toJSON()})}).catch(i=>{console.error("[aegis-sw] Failed to resubscribe:",i)}))})}();
+!function(){"use strict";function i(i){self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(t=>{for(const o of t)o.postMessage(i)}).catch(()=>{})}self.addEventListener("install",()=>{self.skipWaiting()}),self.addEventListener("activate",i=>{i.waitUntil(self.clients.claim())}),self.addEventListener("push",t=>{if(!t.data)return;let o;try{o=t.data.json()}catch{o={title:t.data.text()||"Notification"}}const n=o.title||"Notification",e=o.data,a={campaign_id:o.campaign_id,journey_execution_id:o.journey_execution_id||(null==e?void 0:e.journey_execution_id),lifecycle_fork_id:o.lifecycle_fork_id||(null==e?void 0:e.lifecycle_fork_id),location_id:o.location_id||(null==e?void 0:e.location_id),action_url:o.action_url||o.url,action_type:null==e?void 0:e.action_type,action_payload:null==e?void 0:e.action_payload,timestamp:Date.now()},c={body:o.body||"",icon:o.icon||void 0,badge:o.badge||void 0,image:o.image||void 0,tag:o.tag||o.campaign_id||void 0,data:a,...Array.isArray(o.actions)&&o.actions.length>0?{actions:o.actions.slice(0,2)}:{},requireInteraction:o.require_interaction??!1};t.waitUntil(self.registration.showNotification(n,c).then(()=>{i({type:"push.delivered",campaign_id:o.campaign_id,journey_execution_id:a.journey_execution_id,lifecycle_fork_id:a.lifecycle_fork_id,location_id:a.location_id})}).catch(t=>(console.error("[aegis-sw] showNotification failed, retrying minimal:",t),self.registration.showNotification(n,{body:o.body||"",data:a}).then(()=>{i({type:"push.delivered",campaign_id:o.campaign_id,degraded:!0})}).catch(i=>{console.error("[aegis-sw] minimal showNotification also failed:",i)}))))}),self.addEventListener("notificationclick",t=>{t.notification.close();const o=t.notification.data||{},n=o.action_url||"/";let e=n;if(t.action&&Array.isArray(t.notification.actions)){if(t.notification.actions.find(i=>i.action===t.action)){const i=o.action_urls||{};e=i[t.action]||n}}t.waitUntil(self.clients.matchAll({type:"window",includeUncontrolled:!0}).then(n=>{const a=n.find(i=>new URL(i.url).origin===self.location.origin);return a?(a.postMessage({type:"push.clicked",campaign_id:o.campaign_id,journey_execution_id:o.journey_execution_id,lifecycle_fork_id:o.lifecycle_fork_id,location_id:o.location_id,action_url:e,action:t.action||"default",action_type:o.action_type,action_payload:o.action_payload}),a.focus()):(i({type:"push.clicked",campaign_id:o.campaign_id,action_url:e,action:t.action||"default",action_type:o.action_type,action_payload:o.action_payload}),self.clients.openWindow(e))}))}),self.addEventListener("notificationclose",t=>{const o=t.notification.data||{};i({type:"push.dismissed",campaign_id:o.campaign_id,journey_execution_id:o.journey_execution_id,lifecycle_fork_id:o.lifecycle_fork_id,location_id:o.location_id})}),self.addEventListener("pushsubscriptionchange",t=>{var o,n;t.waitUntil(self.registration.pushManager.subscribe({userVisibleOnly:!0,applicationServerKey:(null==(n=null==(o=t.oldSubscription)?void 0:o.options)?void 0:n.applicationServerKey)||void 0}).then(t=>{i({type:"push.resubscribed",subscription:t.toJSON()})}).catch(i=>{console.error("[aegis-sw] Failed to resubscribe:",i)}))})}();