# GDPR Implementation Guide for HandL UTM Grabber Plugin

## UTM attribution overview

This guide explains GDPR Implementation Guide for HandL UTM Grabber Plugin. It helps you respect consent choices while preserving UTM parameters for compliant WordPress attribution and keep the marketing context needed for accurate reporting across forms, bookings, signups, and sales.

This documentation provides developers with the necessary information to implement GDPR compliance for the HandL UTM Grabber plugin.

## Overview

The HandL UTM Grabber plugin provides two main functions for GDPR compliance:
- `RunHandL()` - Starts tracking when consent is given
- `RemoveHandLCookies()` - Removes tracking cookies when consent is denied

## Core Functions

### RunHandL()
Initiates UTM tracking and cookie setting when user consent is obtained.

```javascript
function RunHandL() {
    // Sets up UTM tracking, cookies, and form field population
    // Only call this when user has given consent
}
```

### RemoveHandLCookies()
Removes all HandL tracking cookies when consent is denied.

```javascript
function RemoveHandLCookies() {
    console.log('Removing HandL cookies');
    handl_utm_all_params.forEach(param => {
        Cookies.remove(param, { path: '/', domain: getDomainName() });
    });
}
```

## Consent Detection Methods

The plugin supports multiple consent management platforms and methods:

### 1. Google Tag Manager (GTM) Consent Mode

```javascript
function getConsentStatus() {
    if (!window.dataLayer) {
        console.warn('dataLayer is not defined.');
        return null;
    }
    let consent = null;
    // Iterate through dataLayer in reverse to find the latest consent event
    for (let i = window.dataLayer.length - 1; i >= 0; i--) {
        if (window.dataLayer[i][0] === 'consent' && window.dataLayer[i][1] === 'update') {
            consent = window.dataLayer[i][2];
            break;
        } else if (typeof window.dataLayer[i] === 'object' && window.dataLayer[i].value && window.dataLayer[i].value.event && window.dataLayer[i].value.event.includes('consent')) {
            consent = window.dataLayer[i].value;
            break;
        }
    }
    return consent;
}

function isConsentDenied() {
    const consentStatus = getConsentStatus();
    return consentStatus && (consentStatus.ad_user_data === 'denied' && (consentStatus.analytics_storage === 'denied' || !consentStatus.analytics_storage));
}

function handleConsentStatus() {
    if (isConsentDenied()) {
        RemoveHandLCookies();
    } else {
        RunHandL();
    }
}
```

### 2. Borlabs Cookie

```javascript
// Check Borlabs cookie on page load
const borlabsCookie = Cookies.get('borlabs-cookie');
if (borlabsCookie) {
    try {
        const cookieData = JSON.parse(borlabsCookie);
        if (cookieData.consents.marketing.includes('handl-utm-grabber')) {
            console.log("handl-utm-grabber checked by Borlabs.. RunHandL...");
            RunHandL();
        } else {
            console.log("handl-utm-grabber not checked by Borlabs");
        }
    } catch (e) {
        console.error('Error parsing JSON:', e);
    }
}

// Listen for Borlabs consent changes
window.addEventListener('borlabs-cookie-consent-saved', () => {
    if (window.BorlabsCookie.Consents.hasConsent('handl-utm-grabber')) {
        RunHandL();
    }
});
```

### 3. Cookiebot

```javascript
window.addEventListener('CookiebotOnAccept', function (e) {
    if (Cookiebot.consent.marketing) {
        RunHandL();
    }
}, false);
```

### 4. Complianz

```javascript
document.addEventListener("cmplz_enable_category", function(consentData) {
    var category = consentData.detail.category;
    if (category === 'marketing') {
        RunHandL();
    }
});
```

### 5. Custom GDPR Implementation

For custom consent implementations, you can use the built-in GDPR notice:

```javascript
// Set consent cookie
Cookies.set("gdprConsent", 1); // 1 for accept, 0 for deny

// The plugin will automatically check this cookie and call appropriate functions
```

## Implementation Examples

### Basic Implementation

```javascript
// Check if consent is required
if (typeof handl_ajax.require_third_party_consent !== 'undefined' && handl_ajax.require_third_party_consent) {
    // Monitor dataLayer for consent changes
    if (!window.dataLayer) {
        window.dataLayer = [];
    }

    const originalPush = window.dataLayer.push;
    window.dataLayer.push = function(...args) {
        args.forEach(entry => {
            if (
                (Array.isArray(entry) && entry[0] === 'consent' && entry[1] === 'update')
                || (entry.event && entry.event.includes('consent'))
                || (entry.value && entry.value.event && entry.value.event.includes('consent'))
            ) {
                handleConsentStatus();
            }
        });
        return originalPush.apply(this, args);
    };
}
```

### Custom Consent Manager Integration

```javascript
// Example for a custom consent manager
function checkCustomConsent() {
    // Your consent checking logic here
    const hasConsent = yourConsentManager.hasMarketingConsent();
    
    if (hasConsent) {
        RunHandL();
    } else {
        RemoveHandLCookies();
    }
}

// Call on page load
checkCustomConsent();

// Listen for consent changes
yourConsentManager.onConsentChange(function(consent) {
    if (consent.marketing) {
        RunHandL();
    } else {
        RemoveHandLCookies();
    }
});
```

## Server-Side PHP Integration

The plugin also provides server-side consent checking:

```php
// Check if consent is given
function HandLCookieConsented() {
    $good2go = apply_filters('is_ok_to_capture_utms', array('good2go' => 1));
    return $good2go["good2go"];
}

// Use in your code
if (HandLCookieConsented()) {
    // User has given consent, proceed with tracking
    // Your tracking code here
}
```

## Configuration Options

### WordPress Admin Settings

1. **Enable GDPR**: Shows HandL's built-in consent notice
2. **Require Third-Party Consent**: Requires consent from third-party services (e.g., GTM) before tracking

### JavaScript Variables

- `handl_ajax.require_third_party_consent`: Boolean indicating if third-party consent is required
- `handl_utm_all_params`: Array of all UTM parameters that will be tracked
- `handl_utm_cookie_duration`: Cookie expiration settings

## Best Practices

1. **Always check consent before calling `RunHandL()`**
2. **Call `RemoveHandLCookies()` when consent is denied**
3. **Listen for consent changes and update accordingly**
4. **Test with different consent management platforms**
5. **Ensure your implementation works with the plugin's built-in GDPR features**

## Testing

To test your GDPR implementation:

1. Clear all cookies
2. Load the page without consent
3. Verify that `RunHandL()` is not called
4. Give consent through your consent manager
5. Verify that `RunHandL()` is called and cookies are set
6. Revoke consent
7. Verify that `RemoveHandLCookies()` is called and cookies are removed

## Troubleshooting

### Common Issues

1. **Consent not detected**: Ensure your consent manager is properly integrated and firing the correct events
2. **Cookies not removed**: Check that `getDomainName()` returns the correct domain
3. **Multiple consent managers**: Ensure only one consent manager is active to avoid conflicts

### Debug Mode

Enable console logging to debug consent issues:

```javascript
console.log('Consent status:', getConsentStatus());
console.log('Is consent denied:', isConsentDenied());
console.log('HandL cookies:', handl_utm_all_params);
```

## Support

For additional support or questions about GDPR implementation, refer to the plugin documentation or contact the development team.