gdpr/CLAUDE.md

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

# 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

# Open the demo in your browser
open index.html
# or
python3 -m http.server 8000  # Then visit http://localhost:8000

Git Workflow

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

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

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.