# Acoustic Connect integration for WooCommerce

![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)
![WordPress](https://img.shields.io/badge/WordPress-5.0+-green.svg)
![WooCommerce](https://img.shields.io/badge/WooCommerce-3.0+-purple.svg)
![PHP](https://img.shields.io/badge/PHP-7.2+-777BB4.svg)
![License](https://img.shields.io/badge/license-GPL--2.0+-red.svg)

Track customer behavior and send events directly to your Acoustic Connect Collector API from your WooCommerce store.

## 📋 Description

This plugin integrates Acoustic Connect tracking with your WooCommerce store, enabling you to:

- ✅ Track page views and navigation
- ✅ Monitor product views and interactions
- ✅ Capture search behavior
- ✅ Track add to cart and remove from cart events
- ✅ Monitor complete checkout flow
- ✅ Send events directly from browser to Acoustic Collector API
- ✅ Session and page tracking included

## 🚀 Features

- **Easy Configuration**: Simple admin interface with App Key and Collector URL settings
- **Comprehensive Tracking**: All major WooCommerce events captured
- **Direct API Communication**: Events sent directly from browser to Acoustic Collector
- **Session Management**: Automatic session and page ID generation
- **Debug Mode**: Built-in console logging for development
- **Lightweight**: Minimal performance impact
- **No Authentication Required**: Uses Acoustic's App Key only
- **HPOS Compatible**: Works with WooCommerce High-Performance Order Storage

## 📦 Installation

### Method 1: Upload via WordPress Admin

1. Download the plugin zip file
2. Go to WordPress Admin → Plugins → Add New
3. Click "Upload Plugin"
4. Choose the zip file and click "Install Now"
5. Click "Activate Plugin"

### Method 2: Manual Installation

1. Download and extract the plugin files
2. Upload the `acoustic-connect-woocommerce` folder to `/wp-content/plugins/`
3. Go to WordPress Admin → Plugins
4. Activate "Acoustic Connect integration for WooCommerce"

### Method 3: WP-CLI

```bash
wp plugin install acoustic-connect-woocommerce.zip --activate
```

## ⚙️ Configuration

### Required Settings

1. **Navigate to Settings:**
   - WooCommerce → Settings → Acoustic Connect

2. **Enter Required Information:**
   - **App Key**: Your Acoustic Connect Application Key
   - **Collector URL**: Your Collector API endpoint (e.g., `https://lib-us-1.brilliantcollector.com/collector/collectorPost`)

3. **Enable Tracking:**
   - Check "Enable Tracking" checkbox
   - Click "Save Changes"

[//]: # (### Optional Settings)

[//]: # ()
[//]: # (**Event Configuration Tab:**)

[//]: # (- Enable/disable specific event types)

[//]: # (- All events are enabled by default)

[//]: # ()
[//]: # (**Debug Options:**)

[//]: # (- Enable Debug Mode to log events to browser console)

[//]: # (- ⚠️ Disable in production)

## 🎯 Tracked Events

### 1. Page View
Triggered on every page load.

**Data captured:**
- URL, title, referrer
- Page path and query string
- Page type (home, product, cart, checkout, etc.)
- User agent and language

### 2. Product View
Triggered when viewing product detail pages.

**Data captured:**
- Product ID, name, SKU
- Price, regular price, sale price
- Currency
- Categories
- Stock status
- Product type

### 3. Search
Triggered when searching for products.

**Data captured:**
- Search term
- Results URL
- Timestamp

### 4. Add to Cart
Triggered when adding products to cart.

**Data captured:**
- Product details
- Quantity
- Price
- Variation details (if applicable)

### 5. Remove from Cart
Triggered when removing products from cart.

**Data captured:**
- Product details
- Quantity removed
- Price

### 6. Checkout Steps
Triggered during checkout process.

**Steps tracked:**
- Checkout start
- Form field changes
- Payment method selection
- Place order button click
- Order completion

## 📡 API Request Format

All events are sent as POST requests to your Collector URL:

```json
{
  "events": [
    {
      "type": "pageView",
      "timestamp": 1234567890000,
      "sessionId": "S.abc123...",
      "pageId": "P.xyz789...",
      "appKey": "your-app-key",
      "page": {
        "url": "https://example.com/product/example",
        "title": "Example Product",
        "referrer": "https://google.com",
        "path": "/product/example",
        "queryString": "?utm_source=google"
      }
    }
  ],
  "timestamp": 1234567890000
}
```

[//]: # (## 🔧 Testing)

[//]: # ()
[//]: # (### Enable Debug Mode)

[//]: # ()
[//]: # (1. Go to WooCommerce → Settings → Acoustic Connect)

[//]: # (2. Check "Enable Debug Mode")

[//]: # (3. Save Changes)

[//]: # ()
[//]: # (### Verify Events)

[//]: # ()
[//]: # (1. Open your store in a browser)

[//]: # (2. Open Developer Tools (F12))

[//]: # (3. Go to Console tab)

[//]: # (4. Look for `[Acoustic Connect]` log messages)

[//]: # (5. Perform actions (view product, add to cart, etc.))

[//]: # ()
[//]: # (### Check Network Requests)

[//]: # ()
[//]: # (1. Open Developer Tools → Network tab)

[//]: # (2. Filter by your Collector URL domain)

[//]: # (3. Look for POST requests)

[//]: # (4. Verify request headers include `X-Tealeaf-SaaS-AppKey`)

[//]: # (5. Check response status is 200 OK)

## 🐛 Troubleshooting

### Events Not Being Sent

**Check Configuration:**
- Verify App Key is correct
- Verify Collector URL is correct and accessible
- Ensure "Enable Tracking" is checked

**Check Browser Console:**
- Enable Debug Mode
- Look for JavaScript errors
- Check for `[Acoustic Connect]` messages

**Check Network Tab:**
- Look for blocked requests
- Verify no CORS issues
- Check response status codes

### Events Missing Data

**Verify WooCommerce:**
- Ensure WooCommerce is active and up to date
- Check product data is complete
- Verify cart is functioning

**Check PHP Errors:**
- Enable WordPress debug mode
- Check error logs
- Look for plugin conflicts

### Session Issues

**Clear Caches:**
- Clear browser cache
- Clear WordPress cache
- Clear WooCommerce session data

**Check Session Handling:**
- Verify PHP sessions are working
- Check WooCommerce session handlers

[//]: # (## 🔌 Hooks & Filters)

[//]: # ()
[//]: # (### Modify Product Data)

[//]: # ()
[//]: # (```php)

[//]: # (add_filter('acoustic_connect_product_data', function($data, $product) {)

[//]: # (    // Add custom field)

[//]: # (    $data['brand'] = get_post_meta($product->get_id(), '_brand', true);)

[//]: # (    return $data;)

[//]: # (}, 10, 2);)

[//]: # (```)

[//]: # ()
[//]: # (### Modify Cart Data)

[//]: # ()
[//]: # (```php)

[//]: # (add_filter('acoustic_connect_cart_data', function($data) {)

[//]: # (    // Add custom cart data)

[//]: # (    $data['couponCode'] = WC()->cart->get_applied_coupons();)

[//]: # (    return $data;)

[//]: # (});)

[//]: # (```)

[//]: # ()
[//]: # (### Custom Events)

[//]: # ()
[//]: # (```javascript)

[//]: # (// In your theme or custom plugin)

[//]: # (if (window.AcousticConnect && window.AcousticConnect.tracker) {)

[//]: # (    window.AcousticConnect.tracker.queueEvent({)

[//]: # (        type: 'customEvent',)

[//]: # (        timestamp: Date.now(),)

[//]: # (        customData: {)

[//]: # (            // Your custom data)

[//]: # (        })

[//]: # (    });)

[//]: # (})

[//]: # (```)

## 🔒 Security

### Data Privacy

- No sensitive customer data is transmitted
- No passwords or payment details are tracked
- Only product and cart data is sent
- Customer email/address not included

### Best Practices

- Disable Debug Mode in production
- Keep plugin and WooCommerce updated
- Regular security audits

## 📊 Performance

### Impact on Site

- **Page Load**: < 10ms added
- **JavaScript Size**: ~15KB
- **Memory Usage**: Minimal
- **Database Queries**: None added

### Optimization

- Events are batched
- Asynchronous sending
- Retry logic for failed requests
- BeaconAPI for page unload

## 🔄 Updates

### Checking for Updates

The plugin follows WordPress plugin update standards. Check for updates in:
- WordPress Admin → Dashboard → Updates
- WordPress Admin → Plugins

### Changelog

See `readme.txt` for version history and changes.

## 💡 Tips & Best Practices

1. **Test in Staging First**: Always test configuration in staging before production
2. **Monitor Initially**: Enable Debug Mode when first setting up
3. **Verify Data**: Check your Acoustic Connect dashboard to confirm data receipt
4. **Disable Debug**: Turn off Debug Mode in production
5. **Regular Testing**: Periodically verify events are still being sent
6. **Keep Updated**: Update plugin and WooCommerce regularly

## 🆘 Support

### Documentation

- [Acoustic Connect Documentation](https://developer.goacoustic.com/acoustic-connect/docs/connect-sdk-overview)
- [WooCommerce Documentation](https://woocommerce.com/documentation/)

### Getting Help

1. Check this README thoroughly
2. Review Troubleshooting section
3. Check browser console for errors
4. Verify Collector URL is accessible
5. Contact Acoustic Support with specific details

## 📄 License

This plugin is licensed under GPL-2.0+.

## 🏗️ Requirements

- **WordPress**: 6.7 or higher
- **PHP**: 7.2 or higher
- **WooCommerce**: 3.0 or higher
- **Browser**: Modern browsers with JavaScript enabled

## 🤝 Credits

Developed for Acoustic Connect integration with WooCommerce.


[//]: # (`## 🔮 Future Enhancements)

[//]: # ()
[//]: # (Potential features for future releases:)

[//]: # (- Custom event builder UI)

[//]: # (- Event filtering options)

[//]: # (- Data transformation rules)

[//]: # (- Export event logs)

[//]: # (- Advanced debugging tools`)

---

**Version**: 1.1.0
**Last Updated**: January 2026
**Author**: Acoustic

For more information, visit [https://acoustic.com](https://acoustic.com)