API JavaScript

L’API JavaScript permet à votre propre code de lire et de modifier le consentement. Elle est disponible de deux façons :

• L’objet global Cookiesh, créé par la balise script. Utilisez-le dans les pages HTML classiques et depuis la console du navigateur.
• Le package @cookiesh/js, une surcouche typée de l’objet global pour les applications compilées avec un bundler. Il fonctionne de la même manière et inclut les définitions TypeScript.

npm install @cookiesh/js

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

Le package ne charge pas une seconde copie de Cookiesh. Il attend la balise script et appelle l’objet global. Tous les exemples ci-dessous utilisent le package, mais Cookiesh.ready() et cookiesh.ready() se comportent exactement de la même façon.

État du consentement

La plupart des méthodes renvoient ou reçoivent un objet ConsentState :

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Origine de l'état actuel. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** Identifiant aléatoire de l'enregistrement de consentement stocké, ou null avant le premier choix. */
  consentId: string | null;
  /** Heure du choix au format ISO 8601, ou null avant le premier choix. */
  timestamp: string | null;
  bannerVersion: string;
  /** Région de la règle appliquée, comme "FR" ou "US-CA". */
  region: string;
}

Avant que le visiteur ne fasse son choix, method vaut default et les catégories reflètent l’état par défaut de la région. Dans les régions opt-in, toutes les catégories sauf necessary valent donc false.

Lire le consentement

ready()

ready(): Promise<ConsentState>

Se résout dès que Cookiesh connaît l’état du consentement : immédiatement pour les visiteurs connus, après la détection de la région pour les nouveaux. Elle n’attend pas que le visiteur clique sur le bandeau. Utilisez-la pour lancer le code qui dépend du consentement :

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

getConsent()

getConsent(): ConsentState | null

Renvoie l’état actuel de manière synchrone, ou null si Cookiesh n’a pas encore fini de se charger. Préférez ready(), sauf si vous êtes certain que le script est chargé.

hasConsent(category)

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

Un raccourci pour vérifier une seule catégorie. Renvoie false tant que Cookiesh n’est pas chargé.

Modifier le consentement

Ces méthodes stockent un nouvel enregistrement de consentement, exactement comme si le visiteur avait utilisé le bandeau. Ne les appelez qu’en réponse à une action claire du visiteur, comme un clic sur votre propre page de paramètres.

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

// Un interrupteur personnalisé sur la page des paramètres du compte
await cookiesh.setConsent({ analytics: event.target.checked });

Les catégories que vous omettez conservent leur valeur actuelle. necessary ne peut pas être modifiée.

Afficher l’interface

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

showBanner() affiche de nouveau le premier niveau du bandeau, même si le visiteur a déjà fait son choix. openPreferences() ouvre le centre de préférences, avec un interrupteur par catégorie et la liste des cookies. close() ferme l’un ou l’autre sans enregistrer.

Utilisateurs connectés

Par défaut, le consentement est stocké par navigateur. Dans les produits avec espace connecté, associez-le à l’identifiant de votre utilisateur pour que son choix le suive sur tous ses appareils :

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

// Après la connexion
await cookiesh.identify(session.user.id);

// Après la déconnexion
cookiesh.reset();

identify() recherche le dernier choix de l’utilisateur. S’il en existe un, Cookiesh l’applique sur cet appareil et n’affiche pas le bandeau. Si le visiteur a fait un choix avant de se connecter, ce choix est enregistré pour l’utilisateur. Cookiesh ne stocke qu’une empreinte salée de l’identifiant transmis, jamais l’identifiant lui-même. Utilisez un identifiant interne opaque, pas une adresse e-mail.

reset() supprime le lien avec l’utilisateur, mais conserve le choix actuel sur cet appareil.

Attributs de la balise script

La balise script se configure avec des attributs data- :

Attribut	Par défaut	Description
data-site-id	Obligatoire	Votre Site ID, comme ck_live_8f2a91
data-language	Automatique	Impose la langue du bandeau (voir Personnalisation du bandeau)
data-auto-block	true	Indiquez false pour ne bloquer que les scripts que vous balisez vous-même
data-nonce	Aucun	Nonce CSP appliqué aux scripts que Cookiesh débloque
data-consent-mode	true	Indiquez false pour ne plus envoyer les signaux Google Consent Mode

Débogage

Cookiesh.debug(): void

Exécutez-la dans la console du navigateur pour afficher la région détectée, la règle appliquée, la version du bandeau, chaque script bloqué et l’état actuel de chaque catégorie. Elle n’est disponible que sur l’objet global.