@prosdevlab/experience-sdk

A lightweight, explainable client-side experience runtime built on @lytics/sdk-kit.

Size: 13.4 KB gzipped core + 12.7 KB gzipped plugins = 26.1 KB total

Features

• Explainability-First - Every decision includes structured reasons
• Plugin-Based - Built on sdk-kit's powerful plugin system
• Multiple Layouts - Banners, modals, and inline experiences
• Form Support - Email capture with built-in validation
• Display Conditions - Exit intent, scroll depth, time delays, page visits
• Frequency Capping - Control impression limits per session/lifetime
• Responsive Layout - Automatically adapts to mobile/desktop
• Script Tag Ready - Works without build tools
• Type-Safe - Full TypeScript support
• CSS Variables - Full theming support

Installation

npm

npm install @prosdevlab/experience-sdk

Script Tag

<script src="https://unpkg.com/@prosdevlab/experience-sdk/dist/experience-sdk.global.js"></script>

Quick Start

For Bundlers (ESM)

import { createInstance } from '@prosdevlab/experience-sdk';

// Create instance
const experiences = createInstance({ debug: true });

// Initialize
await experiences.init();

// Register a modal with form
experiences.register('newsletter', {
  type: 'modal',
  targeting: {
    custom: (context) => context.triggers.exitIntent
  },
  content: {
    title: 'Before You Go!',
    message: 'Subscribe for 10% off your first order.',
    size: 'sm',
    form: {
      fields: [
        { name: 'email', type: 'email', required: true, placeholder: '[email protected]' }
      ],
      submitButton: { text: 'Get Discount', variant: 'primary' },
      successState: { 
        title: '✓ Check Your Inbox',
        message: 'Your discount code is on the way!'
      }
    }
  }
});

// Or register a banner
experiences.register('welcome', {
  type: 'banner',
  targeting: {
    url: { contains: '/' }
  },
  content: {
    message: 'Welcome! Get 20% off today.',
    buttons: [
      { text: 'Shop Now', url: '/shop', variant: 'primary' }
    ],
    position: 'top'
  },
  frequency: {
    max: 3,
    per: 'session'
  }
});

// Evaluate and show
const decision = experiences.evaluate();
console.log(decision.reasons);

For Script Tag

<script src="https://unpkg.com/@prosdevlab/experience-sdk/dist/experience-sdk.global.js"></script>
<script>
  // Global 'experiences' available
  experiences.init({ debug: true });
  
  experiences.register('cookie-consent', {
    type: 'banner',
    content: {
      message: 'We use cookies to improve your experience',
      buttons: [
        { text: 'Accept', action: 'accept', variant: 'primary' },
        { text: 'Reject', action: 'reject', variant: 'secondary' }
      ],
      position: 'bottom'
    }
  });
  
  experiences.evaluate();
</script>

Multiple Buttons

Banners support multiple buttons with visual variants:

buttons: [
  { text: 'Accept all', variant: 'primary', action: 'accept' },
  { text: 'Reject', variant: 'secondary', action: 'reject' },
  { text: 'Preferences', variant: 'link', url: '/preferences' }
]

• primary - Blue button for main actions
• secondary - Gray outlined button for secondary actions
• link - Text link style for tertiary actions

Events

Listen to experience interactions:

// Banner shown
experiences.on('experiences:shown', ({ experienceId }) => {
  console.log('Shown:', experienceId);
});

// Button clicked
experiences.on('experiences:action', ({ experienceId, action, variant, metadata }) => {
  analytics.track('Experience Action', { experienceId, action });
});

// Banner dismissed
experiences.on('experiences:dismissed', ({ experienceId }) => {
  console.log('Dismissed:', experienceId);
});

Included Plugins

This package auto-registers the following official plugins:

Layout Plugins

• Banner Plugin - Top/bottom notification bars
• Modal Plugin - Overlay dialogs with forms
• Inline Plugin - In-content experiences

Display Conditions

• Exit Intent - Detect when users are leaving
• Scroll Depth - Track scroll engagement
• Page Visits - Session and lifetime counters
• Time Delay - Show after time elapsed

Utility Plugins

• Frequency Plugin - Impression tracking and capping
• Debug Plugin - Logging and window events

Documentation

• Full Documentation
• API Reference
• Plugins Guide
• Examples

License

MIT