# BaseCloud UTM Tracker

A WordPress plugin for tracking UTM parameters and Google Click IDs (GCLID) from marketing campaigns, with seamless Gravity Forms integration for better campaign attribution.

[![WordPress Plugin Version](https://img.shields.io/wordpress/plugin/v/basecloud-utm-tracker.svg)](https://wordpress.org/plugins/basecloud-utm-tracker/)
[![WordPress Plugin: Tested WP Version](https://img.shields.io/wordpress/plugin/tested/basecloud-utm-tracker.svg)](https://wordpress.org/plugins/basecloud-utm-tracker/)
[![License](https://img.shields.io/badge/license-GPL--2.0%2B-red.svg)](https://github.com/BaseCloudGlobal/BaseCloudUTMTracker/blob/main/LICENSE)

## 📋 Description

**BaseCloud UTM Tracker** helps marketers and website owners track the effectiveness of their marketing campaigns by automatically capturing and storing UTM parameters and Google Click IDs. The plugin seamlessly integrates with Gravity Forms to provide comprehensive campaign attribution data.

### 🌟 Key Features

- **Automatic UTM Tracking**: Captures utm_source, utm_medium, utm_campaign, utm_term, and gclid parameters
- **Cookie Storage**: Stores UTM data in secure cookies for configurable duration (1-365 days)
- **Gravity Forms Integration**: Automatically populates form fields with UTM data
- **Customizable Parameters**: Track any URL parameters you need
- **GDPR Compliant**: Respects user privacy with secure cookie handling
- **Lightweight**: Minimal performance impact on your website
- **Easy Setup**: Simple configuration through WordPress admin

## 🚀 Installation

### From WordPress.org (Recommended)

1. Go to your WordPress admin dashboard
2. Navigate to **Plugins > Add New**
3. Search for "BaseCloud UTM Tracker"
4. Click **Install Now** and then **Activate**

### Manual Installation

1. Download the plugin from [WordPress.org](https://wordpress.org/plugins/basecloud-utm-tracker/)
2. Upload the plugin files to `/wp-content/plugins/basecloud-utm-tracker/`
3. Activate the plugin through the **Plugins** menu in WordPress

### From GitHub

1. Clone this repository:
   ```bash
   git clone https://github.com/BaseCloudGlobal/BaseCloudUTMTracker.git
   ```
2. Upload the plugin folder to `/wp-content/plugins/`
3. Activate the plugin in WordPress admin

## ⚙️ Configuration

1. After activation, go to **Settings > UTM Tracker** in your WordPress admin
2. Configure the following options:

### Basic Settings

- **Enable UTM Tracking**: Turn on/off UTM parameter tracking
- **Cookie Duration**: Set how long UTM data is stored (1-365 days)
- **Gravity Forms Integration**: Enable automatic form field population

### Advanced Settings

- **Tracked Parameters**: Customize which URL parameters to track (one per line)
  - Default: utm_source, utm_medium, utm_campaign, utm_term, gclid

## 📝 Usage

### Basic UTM Tracking

Once enabled, the plugin automatically tracks UTM parameters from any URL:

```
https://yoursite.com/?utm_source=google&utm_medium=cpc&utm_campaign=summer-sale
```

### Gravity Forms Integration

1. Create a Gravity Form with fields labeled exactly as:
   - `utm_source`
   - `utm_medium` 
   - `utm_campaign`
   - `utm_term`
   - `bc_gclid` (for Google Click ID)

2. The plugin will automatically populate these fields with stored UTM data

### Example Marketing Campaign URLs

```
# Google Ads
https://yoursite.com/?utm_source=google&utm_medium=cpc&utm_campaign=summer-sale&gclid=ABC123

# Facebook Ads  
https://yoursite.com/?utm_source=facebook&utm_medium=paid&utm_campaign=product-launch

# Email Campaign
https://yoursite.com/?utm_source=newsletter&utm_medium=email&utm_campaign=weekly-digest
```

## 🛠️ Development

### Requirements

- PHP 7.4 or higher
- WordPress 5.0 or higher
- Gravity Forms (optional, for form integration)

### Local Development Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/BaseCloudGlobal/BaseCloudUTMTracker.git
   ```

2. Set up a local WordPress environment (XAMPP, Local, Docker, etc.)

3. Symlink or copy the plugin to your WordPress plugins directory

4. Activate the plugin and configure settings

### File Structure

```
BaseCloudUTMTracker/
├── basecloud-utm-tracker.php    # Main plugin file
├── readme.txt                   # WordPress.org description
├── README.md                     # GitHub documentation (this file)
├── LICENSE                       # GPL-2.0 license
├── .gitignore                   # Git ignore rules
├── deploy.ps1                   # PowerShell deployment script
├── deploy.bat                   # Batch deployment script
├── version-helper.php           # Version management utility
└── DEPLOYMENT.md               # Deployment documentation
```

### Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and test thoroughly
4. Commit your changes: `git commit -m 'Add amazing feature'`
5. Push to the branch: `git push origin feature/amazing-feature`
6. Submit a pull request

### Coding Standards

- Follow [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/)
- Use proper escaping for all output: `esc_html()`, `esc_attr()`, etc.
- Sanitize all input data
- Use WordPress hooks and filters appropriately

## 📊 Analytics Integration

The plugin works great with popular analytics platforms:

- **Google Analytics**: UTM parameters automatically tracked
- **Facebook Pixel**: Compatible with conversion tracking
- **Google Tag Manager**: Works with custom tracking events
- **HubSpot**: Integrates with contact property mapping

## 🔒 Privacy & Security

- **GDPR Compliant**: Respects user privacy preferences
- **Secure Cookies**: Uses HttpOnly and Secure flags when appropriate
- **Data Sanitization**: All data is properly sanitized and validated
- **No External Requests**: Plugin works entirely on your server

## 🐛 Troubleshooting

### UTM Parameters Not Being Tracked

1. Check that UTM tracking is enabled in plugin settings
2. Verify the URL contains proper UTM parameters
3. Check browser developer tools for JavaScript errors

### Gravity Forms Not Populating

1. Ensure field labels match exactly (case-sensitive):
   - `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `bc_gclid`
2. Verify Gravity Forms integration is enabled
3. Check that cookies are being set (browser developer tools > Application > Cookies)

### Cookie Issues

1. Verify your site is using HTTPS for secure cookies
2. Check cookie duration settings
3. Ensure no other plugins are interfering with cookies

## 📈 Changelog

### 1.0.0
- Initial release
- UTM parameter tracking
- Gravity Forms integration
- Cookie storage system
- WordPress admin configuration

## 🤝 Support

- **WordPress.org Support**: [Plugin Support Forum](https://wordpress.org/support/plugin/basecloud-utm-tracker/)
- **Documentation**: Check this README and plugin settings page
- **Bug Reports**: Use GitHub Issues for bug reports and feature requests

## 📄 License

This plugin is licensed under the GPL-2.0+ License. See the [LICENSE](LICENSE) file for details.

## 🏢 About BaseCloud

BaseCloud specializes in WordPress solutions for marketing and analytics. Visit our other projects:

- [BaseCloud Security Manager](https://github.com/BaseCloudGlobal/BaseCloudSecurityManager) - WordPress security headers management

---

**Made with ❤️ by [BaseCloud](https://basecloud.global)**

*If this plugin helps your marketing campaigns, please consider leaving a [5-star review](https://wordpress.org/support/plugin/basecloud-utm-tracker/reviews/) on WordPress.org!*