API Reference
Plugins
Banner

Banner Plugin

Renders banner experiences in the DOM with automatic positioning, theming, and responsive layout.

Configuration

import { createInstance } from '@prosdevlab/experience-sdk';
 
const experiences = createInstance({
  banner: {
    position: 'top',      // 'top' | 'bottom' (default: 'top')
    zIndex: 10000,        // Custom z-index (default: 10000)
    dismissable: true     // Allow dismissal (default: true)
  }
});

API Methods

banner.show(experience)

Manually show a banner experience.

experiences.banner.show({
  id: 'welcome',
  type: 'banner',
  targeting: {},
  content: {
    title: 'Welcome!',
    message: 'Thanks for visiting.',
    buttons: [
      { text: 'Get Started', url: '/start', variant: 'primary' }
    ]
  }
});
banner.remove(experienceId)

Remove a specific banner.

experiences.banner.remove('welcome');
banner.isShowing(experienceId?)

Check if a banner is currently showing.

// Check specific banner
if (experiences.banner.isShowing('welcome')) {
  console.log('Welcome banner is visible');
}
 
// Check if any banner is showing
if (experiences.banner.isShowing()) {
  console.log('A banner is visible');
}

Button Variants

Banners support multiple buttons with different visual styles:

buttons: [
  {
    text: 'Accept all',
    action: 'accept',
    variant: 'primary',     // Blue, prominent
    metadata: { consent: ['all'] }
  },
  {
    text: 'Reject',
    action: 'reject',
    variant: 'secondary',   // Gray, outlined
    metadata: { consent: [] }
  },
  {
    text: 'Preferences',
    action: 'preferences',
    variant: 'link',        // Text link style
    url: '/preferences'
  }
]

Variants:

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

Responsive Layout

Banners automatically adapt to screen size:

  • Desktop (>640px): Buttons display inline horizontally
  • Mobile (≤640px): Buttons stack vertically for better touch interaction

Events

The banner plugin emits the following events:

experiences:shown

experiences.on('experiences:shown', ({ experienceId, type }) => {
  console.log(`${type} shown:`, experienceId);
});

experiences:action

experiences.on('experiences:action', ({ experienceId, action, variant, metadata, url }) => {
  console.log('Button clicked:', action, 'variant:', variant);
  if (metadata) {
    console.log('Metadata:', metadata);
  }
});

experiences:dismissed

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

See Banner Examples for complete usage examples.

Customization

The Experience SDK focuses on targeting logic, not visual design. The banner plugin provides minimal, functional default styles that you can customize using CSS.

CSS Classes

The banner plugin uses the .xp-* namespace for all CSS classes:

  • .xp-banner - Main container
  • .xp-banner--top - Top positioned banner
  • .xp-banner--bottom - Bottom positioned banner
  • .xp-banner__container - Inner wrapper
  • .xp-banner__content - Content section
  • .xp-banner__title - Optional title
  • .xp-banner__message - Main message text
  • .xp-banner__buttons - Buttons container
  • .xp-banner__button - Individual button
  • .xp-banner__button--primary - Primary button variant
  • .xp-banner__button--secondary - Secondary button variant
  • .xp-banner__button--link - Link button variant
  • .xp-banner__close - Close button

Use Case 1: User with Tailwind

Add Tailwind classes via the className property:

experiences.register('flash-sale', {
  type: 'banner',
  content: {
    message: 'Flash Sale: 50% Off Everything!',
    className: 'bg-gradient-to-r from-blue-600 to-purple-600 text-white',
    buttons: [{
      text: 'Shop Now',
      url: '/shop',
      variant: 'primary',
      className: 'bg-white text-blue-600 hover:bg-gray-100'
    }]
  },
  targeting: { url: { contains: '/shop' } }
});

Use Case 2: User with Design System

Build your own plugin using your design system components:

import { MyBannerComponent } from '@your-org/design-system';
 
const myBannerPlugin: PluginFunction = (plugin, instance, config) => {
  instance.on('experiences:evaluated', ({ decision, experience }) => {
    if (decision.show && experience.type === 'banner') {
      // Render using your React component
      ReactDOM.render(
        <MyBannerComponent {...experience.content} />,
        document.getElementById('banner-root')
      );
    }
  });
};
 
experiences.use(myBannerPlugin);

Use Case 3: User with CSS Framework

Add Bootstrap, Material UI, or other framework classes:

experiences.register('alert', {
  type: 'banner',
  content: {
    message: 'Important notice',
    className: 'alert alert-warning',
    buttons: [{
      text: 'Learn More',
      className: 'btn btn-primary'
    }]
  },
  targeting: {}
});

Inline Styles

For quick overrides, use the style property:

content: {
  message: 'Flash Sale!',
  style: {
    background: 'linear-gradient(90deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
    padding: '24px'
  }
}
OverviewModal