Examples
Banner Experience

Banner Examples

The Experience SDK supports banner-style experiences with targeting, frequency capping, and full explainability.

Basic Example

import { createInstance } from '@prosdevlab/experience-sdk';
 
// Create SDK instance with banner plugin
const experiences = createInstance({ debug: true });
 
// Register a welcome banner
experiences.register('welcome-banner', {
  type: 'banner',
  targeting: {
    url: { contains: '/' }
  },
  content: {
    title: 'Welcome!',
    message: 'Thanks for visiting our site',
    buttons: [
      {
        text: 'Get Started',
        url: '/getting-started',
        variant: 'primary'
      }
    ],
    dismissable: true
  },
  frequency: {
    max: 3,
    per: 'session'
  }
});
 
// Evaluate and show
const decision = experiences.evaluate();
console.log(decision.reasons); // See why it was shown or hidden

Multiple Buttons

Banners can have multiple buttons with different visual variants:

experiences.register('cookie-consent', {
  type: 'banner',
  content: {
    message: 'We use cookies to improve your experience',
    buttons: [
      {
        text: 'Accept all',
        action: 'accept-all',
        variant: 'primary'
      },
      {
        text: 'Reject',
        action: 'reject',
        variant: 'secondary'
      },
      {
        text: 'Preferences',
        action: 'preferences',
        variant: 'link'
      }
    ],
    position: 'bottom'
  }
});

Button variants:

  • primary - Prominent blue button for main actions
  • secondary - Subtle gray button for secondary actions
  • link - Text link style for tertiary actions

Multiple Banners

You can display multiple banners at different positions:

// Top banner
experiences.register('welcome', {
  type: 'banner',
  content: {
    message: 'Welcome!',
    position: 'top'
  },
  priority: 50
});
 
// Bottom banner
experiences.register('cookie-notice', {
  type: 'banner',
  content: {
    message: 'We use cookies',
    position: 'bottom'
  },
  priority: 100
});
 
// Evaluate all experiences
const decisions = experiences.evaluateAll();

Banner Configuration

Content Options

PropertyTypeDescription
titlestringOptional banner title
messagestringBanner message (required)
buttonsarrayArray of button configurations
dismissablebooleanCan user dismiss? (default: true)
position'top' | 'bottom'Banner position (default: 'top')
classNamestringCustom CSS class for the banner
styleRecord<string, string>Inline styles for the banner

Button Options

buttons: [{
  text: string;                            // Button label (required)
  action?: string;                         // Custom action name
  url?: string;                            // Navigate on click
  variant?: 'primary' | 'secondary' | 'link'; // Visual style (default: 'primary')
  metadata?: Record<string, any>;          // Custom metadata
  className?: string;                      // Custom CSS class
  style?: Record<string, string>;          // Inline styles
}]

Responsive Layout

Buttons automatically adapt to screen size:

  • Desktop: Buttons displayed inline horizontally
  • Mobile: Buttons stack vertically for better touch interaction

Frequency Capping

Control how often banners appear:

frequency: {
  max: 3,              // Maximum impressions
  per: 'session'       // 'session' | 'day' | 'week'
}

Targeting

Show banners based on URL patterns:

targeting: {
  url: {
    contains: '/products',  // URL contains string
    equals: '/about',       // Exact match
    matches: /^\/blog/      // Regex pattern
  }
}

Customization

Customize banners with your own CSS using className or style props:

// With Tailwind classes
experiences.register('promo', {
  type: 'banner',
  content: {
    message: 'Flash Sale: 50% Off!',
    className: 'bg-gradient-to-r from-blue-600 to-purple-600 text-white',
    buttons: [{
      text: 'Shop Now',
      className: 'bg-white text-blue-600 hover:bg-gray-100'
    }]
  }
});
 
// With inline styles
experiences.register('custom', {
  type: 'banner',
  content: {
    message: 'Custom styled banner',
    style: {
      background: 'linear-gradient(90deg, #667eea 0%, #764ba2 100%)',
      color: 'white',
      padding: '24px'
    }
  }
});

The banner plugin uses stable .xp-* CSS classes that you can target in your stylesheets. See the Plugins documentation for complete customization guide.

Events

Listen to banner interactions:

// Banner shown
experiences.on('experiences:shown', ({ experienceId }) => {
  console.log(`Banner shown: ${experienceId}`);
});
 
// Banner dismissed
experiences.on('experiences:dismissed', ({ experienceId }) => {
  console.log(`Banner dismissed: ${experienceId}`);
});
 
// Button clicked
experiences.on('experiences:action', ({ experienceId, action, variant, metadata }) => {
  console.log(`Action: ${action}, Variant: ${variant}`);
  
  // Access custom metadata if provided
  if (metadata) {
    console.log('Metadata:', metadata);
  }
});

Next Steps

OverviewAPI Reference