API JavaScript

L’API JavaScript permette al tuo codice di leggere e modificare il consenso. La stessa API è disponibile in due modi:

• L’oggetto globale Cookiesh, creato dal tag script. Usalo nelle pagine HTML semplici e dalla console del browser.
• Il pacchetto @cookiesh/js, un wrapper tipizzato dell’oggetto globale per le app che usano un bundler. Funziona allo stesso modo e include le definizioni TypeScript.

npm install @cookiesh/js

import { cookiesh } from '@cookiesh/js';

Il pacchetto non carica una seconda copia di Cookiesh: attende il tag script e richiama l’oggetto globale. Tutti gli esempi qui sotto usano il pacchetto, ma Cookiesh.ready() e cookiesh.ready() si comportano in modo identico.

Stato del consenso

La maggior parte dei metodi restituisce o riceve un oggetto ConsentState:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Come si è arrivati allo stato attuale. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** ID casuale del record di consenso salvato, oppure null prima della prima scelta. */
  consentId: string | null;
  /** Ora della scelta in formato ISO 8601, oppure null prima della prima scelta. */
  timestamp: string | null;
  bannerVersion: string;
  /** Regione della regola applicata, ad esempio "FR" o "US-CA". */
  region: string;
}

Prima che il visitatore faccia una scelta, method vale default e le categorie riflettono lo stato predefinito della regione. Nelle regioni opt-in significa che tutto, tranne necessary, è false.

Leggere il consenso

ready()

ready(): Promise<ConsentState>

Si risolve non appena Cookiesh conosce lo stato del consenso: subito per i visitatori di ritorno, dopo il rilevamento della regione per quelli nuovi. Non attende che il visitatore faccia clic sul banner. Usalo per avviare il codice che dipende dal consenso:

const consent = await cookiesh.ready();
if (consent.analytics) initAnalytics();

getConsent()

getConsent(): ConsentState | null

Restituisce lo stato attuale in modo sincrono, oppure null se Cookiesh non ha ancora finito di caricarsi. Usa piuttosto ready(), a meno che tu non sia sicuro che lo script sia già stato caricato.

hasConsent(category)

hasConsent(category: 'necessary' | 'preferences' | 'analytics' | 'marketing'): boolean

Una scorciatoia per controllare una sola categoria. Restituisce false finché Cookiesh non si è caricato.

Modificare il consenso

Questi metodi salvano un nuovo record di consenso, esattamente come se il visitatore avesse usato il banner. Chiamali solo in risposta a un’azione chiara del visitatore, come un clic nella tua pagina delle impostazioni.

acceptAll(): Promise<ConsentState>
rejectAll(): Promise<ConsentState>
setConsent(choices: Partial<Record<'preferences' | 'analytics' | 'marketing', boolean>>): Promise<ConsentState>

// Un interruttore personalizzato nella pagina delle impostazioni dell'account
await cookiesh.setConsent({ analytics: event.target.checked });

Le categorie che non indichi mantengono il valore attuale. necessary non può essere modificato.

Mostrare l’interfaccia

showBanner(): void
openPreferences(): void
close(): void

showBanner() mostra di nuovo il banner di primo livello, anche se il visitatore ha già scelto. openPreferences() apre il centro preferenze con gli interruttori per categoria e la dichiarazione dei cookie. close() chiude l’uno o l’altro senza salvare.

Utenti con login

Per impostazione predefinita, il consenso viene salvato per browser. Nei prodotti con login, collegalo all’ID utente, così la scelta segue l’utente su tutti i suoi dispositivi:

identify(userId: string): Promise<ConsentState>
reset(): void

// Dopo l'accesso
await cookiesh.identify(session.user.id);

// Dopo la disconnessione
cookiesh.reset();

identify() cerca l’ultima scelta dell’utente. Se esiste, Cookiesh la applica su questo dispositivo e non mostra il banner. Se il visitatore ha fatto una scelta prima di accedere, quella scelta viene salvata per l’utente. Cookiesh conserva solo un hash con salt dell’ID che passi, mai l’ID stesso. Usa un ID interno opaco, non un indirizzo email.

reset() rimuove il collegamento con l’utente, ma mantiene la scelta attuale su questo dispositivo.

Attributi del tag script

Il tag script si configura con attributi data-:

Attributo	Predefinito	Descrizione
data-site-id	Obbligatorio	Il tuo Site ID, ad esempio ck_live_8f2a91
data-language	Automatico	Impone la lingua del banner (vedi Personalizzazione del banner)
data-auto-block	true	Imposta false per bloccare solo gli script a cui assegni tu una categoria
data-nonce	Nessuno	Nonce CSP applicato agli script che Cookiesh sblocca
data-consent-mode	true	Imposta false per non inviare più i segnali di Google Consent Mode

Debug

Cookiesh.debug(): void

Eseguilo nella console del browser per visualizzare la regione rilevata, la regola applicata, la versione del banner, ogni script bloccato e lo stato attuale di ogni categoria. È disponibile solo sull’oggetto globale.