Ole-Morten Duesund
2d693605cf
- 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 <noreply@anthropic.com>
128 lines
No EOL
4.2 KiB
Markdown
128 lines
No EOL
4.2 KiB
Markdown
# 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. |