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. Features comprehensive i18n support for Norwegian and English.

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

Internationalization System

• Complete translation system supporting Norwegian (Bokmål) and English
• Language preference persisted with key 'gdpr-language' in localStorage
• Real-time translation updates without page reload
• Language toggle button (EN/NO) in top-right corner
• All UI text, modal content, and notifications fully localized

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, live status indicator, and i18n support
• integration-example.js - Production-ready integration examples for React, Vue, WordPress, and vanilla JS
• README.md - Documentation covering API, customization, i18n, and legal compliance
• favicon.svg, favicon.ico - Privacy-themed favicon with shield and lock design

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'

// Check current language
localStorage.getItem('gdpr-language') || 'en'

// Listen for mode changes
document.addEventListener('trackingModeChanged', (e) => {
  console.log('Mode:', e.detail.mode); // 'minimal' or 'enhanced'
});

// Set language programmatically
setLanguage('no'); // Norwegian
setLanguage('en'); // English

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
• Language toggle styling via .language-toggle and .lang-btn

Behavioral Customization

• Change storage key by modifying this.storageKey in constructor
• Customize consent message in modal HTML
• Add additional tracking services in enableEnhancedTracking() method

Internationalization Customization

• Add new languages to translations object with all required keys
• Modify Norwegian translations for local variants (e.g., Nynorsk)
• Add language detection based on browser locale
• Customize language button labels and positioning

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.