API de JavaScript

La API de JavaScript permite que tu propio código consulte y cambie el consentimiento. La misma API está disponible de dos formas:

• El objeto global Cookiesh, que crea la etiqueta script. Úsalo en páginas HTML sencillas y desde la consola del navegador.
• El paquete @cookiesh/js, un envoltorio tipado del objeto global para apps empaquetadas. Funciona igual e incluye definiciones de TypeScript.

npm install @cookiesh/js

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

El paquete no carga una segunda copia de Cookiesh. Espera a la etiqueta script y llama al objeto global. Todos los ejemplos siguientes usan el paquete, pero Cookiesh.ready() y cookiesh.ready() se comportan exactamente igual.

Estado del consentimiento

La mayoría de los métodos devuelven o reciben un objeto ConsentState:

interface ConsentState {
  necessary: true;
  preferences: boolean;
  analytics: boolean;
  marketing: boolean;
  /** Cómo se ha llegado al estado actual. */
  method: 'default' | 'banner' | 'preferences' | 'api' | 'gpc';
  /** ID aleatorio del registro de consentimiento guardado, o null antes de la primera elección. */
  consentId: string | null;
  /** Momento de la elección en ISO 8601, o null antes de la primera elección. */
  timestamp: string | null;
  bannerVersion: string;
  /** Región de la regla aplicada, como "FR" o "US-CA". */
  region: string;
}

Antes de que el visitante elija, method vale default y las categorías reflejan el estado por defecto de la región. En las regiones opt-in, eso significa que todo salvo necessary es false.

Consultar el consentimiento

ready()

ready(): Promise<ConsentState>

Se resuelve en cuanto Cookiesh conoce el estado del consentimiento: al instante para los visitantes recurrentes y tras detectar la región para los nuevos. No espera a que el visitante haga clic en el banner. Úsalo para arrancar el código que depende del consentimiento:

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

getConsent()

getConsent(): ConsentState | null

Devuelve el estado actual de forma síncrona, o null si Cookiesh aún no ha terminado de cargarse. Es preferible usar ready(), salvo que tengas la certeza de que el script ya se ha cargado.

hasConsent(category)

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

Un atajo para comprobar una sola categoría. Devuelve false hasta que Cookiesh se ha cargado.

Cambiar el consentimiento

Estos métodos guardan un nuevo registro de consentimiento, exactamente igual que si el visitante hubiera usado el banner. Llámalos solo como respuesta a una acción clara del visitante, como un clic en tu propia página de configuración.

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

// Un interruptor propio en la página de configuración de la cuenta
await cookiesh.setConsent({ analytics: event.target.checked });

Las categorías que no indiques conservan su valor actual. necessary no se puede cambiar.

Mostrar la interfaz

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

showBanner() vuelve a mostrar el banner de primera capa, aunque el visitante ya haya elegido. openPreferences() abre el centro de preferencias, con interruptores por categoría y la declaración de cookies. close() cierra cualquiera de los dos sin guardar.

Usuarios con sesión iniciada

Por defecto, el consentimiento se guarda por navegador. En productos con inicio de sesión, vincúlalo al ID de tu usuario para que la elección lo acompañe en todos sus dispositivos:

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

// Tras iniciar sesión
await cookiesh.identify(session.user.id);

// Tras cerrar sesión
cookiesh.reset();

identify() busca la última elección del usuario. Si existe, Cookiesh la aplica en este dispositivo y no muestra el banner. Si el visitante eligió antes de iniciar sesión, esa elección se guarda para el usuario. Cookiesh solo guarda un hash con sal del ID que le pasas, nunca el ID en sí. Usa un ID interno opaco, no una dirección de email.

reset() elimina el vínculo con el usuario, pero mantiene la elección actual en este dispositivo.

Atributos de la etiqueta script

La etiqueta script se configura con atributos data-:

Atributo	Por defecto	Descripción
data-site-id	Obligatorio	Tu Site ID, como ck_live_8f2a91
data-language	Automático	Fuerza el idioma del banner (consulta Personalización del banner)
data-auto-block	true	Ponlo en false para bloquear solo los scripts que etiquetes tú
data-nonce	Ninguno	Nonce de CSP que se aplica a los scripts que Cookiesh desbloquea
data-consent-mode	true	Ponlo en false para dejar de enviar las señales de Google Consent Mode

Depuración

Cookiesh.debug(): void

Ejecútalo en la consola del navegador para ver la región detectada, la regla aplicada, la versión del banner, cada script bloqueado y el estado actual de todas las categorías. Solo está disponible en el objeto global.