🎯 Push Banner Widget

A smart, responsive banner widget for enabling push notifications in MobiLoud apps. Features intelligent display logic, session limiting, mobile optimization, and zero dependencies.

✨ Features

• 🧠 Smart Display Logic - Only shows when user is in app AND notifications are disabled
• 📱 Mobile Responsive - Optimized for all device sizes
• 🔢 Session Limiting - Control how many times banner appears
• ⚡ Real-time Updates - Instantly reflects notification status changes
• 🎨 Fully Customizable - Colors, text, positioning, behavior
• 📍 Flexible Positioning - Fixed top/bottom or within containers
• 🚀 Zero Dependencies - Completely standalone
• ♿ Accessible - WCAG compliant with keyboard navigation
• 🌗 Dark Mode Support - Automatic dark/light mode detection

🚀 Quick Start

CDN (Recommended)

<script src="https://cdn.jsdelivr.net/npm/@mobiloud/push-banner-widget/script.js"></script>
<script>
  createPushBanner({
    position: 'top',
    sessionLimit: 3
  });
</script>

NPM Installation

npm install push-banner-widget

import 'push-banner-widget';

createPushBanner({
  heading: "🎉 Special Offer!",
  text: "Enable notifications for exclusive deals",
  position: 'top',
  sessionLimit: 3
});

Direct Download

1. Download script.js from the releases page
2. Include in your HTML:

<script src="path/to/script.js"></script>
<script>
  createPushBanner({ position: 'top' });
</script>

📖 Usage Examples

Basic Banner

createPushBanner({
  position: 'top',
  sessionLimit: 3
});

Customized Banner

createPushBanner({
  heading: "🛍️ Exclusive Deals",
  text: "Enable notifications for flash sales and limited offers",
  successMessage: "🎉 You're all set for exclusive deals!",
  position: 'bottom',
  sessionLimit: 5,
  backgroundColor: '#e3f2fd',
  headingColor: '#1e293b',
  textColor: '#475569',
  autoHideSuccess: false,
  onAccept: () => {
    console.log('User enabled notifications');
    gtag('event', 'notification_enabled');
  }
});

Container Positioning

createPushBanner({
  heading: "📬 Stay Updated",
  text: "Get notified about important announcements",
  position: { element: '#notification-area' },
  sessionLimit: 2
});

⚙️ Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | heading | string | "Get 10% OFF your next order" | Main banner heading | | text | string | "Enable push notifications to receive your unique coupon code" | Banner description | | successMessage | string | "Thank you for subscribing! Use APPLOVER coupon to get your 10% discount" | Success message | | position | string\|object | 'top' | 'top', 'bottom', or { element: '#selector' } | | sessionLimit | number | 3 | Maximum times to show per session | | backgroundColor | string | '#e3f2fd' | Banner background color | | headingColor | string | '#1e293b' | Heading text color | | textColor | string | '#475569' | Description text color | | autoHideSuccess | boolean | true | Auto-hide success message after 3s | | debugMode | boolean | false | Show in browsers (for testing) | | allowedUrls | array\|string | null | Restrict to specific URLs | | onAccept | function | () => {} | Callback when banner clicked | | onShow | function | () => {} | Callback when banner shown | | onHide | function | () => {} | Callback when banner hidden |

🎨 Color Themes

Light Blue (Default)

backgroundColor: '#e3f2fd',
headingColor: '#1e293b',
textColor: '#475569'

Green Theme

backgroundColor: '#ecfdf5',
headingColor: '#14532d',
textColor: '#166534'

Purple Theme

backgroundColor: '#f3e8ff',
headingColor: '#581c87',
textColor: '#7c3aed'

Yellow Theme

backgroundColor: '#fef3c7',
headingColor: '#92400e',
textColor: '#b45309'

📱 Mobile Responsive

The widget automatically adapts to different screen sizes:

• Desktop (1200px+): Full size with optimal spacing
• Tablet (768px-1199px): Adjusted padding and icon size
• Mobile (480px-767px): Compact layout with smaller text
• Small Mobile (320px-479px): Minimal spacing for tiny screens

🔧 Advanced Usage

Session Management

// Show only once per session
createPushBanner({ sessionLimit: 1 });

// Clear session data (for testing)
Object.keys(sessionStorage)
  .filter(key => key.startsWith('pushBanner_'))
  .forEach(key => sessionStorage.removeItem(key));

URL Restrictions

// Show only on specific pages
createPushBanner({
  allowedUrls: ['/products', '/offers']
});

// Pattern matching
createPushBanner({
  allowedUrls: ['/products/*', '/category/*']
});

Event Tracking

createPushBanner({
  onShow: () => {
    gtag('event', 'banner_shown', {
      banner_type: 'push_notification'
    });
  },
  onAccept: () => {
    gtag('event', 'notification_enabled', {
      source: 'banner_widget'
    });
  }
});

Programmatic Control

const banner = createPushBanner({ position: 'top' });

// Hide manually
banner.hide();

// Destroy completely
banner.destroy();

🛠️ Framework Integration

React

import { useEffect } from 'react';

function App() {
  useEffect(() => {
    // Dynamic import to avoid SSR issues
    import('push-banner-widget').then(() => {
      window.createPushBanner({
        position: 'top',
        sessionLimit: 3
      });
    });
  }, []);

  return <div>Your app content</div>;
}

Vue.js

<template>
  <div>Your app content</div>
</template>

<script>
export default {
  async mounted() {
    await import('push-banner-widget');
    window.createPushBanner({
      position: 'top',
      sessionLimit: 3
    });
  }
}
</script>

WordPress

function add_push_banner() {
    wp_enqueue_script(
        'push-banner-widget',
        'https://cdn.jsdelivr.net/npm/[email protected]/script.js',
        [],
        '1.0.0',
        true
    );
    
    wp_add_inline_script('push-banner-widget', '
        createPushBanner({
            position: "top",
            sessionLimit: 3,
            heading: "Stay Connected!",
            text: "Enable notifications for the latest updates"
        });
    ');
}
add_action('wp_enqueue_scripts', 'add_push_banner');

🧪 Testing & Debug Mode

Enable debug mode to test in regular browsers:

createPushBanner({
  debugMode: true,
  sessionLimit: 999, // Don't limit for testing
  position: 'top'
});

Debug mode bypasses:

• App context checks
• Push notification status checks
• Allows testing in any browser

🌐 Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+
• iOS Safari 12+
• Chrome Android 60+

📦 What's Included

push-banner-widget/
├── script.js          # Main widget file (standalone)
├── styles.css         # Demo page styles (optional)
├── examples/
│   ├── basic.html     # Basic implementation
│   ├── advanced.html  # Advanced customization
│   └── frameworks/    # Framework examples
├── types/
│   └── index.d.ts     # TypeScript definitions
├── README.md
├── CHANGELOG.md
└── package.json

🔒 Security & Privacy

• No external requests - Completely self-contained
• No tracking - Only uses sessionStorage for display limiting
• XSS safe - All user content is properly escaped
• GDPR compliant - No personal data collection

🚀 Performance

• Bundle size: ~12KB minified
• Zero dependencies: No external libraries
• Lazy loading ready: Can be loaded on demand
• Memory efficient: Automatic cleanup and optimization

📈 Real-World Examples

E-commerce

createPushBanner({
  heading: "🛍️ Flash Sale Alert",
  text: "Be first to know about our 24-hour flash sales",
  successMessage: "🎉 You'll never miss a flash sale again!",
  backgroundColor: '#f1f5f9',
  headingColor: '#334155',
  textColor: '#64748b'
});

News Site

createPushBanner({
  heading: "📰 Breaking News",
  text: "Get instant alerts for important news updates",
  successMessage: "✅ You're now subscribed to breaking news",
  backgroundColor: '#ecfdf5',
  headingColor: '#14532d',
  textColor: '#166534'
});

SaaS Application

createPushBanner({
  heading: "🔔 System Updates",
  text: "Stay informed about maintenance and new features",
  position: { element: '.dashboard-header' },
  autoHideSuccess: false,
  backgroundColor: '#fef3c7',
  headingColor: '#92400e',
  textColor: '#b45309'
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

🏷️ Changelog

See CHANGELOG.md for a detailed history of changes.

Made with ❤️ by MobiLoud