docs · para desarrolladores
API del runtime
Todo lo que puede hacer el banner es programable. El runtime expone un global, dispara cinco eventos y no renderiza ninguna UI si prefieres construir la tuya.
El global
window.CookieCrumbs.ready.then(() => {
const choice = window.CookieCrumbs.get();
// { necessary: true, analytics: false, … } or null before any decision
});| Miembro | Qué hace |
|---|---|
ready | Promesa que se resuelve cuando la configuración y el estado están cargados. |
get() | El mapa de categorías actual, o null antes de una decisión. |
set(partial) | Combinar y registrar una decisión mediante código. |
acceptAll() / rejectAll() | Registrar una concesión o un rechazo completos. |
withdraw() | Registrar una retirada (todo desactivado, tipado como retirado). |
open(layer?) / close() | Abrir el banner (la capa 2 es el panel de ajustes) u ocultarlo. |
consentId() | El ID de consentimiento seudónimo del visitante, o null. |
version() / regime() / country() / lang() | El número de versión en producción, el régimen resuelto, el país detectado y el idioma activo. |
setLang(tag) | Cambiar el idioma del banner (debe estar configurado). |
declaration(el?, lang?) | Renderizar la declaración de cookies en un elemento (por defecto: el primer [data-cc-declaration]). |
declarationUrl(lang?) | La URL de la declaración alojada. |
myConsent() | El propio registro guardado del visitante, para una página «mi consentimiento». |
on(event, cb) / off(event, cb) | Suscribirse a eventos. |
sdk | La cadena de versión del runtime. |
Eventos
Cinco eventos: ready, show (se abrió una capa), decision, update (una decisión cambiada) y withdraw. Los eventos de la familia de decisión llevan { categories, type, consentId, regime }.
El control de reapertura
Cualquier elemento con data-cc-open reabre el banner: <a href="#" data-cc-open>Configuración de cookies</a>. Los visitantes deben tener siempre una forma de volver; si desactivas el botón flotante, este enlace es obligatorio.
Modo headless
Con el diseño Headless no se renderiza ningún banner. Tú construyes la interfaz y la manejas por completo a través de esta API; el bloqueo, el registro de consentimiento, los regímenes y Consent Mode siguen funcionando por debajo.
Cómo funcionan realmente el bloqueo y la liberación
El interceptor se instala de forma síncrona, antes de descargar la configuración. Los scripts etiquetados (type="text/plain" con data-cc-category) y los scripts o iframes sin etiquetar cuyo host coincide con el mapa de bloqueo publicado se mantienen en el DOM en forma neutralizada, y se vuelven a crear en el orden del documento en cuanto se concede su categoría. Los nodos liberados una vez nunca se neutralizan de nuevo.
Código de embed al consentir
Un rastreador registrado en el panel puede llevar su propio código de embed. Al publicar se compila en la configuración, y el runtime ejecuta cada entrada exactamente una vez cuando se concede su categoría, en el momento de la decisión o en una visita posterior con consentimiento guardado. El código que ya se ejecutó no puede deshacerse con una retirada; simplemente no vuelve a ejecutarse en la siguiente carga de página.
El estado, con honestidad
La decisión vive en una sola cookie first-party, cc_consent (SameSite=Lax, Secure en https), así que sobrevive a las recargas. Los eventos de consentimiento se encolan en localStorage["cc:q"] y se envían al endpoint de consentimiento, recurriendo a sendBeacon cuando la página se está cerrando; la cola solo se vacía si hay éxito, así que una entrega fallida se reintenta en la siguiente carga. No se guarda ninguna dirección IP, user agent ni URL de página junto a un registro de consentimiento.