From 2d693605cfd7e6b18289143a06be6695d5763ace Mon Sep 17 00:00:00 2001 From: Ole-Morten Duesund Date: Mon, 8 Sep 2025 12:59:47 +0200 Subject: [PATCH] Add GDPR compliant optional tracking solution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Complete demo with privacy-first hero section and live status indicator - Production-ready integration examples for React, Vue, WordPress, and vanilla JS - Comprehensive documentation covering API, customization, and legal compliance - GDPR compliant by default with enhanced tracking only on explicit consent 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 128 ++++++++++ README.md | 161 ++++++++++++ index.html | 552 +++++++++++++++++++++++++++++++++++++++++ integration-example.js | 289 +++++++++++++++++++++ 4 files changed, 1130 insertions(+) create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 index.html create mode 100644 integration-example.js diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b6fa139 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,128 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Information + +- **Git Repository**: ssh://git@kode.naiv.no:2222/olemd/gdpr.git +- **Forgejo Server**: https://kode.naiv.no +- **Owner**: olemd + +## Project Overview + +This is a GDPR-compliant optional tracking solution that provides a privacy-first approach to website analytics. The core concept is "minimal tracking by default, enhanced tracking by consent" - users start with privacy-protected minimal tracking and can opt-in to enhanced features. + +## Architecture + +### Core Components + +**GDPRTrackingConsent Class** (`index.html`) +- Main JavaScript class that manages consent state and UI interactions +- Handles localStorage persistence with key 'gdpr-tracking-consent' +- Integrates with Google Analytics consent modes (`analytics_storage`, `ad_storage`, `personalization_storage`) +- Manages cookie cleanup for tracking cookies (`_ga`, `_gid`, `_gat`, `_fbp`, `_fbc`) +- Fires custom events (`trackingModeChanged`) for external integrations + +**Two-Mode System** +- **Minimal Mode**: Essential cookies only, anonymized analytics, consent denied by default +- **Enhanced Mode**: Full tracking enabled only after explicit user consent + +### Key Files + +- `index.html` - Complete demo with hero section, feature explanations, and live status indicator +- `integration-example.js` - Production-ready integration examples for React, Vue, WordPress, and vanilla JS +- `README.md` - Documentation covering API, customization, and legal compliance + +## Development Commands + +### Repository Operations +```bash +# Clone the repository +git clone ssh://git@kode.naiv.no:2222/olemd/gdpr.git + +# Use fj (Forgejo CLI) for repository management +fj repo view olemd/gdpr +fj issue list +fj pr list +``` + +### Testing the Demo +```bash +# Open the demo in your browser +open index.html +# or +python3 -m http.server 8000 # Then visit http://localhost:8000 +``` + +### Git Workflow +```bash +# Standard git operations work with the Forgejo server +git push origin main +git pull origin main +``` + +### Integration Testing +The solution integrates with Google Analytics via consent modes: +```javascript +// Check current consent status +localStorage.getItem('gdpr-tracking-consent') === 'true' + +// Listen for mode changes +document.addEventListener('trackingModeChanged', (e) => { + console.log('Mode:', e.detail.mode); // 'minimal' or 'enhanced' +}); +``` + +## Key Implementation Details + +### Consent Flow +1. Page loads with minimal tracking (GDPR compliant by default) +2. User sees "Plz trac me!" button in bottom-right +3. Clicking shows consent modal with clear explanation +4. User can enable enhanced tracking or dismiss +5. Status persisted in localStorage, toggleable anytime + +### Google Analytics Integration +The solution expects Google Analytics to be initialized with consent mode: +```javascript +gtag('consent', 'default', { + 'analytics_storage': 'denied', + 'ad_storage': 'denied', + 'personalization_storage': 'denied' +}); +``` + +The button automatically calls `gtag('consent', 'update', {...})` when user changes preferences. + +### Cookie Management +- Automatically cleans up tracking cookies when switching to minimal mode +- Uses domain-aware cookie deletion for cross-subdomain cleanup +- Preserves essential functionality cookies (`functionality_storage: 'granted'`) + +## Customization Points + +### UI Customization +- Button styling via CSS classes `.tracking-consent-btn` and `.tracking-consent-btn.enabled` +- Modal content in `.consent-modal-content` +- Status indicator in `.tracking-status` + +### Behavioral Customization +- Change storage key by modifying `this.storageKey` in constructor +- Customize consent message in modal HTML +- Add additional tracking services in `enableEnhancedTracking()` method + +### Framework Integration +The `integration-example.js` contains complete examples for: +- WordPress (functions.php and shortcode approaches) +- React (hooks-based component) +- Vue.js (composition API) +- Minified standalone snippet for any website + +## Legal Compliance Notes + +This implementation addresses technical requirements for: +- GDPR Article 7 (explicit consent) +- ePrivacy Directive cookie requirements +- CCPA transparency requirements + +However, legal compliance requires consultation with legal experts for specific jurisdictions and use cases. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..63d7bcc --- /dev/null +++ b/README.md @@ -0,0 +1,161 @@ +# GDPR Compliant Optional Tracking Button + +A lightweight, user-friendly JavaScript solution for implementing GDPR-compliant optional tracking on websites. By default, only minimal tracking is enabled, and users can opt-in to enhanced tracking with a fun "Plz trac me!" button. + +## Features + +- 🔒 **GDPR Compliant by Default**: Minimal tracking until user consents +- 🎨 **Beautiful UI**: Gradient button with hover effects and smooth animations +- 📱 **Mobile Responsive**: Works perfectly on all device sizes +- ⚡ **Lightweight**: Pure vanilla JavaScript, no dependencies +- 🔧 **Easy Integration**: Drop-in solution for any website +- 🍪 **Cookie Management**: Automatic cleanup when tracking is disabled +- 📊 **Analytics Ready**: Google Analytics consent mode integration + +## Demo + +Open `gdpr-tracking-consent.html` in your browser to see the button in action! + +## Quick Start + +### Option 1: Standalone HTML (Recommended for testing) +```html + + +``` + +### Option 2: Minified Snippet (Production ready) +```html + +
+ +
+ +``` + +## How It Works + +### Default State (GDPR Compliant) +- Only essential cookies are allowed +- Basic analytics with anonymized IP +- No personalization or ad tracking +- No cross-site tracking + +### Enhanced Tracking (User Opt-in) +- Detailed page interactions +- User preferences for personalization +- Marketing campaign effectiveness +- Full Google Analytics features + +## Integration Examples + +### WordPress +```php +// Add to functions.php +function add_gdpr_tracking_consent() { + // Include the snippet +} +add_action('wp_footer', 'add_gdpr_tracking_consent'); +``` + +### React +```jsx +import GDPRTrackingConsent from './GDPRTrackingConsent'; + +function App() { + return ( +
+ {/* Your app content */} + +
+ ); +} +``` + +### Google Analytics Setup +```html + +``` + +## Customization + +### Button Text +```javascript +// Change the button text +btnText.textContent = 'Enable Analytics'; +``` + +### Styling +```css +.tracking-consent-btn { + /* Customize colors, position, size */ + background: your-gradient; + bottom: 30px; + right: 30px; +} +``` + +### Consent Modal +```javascript +// Customize the consent message +const consentText = "Your custom consent message here"; +``` + +## API Events + +The button fires custom events you can listen to: + +```javascript +document.addEventListener('trackingModeChanged', (e) => { + console.log('Tracking mode:', e.detail.mode); // 'minimal' or 'enhanced' +}); +``` + +## Cookie Management + +```javascript +// Access the consent status +const isTrackingEnabled = localStorage.getItem('gdpr-tracking-consent') === 'true'; + +// Programmatically enable/disable +window.trackingConsent.enableTracking(); +window.trackingConsent.disableTracking(); +``` + +## Browser Support + +- Modern browsers (ES6+) +- Internet Explorer 11+ (with polyfills) +- All mobile browsers + +## Files + +- `gdpr-tracking-consent.html` - Complete demo with all features +- `integration-example.js` - Integration examples for different frameworks +- `README.md` - This documentation + +## Legal Compliance + +This solution helps with: +- ✅ GDPR Article 7 (Consent) +- ✅ ePrivacy Directive +- ✅ CCPA compliance +- ✅ Cookie Law compliance + +**Note**: This is a technical implementation. Always consult with legal experts for complete GDPR compliance in your specific jurisdiction and use case. + +## License + +MIT License - Feel free to use in any project! \ No newline at end of file diff --git a/index.html b/index.html new file mode 100644 index 0000000..8ef2d8d --- /dev/null +++ b/index.html @@ -0,0 +1,552 @@ + + + + + + 🍪 Privacy-First Demo | GDPR Compliant Tracking + + + +
+
+ Privacy Mode: Minimal Tracking +
+ +
+
+
+ 🔒 GDPR Compliant by Default +
+ +

Privacy-First Demo

+

+ Experience truly optional tracking. Your privacy is protected by default,
+ with enhanced features available only when you choose to enable them. +

+ +
+

🎯 How It Works

+

This demo shows how modern websites can respect your privacy while still providing great experiences:

+ +
+
+ 🔒 +
+ Default: Privacy Protected
+ Only essential cookies, anonymized analytics +
+
+
+ 📊 +
+ Optional: Enhanced Tracking
+ Detailed analytics, personalization when you opt-in +
+
+
+ 🎚️ +
+ Full Control
+ Toggle anytime with the button below +
+
+
+ 🍪 +
+ Smart Cookie Management
+ Automatic cleanup when disabled +
+
+
+ +

Try it out! Click the colorful button in the bottom-right corner to see the consent flow in action. 👇

+
+
+
+ +
+ +
+ + + + + + \ No newline at end of file diff --git a/integration-example.js b/integration-example.js new file mode 100644 index 0000000..377c641 --- /dev/null +++ b/integration-example.js @@ -0,0 +1,289 @@ +/** + * GDPR Tracking Consent - Integration Example + * + * This file shows how to integrate the GDPR tracking consent button + * into your existing website or application. + */ + +// Standalone JavaScript snippet (minified version for production) +const gdprTrackingSnippet = ` +
+ +
+ +`; + +// Integration examples for different scenarios + +// 1. WordPress Integration +const wordPressIntegration = { + // Add to functions.php + php: ` + + + ${gdprTrackingSnippet} + `, + + // Or as a WordPress shortcode + shortcode: ` + +` +}; + +// 2. React Integration +const reactIntegration = ` +import React, { useEffect, useState } from 'react'; + +const GDPRTrackingConsent = () => { + const [isTrackingEnabled, setIsTrackingEnabled] = useState(false); + const [showModal, setShowModal] = useState(false); + + useEffect(() => { + const consent = localStorage.getItem('gdpr-tracking-consent') === 'true'; + setIsTrackingEnabled(consent); + + if (consent) { + enableEnhancedTracking(); + } else { + enableMinimalTracking(); + } + }, []); + + const enableTracking = () => { + localStorage.setItem('gdpr-tracking-consent', 'true'); + setIsTrackingEnabled(true); + setShowModal(false); + enableEnhancedTracking(); + }; + + const disableTracking = () => { + if (window.confirm('Disable enhanced tracking?')) { + localStorage.setItem('gdpr-tracking-consent', 'false'); + setIsTrackingEnabled(false); + enableMinimalTracking(); + } + }; + + const enableMinimalTracking = () => { + console.log('🔒 GDPR Mode: Minimal tracking'); + if (typeof window.gtag !== 'undefined') { + window.gtag('consent', 'update', { + 'analytics_storage': 'denied', + 'ad_storage': 'denied' + }); + } + }; + + const enableEnhancedTracking = () => { + console.log('📊 Enhanced tracking enabled'); + if (typeof window.gtag !== 'undefined') { + window.gtag('consent', 'update', { + 'analytics_storage': 'granted', + 'ad_storage': 'granted' + }); + } + }; + + return ( + <> +
+ +
+ + {showModal && ( +
+
+

Optional Enhanced Tracking

+

We respect your privacy! Enable enhanced tracking to help us improve.

+
+ + +
+
+
+ )} + + ); +}; + +export default GDPRTrackingConsent;`; + +// 3. Vue.js Integration +const vueIntegration = ` + + +`; + +// 4. Google Analytics Integration +const googleAnalyticsSetup = ` + + +`; + +// 5. Cookie Management Integration +const cookieManagement = ` +// Cookie utility functions for GDPR compliance +class GDPRCookieManager { + static setCookie(name, value, days = 365, sameSite = 'Lax') { + const expires = new Date(Date.now() + days * 864e5).toUTCString(); + document.cookie = \`\${name}=\${value}; expires=\${expires}; path=/; SameSite=\${sameSite}\`; + } + + static getCookie(name) { + return document.cookie.split('; ').reduce((r, v) => { + const parts = v.split('='); + return parts[0] === name ? decodeURIComponent(parts[1]) : r; + }, ''); + } + + static deleteCookie(name) { + document.cookie = \`\${name}=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/\`; + } + + static cleanupTrackingCookies() { + const trackingCookies = ['_ga', '_gid', '_gat', '_fbp', '_fbc', '_hjid']; + trackingCookies.forEach(cookie => this.deleteCookie(cookie)); + } +}`; + +// Export all integration examples +module.exports = { + gdprTrackingSnippet, + wordPressIntegration, + reactIntegration, + vueIntegration, + googleAnalyticsSetup, + cookieManagement +}; \ No newline at end of file