# OpenConsent v2 ๐ช
> ## **๐ Native Google Consent Mode v2 Support Without Bloated Dependencies**
>
> Zero dependencies. Full control. No monthly fees.
[](LICENSE)
[](https://www.npmjs.com/package/rs-cmp)
[]()
[]()
[]()
[]()
[]()
**The lightweight, dependency-free GDPR Consent Management Platform with native Google Consent Mode v2 support.**
The free, open-source alternative to Cookiebot, OneTrust, and Iubenda. Perfect for developers who want full control over their consent management without vendor lock-in or monthly fees.
## โจ Why OpenConsent v2?
- ๐ **No Dependencies** - Pure JavaScript, runs anywhere
- ๐ฏ **Google Consent Mode v2** - Native integration, no configuration needed
- ๐ **GDPR First** - IP hashing, secure storage, data export built-in
- โก **Lightweight** - < 40kb minified + gzipped (~15kb)
- ๐จ **Fully Customizable** - Colors, position, layout, and translations
- ๐ **SPA Support** - MutationObserver for dynamic content
- ๐ก๏ธ **CSP Compatible** - Works with Content Security Policy (nonce support)
- ๐ช **Automatic Cookie Cleaning** - Removes cookies when consent is revoked
- ๐ญ **Script Blocking** - Block tracking scripts until consent is given
- ๐ฆ **Batteries Included** - Backend examples for Node.js and PHP
## Features
### โ
Core Features (MVP)
- **One-Script Installation**: Install with a single `
```
**Step 2: Add to your website**
```html
Your Website
Your Website
```
**๐ That's it!** The CMP will:
- โ
Show a GDPR-compliant consent banner on first visit
- โ
Block ALL scripts marked with `data-category` until consent
- โ
Automatically integrate with **Google Consent Mode v2** (zero config!)
- โ
Store consent choices securely (localStorage + cookie)
- โ
Work with Google Tag Manager, Google Analytics, Facebook Pixel, etc.
**๐ฑ Try it now:** Open `examples/basic.html` in your browser to see it in action!
**๐ Optional:** Set up backend logging (see `server-side/` folder for Node.js/PHP examples)
---
## ๐ Repository Structure
```
rs-cmp/
โโโ dist/ # Minified production files
โ โโโ cmp.min.js # Ready-to-use CMP (<40kb)
โ โโโ cmp-js.min.js # Alternative build name
โโโ src/ # Source code
โ โโโ cmp.js # Main CMP implementation
โโโ examples/ # ๐ Live examples
โ โโโ basic.html # Simple implementation
โ โโโ gtm-implementation.html # Google Tag Manager integration
โโโ server-side/ # ๐ง Backend examples
โ โโโ node-logger.js # Node.js/Express logger
โ โโโ php-logger.php # PHP logger
โ โโโ README.md # Server setup guide
โโโ LICENSE # MIT License
โโโ README.md # This file
```
### ๐ฏ Try the Examples
1. **Basic Example**: [`examples/basic.html`](examples/basic.html)
- Simple implementation with all features
- Test buttons for consent management
- Live consent status display
2. **Google Tag Manager**: [`examples/gtm-implementation.html`](examples/gtm-implementation.html)
- Complete GTM integration guide
- Google Consent Mode v2 visualization
- Live consent mode status display
3. **Backend Setup**: [`server-side/`](server-side/)
- Node.js logger (Express)
- PHP logger
- Database examples (PostgreSQL, MySQL, MongoDB, SQLite)
### ๐ฆ Installation
#### Quick Start
**IMPORTANT: The CMP script must be placed immediately after the `` tag in your `<head>` section, before any other scripts!**
Add this script to your website's `<head>` section:
```html
<head>
<meta charset="UTF-8">
<title>Your Site Title
```
The CMP will:
1. Block tracking scripts immediately (before they execute)
2. Load your site configuration
3. Show the consent banner if no consent exists
4. Apply user consent choices dynamically without page reload
#### Debug Mode
To enable cookie scanning in debug mode (scans only after consent changes):
```javascript
window.RSCMP.setDebugMode(true);
```
#### Manual Script Blocking
For precise control, mark scripts with `data-category` and `type="text/plain"`:
```html
```
**How it works:**
1. Scripts with `type="text/plain"` won't execute automatically
2. When user gives consent, the CMP unblocks scripts dynamically (no page reload)
3. Consented scripts are recreated with proper type and execute
4. Non-consented scripts remain blocked as `type="text/plain"`
5. All critical script attributes (type="module", nonce, integrity, crossorigin) are preserved
**Cookie Storage:**
- Consent data is stored primarily in localStorage
- A minimal cookie (`rs-cmp-consent=1`) is used only as a presence indicator
- Full consent state is maintained in localStorage for privacy and efficiency
### ๐๏ธ Architecture
#### Frontend SDK
**NEW: SDK disponibile in TypeScript E JavaScript!**
Due versioni complete dello stesso SDK:
**Versione TypeScript**:
- **File principale**: `src/cmp.ts` - Tutto in un unico file TypeScript
- **Vanilla TypeScript** (no dependencies)
- **< 16kb minified** (gzipped ~6-7kb)
- **ES2015 compatible**
- Type safety completo
**Versione JavaScript** ๐:
- **File principale**: `src/cmp.js` - Versione JavaScript pura
- **Nessuna compilazione richiesta** - Usa direttamente nel browser
- **JSDoc completo** per documentazione tipi
- **Stesse dimensioni e funzionalitร ** della versione TypeScript
- **Vedi [JAVASCRIPT.md](JAVASCRIPT.md) per documentazione completa**
Il file consolidato include:
- Type definitions - Tutte le interfacce (TypeScript) o JSDoc (JavaScript)
- `ConsentStorage` - localStorage + cookie persistence
- `ConsentManager` - Consent state management
- `ScriptBlocker` - Automatic script blocking/unblocking
- `GoogleConsentMode` - Google Consent Mode v2 integration
- `BannerUI` - Banner UI with customization modal
- `RSCMP` - Main class with auto-initialization
**Documentazione**:
- TypeScript: vedi [USAGE.md](USAGE.md)
- JavaScript: vedi [JAVASCRIPT.md](JAVASCRIPT.md)
Struttura legacy (ancora presente per riferimento):
- `src/sdk/` - File separati originali (deprecati)
#### Backend API (`src/backend/`)
- **Fastify** - Fast, low-overhead web framework
- **PostgreSQL** - Consent logs and site configurations
- **Rate limiting** - Protection against abuse
- **IP hashing** - Privacy-first consent logging
Endpoints:
- `GET /v1/site/:id/config` - Get site configuration
- `POST /v1/consent` - Log user consent
- `GET /v1/consent/export` - Export consent logs (CSV)
- `POST /v1/site` - Create new site
- `PUT /v1/site/:id/config` - Update site configuration
### ๐๏ธ Database Schema
```sql
-- Sites table
CREATE TABLE sites (
id VARCHAR(64) PRIMARY KEY,
name VARCHAR(255) NOT NULL,
domain VARCHAR(255) NOT NULL,
config_json JSONB NOT NULL,
policy_version VARCHAR(20),
created_at TIMESTAMP,
updated_at TIMESTAMP
);
-- Consents table
CREATE TABLE consents (
id SERIAL PRIMARY KEY,
site_id VARCHAR(64) REFERENCES sites(id),
timestamp TIMESTAMP NOT NULL,
categories_json JSONB NOT NULL,
ip_hash VARCHAR(64) NOT NULL,
version VARCHAR(20)
);
```
### ๐ Development
#### Prerequisites
- Node.js 18+
- PostgreSQL 14+
#### Setup
1. Install dependencies:
```bash
npm install
```
2. Set up database:
```bash
psql -U postgres -f database/schema.sql
```
3. Configure environment:
```bash
cp .env.example .env
# Edit .env with your database credentials
```
4. Build the SDK:
```bash
npm run build:sdk
```
5. Start the backend:
```bash
npm run dev:backend
```
#### Build Commands
```bash
# Build TypeScript SDK (development)
npm run build:sdk:dev
# Build TypeScript SDK (production, minified)
npm run build:sdk:prod
# Build both TypeScript SDK versions
npm run build:sdk
# Build JavaScript SDK (development)
npm run build:sdk:js:dev
# Build JavaScript SDK (production, minified)
npm run build:sdk:js:prod
# Build both JavaScript SDK versions
npm run build:sdk:js
# Build backend
npm run build:backend
# Build everything (TypeScript SDK + JavaScript SDK + Backend)
npm run build
```
### ๐ Configuration
Default configuration includes:
```json
{
"banner": {
"position": "bottom",
"layout": "bar",
"primaryColor": "#2563eb",
"backgroundColor": "#ffffff",
"textColor": "#1f2937",
"buttonTextColor": "#ffffff",
"showLogo": false,
"privacyPolicyUrl": "https://yoursite.com/privacy",
"cookiePolicyUrl": "https://yoursite.com/cookies"
},
"categories": [
{
"id": "necessary",
"name": "Necessary",
"required": true,
"enabled": true
},
{
"id": "analytics",
"name": "Analytics",
"required": false,
"enabled": false
},
{
"id": "marketing",
"name": "Marketing",
"required": false,
"enabled": false
},
{
"id": "preferences",
"name": "Preferences",
"required": false,
"enabled": false
}
]
}
```
**โ ๏ธ IMPORTANT for GDPR Compliance**: Always set `privacyPolicyUrl` and `cookiePolicyUrl` in your configuration. These links will appear in the consent banner, allowing users to read detailed information about data processing before giving consent (required by GDPR Art. 13).
### ๐ Supported Languages
- English (en)
- Italian (it)
More languages can be added in the site configuration.
### ๐ Security Features
- **IP Hashing**: SHA-256 hashing of IP addresses before storage
- **Rate Limiting**: 100 requests per minute per IP
- **CORS Protection**: Configurable CORS policies
- **CSP Friendly**: Compatible with Content Security Policy
- **No Cookies Before Consent**: Zero cookies until user accepts
### ๐ Compliance
- โ
GDPR compliant
- โ
ePrivacy Directive compliant
- โ
Google Consent Mode v2 ready
### ๐ฏ Performance
- Script size: **< 40kb** (minified + gzipped)
- Lighthouse impact: **< 10ms** blocking time
- 100% scripts blocked before consent
- Async loading supported
### ๐ฎ Roadmap (v2)
- [ ] A/B testing for banner variations
- [ ] Geo-targeting (EU-only mode)
- [ ] Server-side consent API
- [ ] WordPress plugin
- [ ] Shopify app
- [ ] Multi-domain support
- [ ] White-label options
- [ ] Advanced analytics dashboard
- [ ] Privacy policy generator
### ๐ License
MIT License - see LICENSE file for details
### ๐ค Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
### ๐ง Support
For support and questions, please open an issue on GitHub.