@mobiloud/push-banner-widget/README.md

Smart, responsive banner widget for enabling push notifications in MobiLoud apps. Features session limiting, mobile optimization, and zero dependencies.

# 🎯 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)

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

### NPM Installation

```bash
npm install push-banner-widget
```

```javascript
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](https://github.com/mobiloud/push-banner-widget/releases)
2. Include in your HTML:

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

## 📖 Usage Examples

### Basic Banner
```javascript
createPushBanner({
  position: 'top',
  sessionLimit: 3
});
```

### Customized Banner
```javascript
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
```javascript
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)
```javascript
backgroundColor: '#e3f2fd',
headingColor: '#1e293b',
textColor: '#475569'
```

### Green Theme
```javascript
backgroundColor: '#ecfdf5',
headingColor: '#14532d',
textColor: '#166534'
```

### Purple Theme
```javascript
backgroundColor: '#f3e8ff',
headingColor: '#581c87',
textColor: '#7c3aed'
```

### Yellow Theme
```javascript
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
```javascript
// 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
```javascript
// Show only on specific pages
createPushBanner({
  allowedUrls: ['/products', '/offers']
});

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

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

### Programmatic Control
```javascript
const banner = createPushBanner({ position: 'top' });

// Hide manually
banner.hide();

// Destroy completely
banner.destroy();
```

## 🛠️ Framework Integration

### React
```jsx
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
```vue
<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
```php
function add_push_banner() {
    wp_enqueue_script(
        'push-banner-widget',
        'https://cdn.jsdelivr.net/npm/push-banner-widget@1.0.0/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:

```javascript
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
```javascript
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
```javascript
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
```javascript
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](CONTRIBUTING.md) 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](LICENSE) file for details.

## 🆘 Support

- 📚 [Documentation](https://github.com/mobiloud/push-banner-widget/wiki)
- 🐛 [Issue Tracker](https://github.com/mobiloud/push-banner-widget/issues)
- 💬 [Discussions](https://github.com/mobiloud/push-banner-widget/discussions)
- 📧 [Email Support](mailto:support@mobiloud.com)

## 🏷️ Changelog

See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.

---

Made with ❤️ by [MobiLoud](https://www.mobiloud.com)