Documentazione
Avvio rapido e concetti.
Questa pagina raccoglie gli snippet più importanti per integrare SimpleCMP.
Il riferimento completo dell'API vive nel repository sotto
docs/ — l'implementazione è in fase pre-1.0 e
cambia ancora.
Installazione
Due strade: come pacchetto npm per le build pipeline, oppure come script tag IIFE per siti statici e scenari drop-in.
Pacchetto npm
# con pnpm
pnpm add simplecmp
# oppure con npm
npm install simplecmp
IIFE drop-in (self-hosted)
Per motivi di privacy non distribuiamo SimpleCMP tramite CDN pubblici.
Metti il bundle nella tua directory assets/ — per la guida completa
vedi Installazione su sito statico.
<link rel="stylesheet" href="/assets/vendor/simplecmp/default.css">
<script src="/assets/vendor/simplecmp/simplecmp.global.js"></script>
<script>
SimpleCMP.init({ /* config */ });
</script>
Avvio rapido
Configurazione minima con due servizi. I link all'informativa privacy e alle note legali sono separati — importanti per il mercato tedesco (TMG/MStV).
import { init } from 'simplecmp';
init({
storageName: 'simplecmp-myapp',
privacyPolicy: 'https://example.com/datenschutz',
imprint: 'https://example.com/impressum',
floatingTrigger: { label: 'Cookie-Einstellungen' },
services: [
{
name: 'analytics',
title: 'Google Analytics',
purposes: ['analytics'],
cookies: [/^_ga/, '_gid'],
required: false,
default: false
},
{
name: 'matomo',
title: 'Matomo',
purposes: ['analytics'],
cookies: ['_pk_id', '_pk_ses'],
required: false,
default: false
}
]
});
Modalità headless
Ti serve solo la state machine, senza banner? Il subpath engine rinuncia ai componenti Lit ed è decisamente più leggero.
import { getManager, addEventListener } from 'simplecmp/engine';
const manager = getManager({
storageName: 'simplecmp-spa',
services: [/* ... */]
});
addEventListener('saveConsents', (consents) => {
console.log('Consent-State:', consents);
// aggiorna qui la tua UI personalizzata
});
// Dal tuo banner:
manager.updateConsent('analytics', true);
manager.saveConsents();
Attivare il recorder
Nella build di dev o staging attivi il recorder prima della prima
chiamata a init(). Attenzione: non usarlo in produzione senza
sampling rate.
import { init } from 'simplecmp';
import { startRecorder } from 'simplecmp/recorder';
startRecorder({
serviceDB: 'https://library.simplecmp.eu',
onUnknown: (item) => console.warn('Unknown:', item),
onKnown: (item, service) => console.log('Found:', service.name)
});
init({ services: [] });
// Dopo qualche minuto di clic:
recorder.exportConfig();
// → { services: [ { name: 'ga', cookies: [...] }, ... ] }
// In CI:
recorder.assertNoUnknown(); // throws on unknown items
Configurare la CMS-Bridge
Per l'uso in produzione: a ogni rilevamento sconosciuto SimpleCMP invia un POST al tuo webhook. La sampling rate evita flood di webhook in caso di molto traffico.
import { init } from 'simplecmp';
init({
services: [/* ... */],
bridge: {
url: 'https://example.com/api/simplecmp/webhook',
secret: window.SCMP_PUBLIC_NONCE, // nonce, not secret
sampleRate: 0.05, // 5 % dei visitatori
dedupTTL: 3600 // secondi
}
});
Lo schema webhook v2 è documentato in docs/cms-bridge-webhook.md.
Un receiver Node.js si trova in
demos/cms-bridge-receiver.mjs.
Integrare WordPress senza plugin
Il plugin WordPress è disponibile in beta.
Chi preferisce lavorare senza plugin integra SimpleCMP manualmente in
ogni tema WordPress. Nel file
functions.php:
function mytheme_enqueue_simplecmp() {
// Prima il bundle tramite `composer require` oppure manualmente in
// copiare in wp-content/themes/<theme>/assets/vendor/simplecmp/.
wp_enqueue_style(
'simplecmp',
get_template_directory_uri() . '/assets/vendor/simplecmp/default.css'
);
wp_enqueue_script(
'simplecmp',
get_template_directory_uri() . '/assets/vendor/simplecmp/simplecmp.global.js',
array(), null, false
);
$config = array(
'storageName' => 'simplecmp-' . sanitize_title(get_bloginfo('name')),
'privacyPolicy' => get_permalink(get_option('wp_page_for_privacy_policy')),
'imprint' => get_permalink(get_page_by_path('impressum')),
'services' => apply_filters('simplecmp_services', array())
);
wp_add_inline_script(
'simplecmp',
'SimpleCMP.init(' . wp_json_encode($config) . ');'
);
}
add_action('wp_enqueue_scripts', 'mytheme_enqueue_simplecmp');
Segnali di consenso del browser
SimpleCMP tiene conto del segnale Global Privacy Control
(Sec-GPC: 1) e dell'header DNT legacy. Il comportamento
predefinito è auto-decline; modificabile tramite configurazione.
init({
consentSignals: {
gpc: 'auto-decline', // oppure 'hide-banner' | 'confirm'
dnt: 'ignore' // DNT è di fatto deprecato
},
services: [/* ... */]
});
Altre risorse
La documentazione completa e tutte le ADR (Architectural Decision Records) si trovano nel repository GitHub:
Ti serve aiuto?
Supporto all'integrazione direttamente dai maintainer.
Noi di WapplerSystems usiamo SimpleCMP ogni giorno nei progetti dei clienti. Se ti serve supporto per l'introduzione, per il theming o per un'estensione su misura — siamo felici di aiutarti.