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:

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

2. Initialize When Consent is Granted

// 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:

   <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:

   <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:

// 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

// 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:

// 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

// 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