# UTMSimple Consent Mode Guide (GDPR)

UTMSimple now supports conditional consent mode that integrates seamlessly with Google Tag Manager (GTM) and other consent management systems.

## How It Works

When `UTMSIMPLE_CONSENT_MODE = true` is set globally, UTMSimple will not automatically initialize. Instead, you can manually call `HandL.init()` when consent is granted.

## Basic Implementation

### 1. Enable Consent Mode

Set the global flag before loading UTMSimple:

```html
<script>
    window.UTMSIMPLE_CONSENT_MODE = true;
</script>
<script src="path/to/utmsimple.js"></script>
```

### 2. Initialize When Consent is Granted

```javascript
// When user grants consent
window.UTMSIMPLE_CONSENT_MODE = false;
HandL.init();
```

## GTM Integration

### Method 1: Using GTM Variables and Triggers

1. **Create a GTM Variable** for consent status:
   - Variable Type: Custom JavaScript
   - Code: `return window.UTMSIMPLE_CONSENT_MODE || false;`

2. **Create a Trigger** for consent granted:
   - Trigger Type: Custom Event
   - Event Name: `consent_granted`
   - Or use GTM's built-in consent mode triggers

3. **Create a Custom HTML Tag** to initialize UTMSimple:
   ```html
   <script>
   if (typeof HandL !== 'undefined') {
       window.UTMSIMPLE_CONSENT_MODE = false;
       HandL.init();
   }
   </script>
   ```

### Method 2: Using GTM Consent Mode

1. **Enable GTM Consent Mode** in your container settings

2. **Set consent mode variable**:
   ```html
   <script>
   window.UTMSIMPLE_CONSENT_MODE = true;
   </script>
   ```

3. **Create a trigger** based on consent mode changes:
   - Trigger Type: Consent Initialization
   - Consent Type: analytics_storage (or your preferred consent type)

4. **Fire UTMSimple initialization** when consent is granted

## Advanced Usage

### Cookie Management

UTMSimple provides a method to delete all cookies it has created:

```javascript
// Delete all UTMSimple cookies and localStorage data
const result = HandL.deleteAllCookies();

// Result object contains:
// - deletedCount: number of cookies deleted
// - cookiesDeleted: array of cookie names that were deleted
```

This method:
- Deletes all UTM parameter cookies
- Deletes first-touch parameter cookies
- Deletes UTMSimple-specific cookies (handlID, handl_js_domain, etc.)
- Clears localStorage items used for Facebook advanced matching
- Fires a `UTMSimpleCookiesDeleted` event
- Returns a result object with deletion details

### Checking Consent Status

```javascript
// Check if consent mode is enabled
if (typeof window.UTMSIMPLE_CONSENT_MODE !== "undefined" && window.UTMSIMPLE_CONSENT_MODE === true) {
    console.log('Consent mode is active');
}

// Check if HandL is available
if (typeof HandL !== 'undefined') {
    console.log('UTMSimple is loaded');
}
```

### Event Listeners

UTMSimple fires custom events that you can listen to:

```javascript
// Listen for successful initialization
document.addEventListener('UTMSimpleLoaded', function() {
    console.log('UTMSimple loaded successfully');
});

// Listen for cookie setting
document.addEventListener('UTMSimpleCookiesSet', function() {
    console.log('UTMSimple cookies have been set');
});

// Listen for cookie deletion
document.addEventListener('UTMSimpleCookiesDeleted', function(event) {
    console.log(`UTMSimple cookies deleted: ${event.detail.deletedCount} cookies removed`);
});
```

### Dynamic Consent Management

```javascript
// Grant consent
function grantConsent() {
    window.UTMSIMPLE_CONSENT_MODE = false;
    if (typeof HandL !== 'undefined') {
        HandL.init();
    }
}

// Revoke consent (for future page loads)
function revokeConsent() {
    window.UTMSIMPLE_CONSENT_MODE = true;
    // Delete all cookies when consent is revoked
    if (typeof HandL !== 'undefined') {
        HandL.deleteAllCookies();
    }
    // Note: This won't stop already running scripts, just prevents future initialization
}

// Delete all UTMSimple cookies and localStorage data
function deleteAllCookies() {
    if (typeof HandL !== 'undefined') {
        const result = HandL.deleteAllCookies();
        console.log(`Deleted ${result.deletedCount} cookies`);
        return result;
    }
}
```

## Example Implementation

See `consent_example.html` for a complete working example that demonstrates:
- Enabling consent mode
- Granting/revoking consent
- Manual initialization
- Event listening
- Status checking

## Best Practices

1. **Set consent mode before loading UTMSimple** to prevent any initialization
2. **Use GTM's consent mode** for comprehensive consent management
3. **Listen for UTMSimple events** to confirm successful initialization
4. **Test consent flows** thoroughly in development
5. **Consider user experience** - don't block essential functionality

## Troubleshooting

### Script Not Initializing
- Check if `UTMSIMPLE_CONSENT_MODE` is set to `true`
- Ensure `HandL.init()` is called after consent is granted
- Verify UTMSimple script is loaded before calling `HandL.init()`

### GTM Integration Issues
- Ensure GTM variables are properly configured
- Check trigger conditions match your consent logic
- Verify custom HTML tags are firing at the right time

### Console Errors
- Look for "Consent mode enabled" messages in console
- Check for "HandL not available" warnings
- Ensure all dependencies are loaded