|
4 | 4 |
|
5 | 5 | **A lightweight, explainable client-side experience runtime built on [@lytics/sdk-kit](https://github.com/lytics/sdk-kit)** |
6 | 6 |
|
7 | | -Experience SDK decides if/when/why experiences (banners, modals, tooltips) should render. Every decision comes with structured reasons, making debugging and testing effortless. |
| 7 | +Experience SDK enables marketers and developers to create personalized experiences (modals, banners, inline content) with powerful targeting and explainability. Every decision comes with structured reasons, making debugging and testing effortless. |
8 | 8 |
|
9 | 9 | ## Features |
10 | 10 |
|
11 | 11 | - 🔍 **Explainability-First** - Every decision includes structured reasons |
12 | 12 | - 🧩 **Plugin-Based** - Built on @lytics/sdk-kit's powerful plugin system |
13 | | -- 📦 **Script Tag Ready** - Works without build tools |
| 13 | +- 🎨 **Presentation Plugins** - Modal, banner, and inline content rendering |
| 14 | +- 📝 **Built-in Forms** - Email capture, surveys, feedback with validation |
| 15 | +- 🎯 **Smart Triggers** - Exit intent, scroll depth, time delay, page visits |
| 16 | +- 📦 **Script Tag Ready** - Works without build tools (marketers love it!) |
| 17 | +- 💅 **CSS Variables** - Easy theming with CSS custom properties |
14 | 18 | - 🎯 **Type-Safe** - Full TypeScript support |
15 | | -- 🪶 **Lightweight** - < 15KB gzipped |
| 19 | +- 🪶 **Lightweight** - ~26KB gzipped with all plugins (13.4KB core) |
16 | 20 | - 🔧 **Developer-Friendly** - Built for inspection and debugging |
17 | 21 |
|
18 | 22 | ## Quick Start |
19 | 23 |
|
20 | | -### Script Tag |
| 24 | +### Script Tag (For Marketers) |
21 | 25 |
|
22 | 26 | ```html |
23 | | -<script src="https://sdk.prosdevlab.com/experience-sdk.min.js"></script> |
| 27 | +<script src="https://cdn.jsdelivr.net/npm/@prosdevlab/experience-sdk@latest/dist/experience-sdk.global.js"></script> |
24 | 28 | <script> |
25 | 29 | // Initialize |
26 | 30 | experiences.init({ debug: true }); |
27 | 31 | |
28 | | - // Register an experience |
29 | | - experiences.register('welcome-banner', { |
30 | | - type: 'banner', |
| 32 | + // Exit intent modal with email capture |
| 33 | + experiences.register('exit-intent-modal', { |
| 34 | + type: 'modal', |
| 35 | + content: { |
| 36 | + title: '🚀 Wait! Before You Go...', |
| 37 | + message: 'Join 10,000+ subscribers for exclusive content', |
| 38 | + form: { |
| 39 | + fields: [ |
| 40 | + { name: 'email', type: 'email', label: 'Email', required: true } |
| 41 | + ], |
| 42 | + submitButton: { text: 'Subscribe', variant: 'primary' } |
| 43 | + } |
| 44 | + }, |
31 | 45 | targeting: { |
32 | | - url: { contains: '/' }, |
33 | | - frequency: { max: 1, per: 'session' } |
| 46 | + url: { contains: '/pricing' } |
34 | 47 | }, |
35 | | - content: { |
36 | | - title: 'Welcome!', |
37 | | - message: 'Thanks for visiting.' |
| 48 | + display: { |
| 49 | + trigger: 'exitIntent', |
| 50 | + frequency: { max: 1, per: 'session' } |
38 | 51 | } |
39 | 52 | }); |
40 | 53 | |
41 | | - // Evaluate (shows if rules match) |
42 | | - const decision = experiences.evaluate(); |
43 | | - |
44 | | - // See why |
45 | | - console.log(decision.reasons); |
46 | | - // ['✅ URL contains "/"', '✅ Not shown this session (0/1)'] |
| 54 | + // Listen for form submissions |
| 55 | + experiences.on('experiences:modal:form:submit', (event) => { |
| 56 | + console.log('Email submitted:', event.formData.email); |
| 57 | + // Send to your API, analytics, etc. |
| 58 | + }); |
47 | 59 | </script> |
48 | 60 | ``` |
49 | 61 |
|
50 | | -### npm |
| 62 | +### npm (For Developers) |
51 | 63 |
|
52 | 64 | ```bash |
53 | | -npm install @prosdevlab/experience-sdk |
| 65 | +npm install @prosdevlab/experience-sdk @prosdevlab/experience-sdk-plugins |
54 | 66 | ``` |
55 | 67 |
|
56 | 68 | ```typescript |
57 | | -import experiences from '@prosdevlab/experience-sdk'; |
| 69 | +import { createInstance } from '@prosdevlab/experience-sdk'; |
| 70 | +import { modalPlugin, inlinePlugin, bannerPlugin } from '@prosdevlab/experience-sdk-plugins'; |
| 71 | + |
| 72 | +const sdk = createInstance({ debug: true }); |
| 73 | + |
| 74 | +// Use plugins |
| 75 | +sdk.use(modalPlugin); |
| 76 | +sdk.use(inlinePlugin); |
| 77 | +sdk.use(bannerPlugin); |
| 78 | + |
| 79 | +// Register experiences |
| 80 | +sdk.register('feature-tip', { |
| 81 | + type: 'inline', |
| 82 | + content: { |
| 83 | + selector: '#feature-section', |
| 84 | + position: 'after', |
| 85 | + message: '<div>💡 New: Check out our analytics dashboard!</div>' |
| 86 | + }, |
| 87 | + display: { |
| 88 | + trigger: 'scrollDepth', |
| 89 | + triggerData: { threshold: 50 } |
| 90 | + } |
| 91 | +}); |
58 | 92 |
|
59 | | -experiences.init({ debug: true }); |
60 | | -experiences.register('welcome', { ... }); |
61 | | -const decision = experiences.evaluate(); |
| 93 | +// Listen to events |
| 94 | +sdk.on('experiences:shown', (event) => { |
| 95 | + analytics.track('Experience Shown', { id: event.experienceId }); |
| 96 | +}); |
62 | 97 | ``` |
63 | 98 |
|
64 | 99 | ### Event-Driven Architecture |
@@ -90,18 +125,38 @@ See the [Events Reference](https://your-docs-url/api/events) for comprehensive d |
90 | 125 |
|
91 | 126 | ## Documentation |
92 | 127 |
|
93 | | -See [notes/IMPLEMENTATION_PLAN.md](notes/IMPLEMENTATION_PLAN.md) for detailed implementation guide. |
| 128 | +- **[Plugin Reference](https://prosdevlab.github.io/experience-sdk/reference/plugins)** - Modal, Banner, Inline plugins |
| 129 | +- **[Theming Guide](https://prosdevlab.github.io/experience-sdk/guides/theming)** - CSS variables customization |
| 130 | +- **[Playground](https://experience-sdk-playground.vercel.app)** - Live demos and use cases |
94 | 131 |
|
95 | 132 | ## Project Status |
96 | 133 |
|
97 | | -🚧 **v0.1.0 in development** - Foundation phase |
98 | | - |
99 | | -- [ ] Core runtime with explainability |
100 | | -- [ ] Storage plugin (frequency capping) |
101 | | -- [ ] Debug plugin (event emission) |
102 | | -- [ ] Banner plugin (delivery) |
103 | | -- [ ] Demo site |
104 | | -- [ ] UMD bundle |
| 134 | +✅ **v0.2.0** - Presentation Layer Complete |
| 135 | + |
| 136 | +**Core Runtime:** |
| 137 | +- ✅ Explainability-first evaluation engine |
| 138 | +- ✅ Plugin system (sdk-kit) |
| 139 | +- ✅ Event-driven architecture |
| 140 | +- ✅ Hybrid API (singleton + instance) |
| 141 | + |
| 142 | +**Display Condition Plugins:** |
| 143 | +- ✅ Exit Intent - Detect users about to leave |
| 144 | +- ✅ Scroll Depth - Trigger at scroll thresholds |
| 145 | +- ✅ Time Delay - Time-based triggers |
| 146 | +- ✅ Page Visits - Session/total visit tracking |
| 147 | +- ✅ Frequency Capping - Impression limits |
| 148 | + |
| 149 | +**Presentation Plugins:** |
| 150 | +- ✅ Modal - Announcements, promotions, forms |
| 151 | +- ✅ Banner - Top/bottom dismissible messages |
| 152 | +- ✅ Inline - Embed content in page DOM |
| 153 | + |
| 154 | +**Features:** |
| 155 | +- ✅ Built-in form support (validation, submission) |
| 156 | +- ✅ CSS variable theming |
| 157 | +- ✅ TypeScript support |
| 158 | +- ✅ 432 tests passing |
| 159 | +- ✅ ~26KB gzipped (all plugins) |
105 | 160 |
|
106 | 161 | ## Development |
107 | 162 |
|
@@ -149,13 +204,13 @@ Built on [@lytics/sdk-kit](https://github.com/lytics/sdk-kit), Experience SDK sh |
149 | 204 |
|
150 | 205 | ## Roadmap |
151 | 206 |
|
152 | | -- **Phase 0 (v0.1.0)**: Foundation - Runtime + 3 plugins + demo |
153 | | -- **Phase 1 (v0.2.0)**: Chrome Extension - DevTools integration |
154 | | -- **Phase 2 (v0.3.0)**: Advanced plugins - More experience types |
155 | | -- **Phase 3 (v0.4.0)**: Developer tools - Playground & testing |
156 | | -- **Phase 4 (v1.0.0)**: Production-ready |
| 207 | +- ✅ **Phase 0 (v0.1.0)**: Foundation - Core runtime, display condition plugins, banner plugin |
| 208 | +- ✅ **Phase 1 (v0.2.0)**: Presentation Layer - Modal & inline plugins with forms |
| 209 | +- 🚧 **Phase 2 (v0.3.0)**: Developer Experience - Chrome DevTools extension |
| 210 | +- 🚧 **Phase 3 (v0.4.0)**: Advanced Features - Tooltip plugin, multi-instance support |
| 211 | +- 🚧 **Phase 4 (v1.0.0)**: Production Ready - Performance optimizations, advanced targeting |
157 | 212 |
|
158 | | -See [notes/vision-and-roadmap.md](notes/vision-and-roadmap.md) for full roadmap. |
| 213 | +See the [full roadmap](notes/vision-and-roadmap.md) for details. |
159 | 214 |
|
160 | 215 | ## License |
161 | 216 |
|
|
0 commit comments