Vai al contenuto

Lingua

Menu della documentazione

Guida rapida

Installa Cookiesh in pochi minuti con HTML, Next.js o Google Tag Manager e verifica che gli script di terze parti restino bloccati fino al consenso dei visitatori.

Ultimo aggiornamento: 29 ottobre 2026

Cookiesh funziona con un solo tag script. Caricalo prima di qualsiasi altro tag della pagina e assegna una categoria agli script che richiedono il consenso: Cookiesh mostra a ogni visitatore il banner giusto per la sua regione, blocca quegli script finché il visitatore non acconsente e registra la scelta. La maggior parte dei siti è online in meno di cinque minuti.

Prima di iniziare

Ti servono un account Cookiesh e un sito. Nella dashboard apri Domains → Add domain, inserisci il tuo dominio e copia il Site ID, che ha questo formato: ck_live_8f2a91.

Cookiesh suddivide tutto in quattro categorie di consenso:

Categoria Predefinito Uso tipico
necessary Sempre attivo Sessioni, sicurezza, bilanciamento del carico, il cookie di consenso stesso
preferences Disattivato Lingua, tema e altre impostazioni memorizzate
analytics Disattivato Analisi del prodotto e del traffico
marketing Disattivato Pubblicità, retargeting e pixel dei social

Prima di andare online, avvia la tua prima scansione dei cookie dalla dashboard. Così Cookiesh sa a quale categoria appartengono script e cookie e può precompilare il tuo banner.

Installazione con HTML

Aggiungi il loader come primo script nel <head>, in modo che venga eseguito prima di qualsiasi elemento che imposta cookie:

<head>
  <script
    src="https://sdk.cookiesh.eu/v1/cookiesh.js"
    data-site-id="ck_live_8f2a91"
    async
  ></script>
  <!-- altri tag qui sotto -->
</head>

Poi cambia il tipo di ogni script che richiede il consenso da type="text/javascript" a type="text/plain" e aggiungi una categoria con data-cookiesh. Quando il visitatore autorizza quella categoria, Cookiesh ripristina il tipo originale ed esegue lo script:

<script
  type="text/plain"
  data-cookiesh="analytics"
  src="https://analytics.example.com/script.js"
></script>

<script type="text/plain" data-cookiesh="marketing">
  // Gli script inline funzionano allo stesso modo.
  initAdPixel();
</script>

Puoi bloccare anche gli iframe, come video e mappe incorporati. Usa data-cookiesh-src al posto di src e Cookiesh li caricherà dopo il consenso.

Installazione con Next.js

Installa l’SDK per React:

npm install @cookiesh/react

Carica lo script nel layout principale con la strategia beforeInteractive, così viene eseguito prima degli altri script, e racchiudi l’app in CookieshProvider:

// app/layout.tsx
import Script from 'next/script';
import { CookieshProvider } from '@cookiesh/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Script
          src="https://sdk.cookiesh.eu/v1/cookiesh.js"
          data-site-id={process.env.NEXT_PUBLIC_COOKIESH_SITE_ID}
          strategy="beforeInteractive"
        />
        <CookieshProvider>{children}</CookieshProvider>
      </body>
    </html>
  );
}

Esegui il rendering del codice che dipende dal consenso solo quando la categoria è autorizzata. useConsent() aggiorna il rendering ogni volta che il visitatore modifica la propria scelta:

// app/analytics.tsx
'use client';

import Script from 'next/script';
import { useConsent } from '@cookiesh/react';

export function Analytics() {
  const { analytics } = useConsent();
  if (!analytics) return null;

  return <Script src="https://analytics.example.com/script.js" strategy="afterInteractive" />;
}

Per i prodotti con login, passa userId a CookieshProvider per sincronizzare la scelta del visitatore su tutti i suoi dispositivi.

Installazione con Google Tag Manager

Il Community Template di Cookiesh imposta i valori predefiniti di Google Consent Mode v2 prima che si attivi qualsiasi tag e li aggiorna quando il visitatore fa la sua scelta.

  1. Nel tuo contenitore GTM apri Templates → Tag templates → Search gallery e aggiungi Cookiesh CMP.
  2. Crea un nuovo tag a partire dal template e incolla il tuo Site ID.
  3. Imposta l’attivatore su Consent Initialization – All Pages.
  4. Scegli uno stato di consenso predefinito per ogni regione. Usa denied per il SEE, il Regno Unito e la Svizzera.
  5. Per ogni tag Google apri Advanced settings → Consent settings. Lascia attivi i controlli del consenso integrati e richiedi un consenso aggiuntivo per i tag non Google.
  6. Pubblica il contenitore.

Se carichi gtag.js senza GTM, imposta tu i valori predefiniti, prima del tag Google:

<script>
  window.dataLayer = window.dataLayer || [];
  function gtag() { dataLayer.push(arguments); }

  gtag('consent', 'default', {
    ad_storage: 'denied',
    ad_user_data: 'denied',
    ad_personalization: 'denied',
    analytics_storage: 'denied',
    wait_for_update: 500,
  });
</script>

Cookiesh invia la chiamata gtag('consent', 'update', …) corrispondente non appena il visitatore fa una scelta e poi a ogni visualizzazione di pagina successiva.

Verifica l’installazione

  1. Apri il tuo sito in una finestra di navigazione privata. Il banner dovrebbe comparire e gli strumenti per sviluppatori del browser non dovrebbero ancora mostrare cookie di analisi o di marketing.
  2. Esegui Cookiesh.debug() nella console. Il comando mostra la regione rilevata, il banner attivo, ogni script bloccato e lo stato attuale del consenso.
  3. Accetta solo i cookie di analisi e ricarica la pagina. Gli script di analisi vengono eseguiti, mentre quelli di marketing restano bloccati.
  4. In Google Tag Assistant, verifica che la scheda Consent mostri gli eventi default e update nell’ordine corretto.

Passi successivi