# Taboola Web Push

A comprehensive WordPress plugin for web push notifications, specifically designed for Taboola publishers and content creators.

## 🚀 Features

### Core Functionality
- **Web Push Notifications**: Send instant browser notifications to your subscribers
- **Subscription Management**: Manage subscriber lists with detailed analytics
- **Custom Prompts**: Fully customizable subscription prompts
- **Service Worker**: Robust service worker implementation for reliable notifications
- **Post Integration**: Automatic notifications when publishing new content

### Admin Dashboard
- **Settings Panel**: Complete configuration interface
- **Subscriber Analytics**: Track subscription rates and engagement
- **Notification Templates**: Pre-built templates for quick sending
- **Bulk Actions**: Manage multiple subscribers at once
- **Test Notifications**: Send test notifications to verify functionality

### User Experience
- **Responsive Design**: Works perfectly on all devices
- **Accessibility**: Full accessibility support with ARIA labels
- **Performance**: Optimized for fast loading and minimal impact
- **Browser Compatibility**: Supports all modern browsers

## 📋 Requirements

- WordPress 5.0 or higher
- PHP 7.4 or higher
- MySQL 5.6 or higher
- SSL certificate (HTTPS) - Required for push notifications
- Modern browser with push notification support

## 🛠 Installation

### Method 1: Manual Installation

1. **Download the Plugin**
   - Download the `taboola-web-push` folder to your computer

2. **Upload to WordPress**
   - Upload the entire `taboola-web-push` folder to `/wp-content/plugins/`
   - Or zip the folder and upload via WordPress admin

3. **Activate the Plugin**
   - Go to WordPress Admin > Plugins
   - Find "Taboola Web Push" and click "Activate"

### Method 2: WordPress Admin Upload

1. Go to WordPress Admin > Plugins > Add New
2. Click "Upload Plugin"
3. Choose the zipped plugin file
4. Click "Install Now" and then "Activate"

## ⚙️ Configuration

### Initial Setup

1. **Navigate to Plugin Settings**
   - Go to WordPress Admin > Taboola Web Push > Settings

2. **Enable Push Notifications**
   - Check "Enable web push notifications for your website"
   - Enter your site name and default icon URL

3. **Configure Prompt Settings**
   - Set up your subscription prompt title and message
   - Choose when to show the prompt to visitors

4. **Save Settings**
   - Click "Save Changes" to apply your configuration

### VAPID Keys (For Production)

For production use, you'll need to generate VAPID keys:

1. **Generate Keys**
   - Use an online VAPID key generator or Node.js script
   - Or use the plugin's built-in generator (coming soon)

2. **Add Keys to Settings**
   - Enter the public key in "VAPID Public Key"
   - Enter the private key in "VAPID Private Key"

## 🎯 Usage

### For Visitors (Frontend)

1. **Subscribe to Notifications**
   - Visitors will see a subscription prompt
   - Click "Subscribe" to enable notifications
   - Browser will ask for permission

2. **Receive Notifications**
   - Notifications appear when new content is published
   - Click notifications to visit the content
   - Dismiss notifications as needed

### For Publishers (Admin)

1. **View Subscribers**
   - Go to Taboola Web Push > Subscribers
   - See all subscribers and their status
   - Export subscriber lists

2. **Send Test Notifications**
   - Go to Taboola Web Push > Send Notification
   - Enter title, message, and click URL
   - Send to all subscribers or test individually

3. **Automatic Notifications**
   - When creating/editing posts, check "Send Push Notification"
   - Customize the notification title and message
   - Notification sends automatically when post is published

## 🧪 Testing

### Local Testing

1. **Enable the Plugin**
   - Make sure the plugin is activated
   - Enable push notifications in settings

2. **Test Subscription**
   - Visit your website in a new browser/incognito window
   - Allow notifications when prompted
   - Check if you appear in the subscribers list

3. **Test Notifications**
   - Go to Admin > Taboola Web Push > Send Notification
   - Send a test notification to yourself
   - Verify the notification appears in your browser

### Debug Mode

Add `?taboola_debug=1` to your URL to enable debug mode:
- Frontend: `yoursite.com/?taboola_debug=1`
- Admin: `yoursite.com/wp-admin/admin.php?page=taboola-web-push&taboola_debug=1`

## 🎨 Customization

### CSS Customization

You can customize the appearance by adding CSS to your theme:

```css
/* Customize notification prompt */
.taboola-prompt {
    background: linear-gradient(135deg, #your-color-1, #your-color-2);
    border-radius: 15px;
}

/* Customize buttons */
.taboola-btn-primary {
    background: #your-brand-color;
}
```

### JavaScript Customization

Access the plugin's JavaScript API:

```javascript
// Show prompt manually
TaboolaWebPush.showPrompt();

// Check subscription status
if (TaboolaWebPush.isSubscribed()) {
    console.log('User is subscribed');
}

// Subscribe programmatically
TaboolaWebPush.subscribe();
```

## 🔧 Advanced Configuration

### Database Tables

The plugin creates two tables:
- `wp_taboola_web_push_subscribers` - Stores subscriber data
- `wp_taboola_web_push_notifications` - Stores notification history

### Hooks and Filters

```php
// Modify notification data before sending
add_filter('taboola_notification_data', function($data) {
    $data['icon'] = 'your-custom-icon.png';
    return $data;
});

// Action when user subscribes
add_action('taboola_user_subscribed', function($subscriber_id) {
    // Your custom code here
});
```

## 🚨 Troubleshooting

### Common Issues

1. **Notifications Not Appearing**
   - Check if HTTPS is enabled
   - Verify browser supports push notifications
   - Check if notifications are blocked in browser settings

2. **Prompt Not Showing**
   - Ensure plugin is enabled
   - Check if prompt was recently dismissed
   - Verify JavaScript is not blocked

3. **Subscription Failing**
   - Check browser console for errors
   - Verify VAPID keys are correct
   - Ensure service worker is registered

### Debug Steps

1. **Check Console**
   - Open browser developer tools
   - Look for errors in console
   - Check network tab for failed requests

2. **Verify Service Worker**
   - Go to Application tab in dev tools
   - Check if service worker is registered
   - Look for any service worker errors

3. **Test Permissions**
   - Check notification permissions in browser settings
   - Reset permissions if needed
   - Try in incognito/private browsing

## 📊 Analytics

### Built-in Analytics

The plugin provides:
- Subscriber count and growth
- Notification delivery statistics
- Click-through rates
- Geographic distribution (if available)

### Google Analytics Integration

The plugin automatically sends events to Google Analytics if available:
- `notification_shown` - When notification is displayed
- `notification_clicked` - When notification is clicked
- `subscription_completed` - When user subscribes

## 🔒 Security

### Data Protection

- All subscriber data is stored securely in your WordPress database
- No data is sent to external servers (except for notifications)
- VAPID keys are stored encrypted
- Regular security updates

### Privacy Compliance

- GDPR compliant with proper consent mechanisms
- Users can unsubscribe at any time
- No tracking without explicit consent
- Clear privacy policies recommended

## 🔄 Updates

### Automatic Updates

The plugin supports WordPress automatic updates:
- Updates are delivered through WordPress.org
- Backup your site before major updates
- Test updates on staging sites first

### Manual Updates

To update manually:
1. Deactivate the plugin
2. Replace plugin files
3. Reactivate the plugin
4. Clear any caches

## 🤝 Support

### Documentation

- Full documentation available in the plugin admin
- Video tutorials coming soon
- FAQ section with common questions

### Community Support

- WordPress.org support forums
- GitHub issues and discussions
- Community Discord server

### Professional Support

For enterprise support and custom development:
- Contact: shlomi.b@taboola.com
- Visit: https://www.taboola.com/support

## 📝 Changelog

### Version 1.0.0
- Initial release
- Complete web push notification system
- Admin dashboard with full functionality
- Subscriber management
- Notification templates
- Service worker implementation
- Responsive design
- Accessibility features

## 🤖 API Reference

### PHP Hooks

```php
// Filter notification data
add_filter('taboola_notification_data', $callback);

// Action when notification is sent
add_action('taboola_notification_sent', $callback);

// Filter subscription data
add_filter('taboola_subscription_data', $callback);
```

### JavaScript API

```javascript
// Main API object
window.TaboolaWebPush = {
    subscribe: function() {},
    showPrompt: function() {},
    hidePrompt: function() {},
    isSubscribed: function() {},
    getConfig: function() {}
};
```

## 📄 License

This plugin is licensed under the GPL v2 or later.

## 🙏 Credits

- **Author**: shlomi.b@taboola.com
- **Company**: Taboola
- **WordPress Profile**: https://profiles.wordpress.org/taboolawordpress/
- **Website**: https://www.taboola.com/

## 🔗 Links

- [Plugin Homepage](https://www.taboola.com/web-push)
- [Documentation](https://www.taboola.com/web-push/docs)
- [Support](https://www.taboola.com/support)
- [WordPress.org Profile](https://profiles.wordpress.org/taboolawordpress/)

---

Made with ❤️ by the Taboola team for WordPress publishers worldwide.