Documentación pública de los web components consent-dialog, consent-guard, consent-missing y consent-validator.
Componente principal de la interfaz de consentimiento y de la lógica de orquestación de PrivacyKit.
| Atributo | Tipo | Predeterminado / Obligatorio | Descripción |
|---|---|---|---|
| variant | standard | panel | modern | modest | standard | Variante visual del diálogo. |
| theme | standard | dark | teal | slate | light | vibrant | high-contrast | standard | Tema visual del diálogo. |
| expires-days | number | 180 | Duración de la cookie en días. |
| version | number | 0 | Versión del esquema de consentimiento usada para revalidar. |
| google-consent-mode | boolean | unset | Emite señales de consentimiento de Google Consent Mode v2 basadas en las elecciones de consentimiento de PrivacyKit del visitante. |
| locale | da | de | en | es | fi | fr | it | nl | no | pl | sv | derivado del navegador | Sobrescribe el idioma. |
| hide-summary-part-2 | boolean | unset | Oculta la sección de resumen parte 2 (dialog-summary-part-2) del diálogo. |
| hide-necessary | boolean | unset | Oculta la categoría Necesario. |
| hide-preferences | boolean | unset | Oculta la categoría Preferencias. |
| hide-analytics | boolean | unset | Oculta la categoría Analítica. |
| hide-marketing | boolean | unset | Oculta la categoría Marketing. |
| hide-readmore | boolean | unset | Oculta la sección desplegable "Leer más". |
| hide-privacykit-badge | boolean | unset | Oculta la insignia de PrivacyKit que aparece en la parte inferior del cuerpo del diálogo de consentimiento. |
| hide-privacy-policy-link | boolean | unset | Oculta el enlace predeterminado a la Política de privacidad completamente. Usa `privacy-policy-url` en su lugar para mantener el enlace visible y redirigir a los usuarios a tu propia página de política. |
| privacy-policy-url | string | unset | URL a la que se redirige a los usuarios al hacer clic en el enlace de Política de privacidad. Cuando se establece, el enlace abre esta URL en lugar del diálogo de política de privacidad integrado. |
| demo | boolean | unset | Modo demo: desactiva la apertura automática y limita funciones. No es compatible con RGPD; no lo uses en producción. |
| dismissible | boolean | false | Controla si puede cerrarse con el fondo/escape cuando aún no hay decisión. |
| show-fab | boolean | false | Habilita el botón de preferencias de consentimiento. No tiene efecto visible hasta que exista una cookie de consentimiento. |
| fab-position | left | right | left | Fija el botón en la esquina inferior izquierda o inferior derecha del viewport. |
| dialog-position | left | right | left | Controla en qué lado de la pantalla aparece el diálogo. Solo se aplica a las variantes modern y modest — standard y panel siempre están centrados. |
Ejemplo
<consent-dialog theme="panel" variant="dark" expires-days="90"
version="1" locale="es" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>Los design tokens exponen un conjunto estable de variables CSS para personalizar colores, espaciados, tipografías y más sin tocar la implementación interna. Los temas integrados se basan en el mismo sistema de tokens, lo que te permite sobrescribir estilos individuales o crear una apariencia completamente personalizada.
| Design tokens | Descripción |
|---|---|
| --pk-transparency | Transparencia de la superficie del diálogo y de sus tarjetas/acordeones anidados, expresada en porcentaje. 0% (predeterminado) es totalmente sólido; el valor se limita a un máximo del 50%. |
| --pk-bg-color | Color de fondo de todo el contenedor del diálogo. Se combina con --pk-transparency para producir el color final. |
| --pk-paper-color | Color de papel para tarjetas, acordeones y paneles dentro del diálogo. También se combina con --pk-transparency. |
| --pk-text-color | Color base aplicado a encabezados y cuerpo de texto. |
| --pk-text-color-on-primary | Color de texto usado en elementos rellenos con el color primario, como botones sólidos. |
| --pk-primary-color | Acento principal para CTA, focos y enlaces. |
| --pk-secondary-color | Acento secundario, usado sobre todo en los interruptores. |
| --pk-focus-ring-color | Color del contorno de enfoque (outline) para estados de enfoque con teclado. |
| --pk-font-family | Familia tipográfica para todo el texto; recurre a la fuente del body si es necesario. |
| --pk-spacing-unit | Unidad de espaciado que rige paddings y separaciones. |
| --pk-control-border-color | Color de borde para los controles dentro del diálogo — tarjetas, acordeones, botones y elementos similares. |
| --pk-control-border-width | Ancho de borde para los controles dentro del diálogo — tarjetas, acordeones, botones y elementos similares. |
| --pk-control-border-radius | Radio de esquina para botones, campos y controles interactivos. |
| --pk-dialog-border-color | Color de borde para el propio marco del diálogo — el contorno del panel exterior y las líneas divisorias del encabezado/pie. |
| --pk-dialog-border-width | Ancho de borde para el propio marco del diálogo — el contorno del panel exterior y las líneas divisorias del encabezado/pie. |
| --pk-dialog-border-radius | Radio de esquina para el contenedor exterior del diálogo de consentimiento. |
| --pk-dialog-max-height | Altura máxima del diálogo de consentimiento; cuando el contenido supera este límite, el cuerpo del diálogo se desplaza. |
| --pk-dialog-shadow | Sombra de caja aplicada al diálogo de consentimiento. |
Ejemplo
<consent-dialog theme="light" style="
--pk-bg-color: #faf7f2;
--pk-paper-color: #f7eede;
--pk-primary-color: #b08968;
--pk-font-family: 'Segoe UI', Tahoma, sans-serif;
--pk-control-border-radius: 10px;
--pk-dialog-border-radius: 20px;
--pk-dialog-max-height: 50vh;
--pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
">
</consent-dialog>Inyecta contenido personalizado en partes específicas de un componente mediante slots HTML con nombre, lo que te da control total sobre el contenido y los estilos sin modificar el componente.
| Nombre del slot | Descripción |
|---|---|
| dialog-logo-top | Logotipo o imagen de marca opcional mostrado en el encabezado del diálogo de consentimiento. |
| dialog-logo-right | Logotipo o imagen de marca opcional mostrado en la parte superior derecha del diálogo de consentimiento. |
| dialog-title | Sobrescribe el título en el encabezado del diálogo. |
| dialog-summary-part-1 | Inserta texto personalizado en el primer párrafo introductorio bajo el título del diálogo. |
| dialog-summary-part-2 | Inserta texto personalizado en el segundo párrafo introductorio que explica las opciones de consentimiento. |
| necessary-content | Sustituye la descripción por defecto de la categoría Necesario. |
| preferences-content | Texto personalizado dentro del acordeón de Preferencias. |
| analytics-content | Texto personalizado dentro del acordeón de Analítica. |
| marketing-content | Texto personalizado dentro del acordeón de Marketing. |
| read-more-title | Configura el título de la sección "Leer más" al final. |
| read-more-content | Contenido mostrado al desplegar "Leer más". |
| privacy-policy-content | Reemplaza el texto predeterminado de la Política de privacidad. Usa solo lenguaje validado por tu propio asesor legal, porque PrivacyKit no puede verificar GDPR compliance una vez que lo personalizas. |
Ejemplo
<consent-dialog theme="standard" variant="standard" locale="es" version="1">
<img slot="dialog-logo-top" width="100px" src="/logo.png" alt="Logotipo de la empresa" />
<div slot="dialog-title" class="tu-clase">
<h2>Usamos cookies</h2>
</div>
<span slot="marketing-content">
<b>Actualmente no recopilamos cookies con fines de marketing.</b>
</span>
</consent-dialog>
PrivacyKit aplica automáticamente el perfil de privacidad adecuado según la ubicación detectada del visitante. No se requiere configuración adicional.
A los visitantes ubicados en Europa se les presenta el modelo de consentimiento GDPR/ePrivacy. Las tecnologías de analítica, marketing y otras no esenciales permanecen bloqueadas hasta que el visitante haya otorgado su consentimiento.
A los visitantes fuera de Europa se les presenta el modelo de privacidad CPRA. El consentimiento se otorga automáticamente, lo que permite que el sitio web funcione sin un diálogo de consentimiento inicial. Los visitantes pueden abrir el diálogo de PrivacyKit en cualquier momento para revisar o retirar sus decisiones de privacidad. Si se retira el consentimiento, PrivacyKit solicita actualizar la página para garantizar que las tecnologías bloqueadas dejen de ejecutarse.
PrivacyKit determina automáticamente si el visitante se encuentra dentro de Europa. No se requiere configuración.
<consent-dialog> incluye traducciones integradas para inglés, noruego, alemán, polaco, español, francés, italiano, neerlandés, sueco, danés y finés — sin archivos de traducción que cargar ni mantener por tu cuenta.
De forma predeterminada, el diálogo lee el idioma del navegador del visitante y muestra automáticamente la traducción correspondiente. Si el navegador está configurado en un idioma que PrivacyKit no admite, se usa el inglés como alternativa.
Para forzar un idioma específico independientemente de la configuración del navegador del visitante, establece el atributo locale — consulta la tabla anterior para ver la lista completa de códigos admitidos.
<consent-dialog locale="es"></consent-dialog>Cuando google-consent-mode está habilitado, PrivacyKit lee las decisiones de consentimiento del visitante y las señala a Google Tag Manager o gtag mediante el protocolo Google Consent Mode v2. Esto ocurre automáticamente al cargar la página y cada vez que el visitante cambia su consentimiento. No se requiere configuración adicional más allá de añadir el atributo.
PrivacyKit mapea sus tres categorías de consentimiento a los siete campos de Consent Mode v2 de Google:
| Campo GCM v2 | Mapeado desde | Valor |
|---|---|---|
| analytics_storage | Análisis | granted / denied |
| ad_storage | Marketing | granted / denied |
| ad_user_data | Marketing | granted / denied |
| ad_personalization | Marketing | granted / denied |
| functionality_storage | Preferencias | granted / denied |
| personalization_storage | Preferencias | granted / denied |
| security_storage | — | Always granted |
security_storage siempre está en granted, ya que cubre el almacenamiento del navegador esencial para la seguridad y no está sujeto al consentimiento de seguimiento opcional.
Al cargar la página, PrivacyKit se asegura de que existan window.dataLayer y una función gtag, usando el fragmento estándar de Google y conservando los que ya estén en la página. Pone en cola un valor predeterminado con todo denegado, luego el consentimiento actual del visitante, y pone en cola una actualización con cada cambio de consentimiento:
gtag('consent', 'update', {
analytics_storage: 'granted' | 'denied',
ad_storage: 'granted' | 'denied',
ad_user_data: 'granted' | 'denied',
ad_personalization: 'granted' | 'denied',
functionality_storage: 'granted' | 'denied',
personalization_storage: 'granted' | 'denied',
security_storage: 'granted'
});El dataLayer es una cola en la memoria de la página; no se guarda nada. Google Tag Manager y gtag.js procesan los comandos en cola en orden al cargarse, de modo que el estado de consentimiento se aplica antes de que se ejecute cualquier etiqueta de Google, incluso cuando Google se carga más tarde.
Si tu página tiene su propio fragmento de Google, debe conservar un dataLayer existente (window.dataLayer = window.dataLayer || [], como hacen los fragmentos de Google).
Consejo de depuración: PrivacyKit registra su actividad de Google Consent Mode v2 en la consola del navegador, para que puedas verificar el comportamiento directamente en DevTools:
[PrivacyKit] Google Consent Mode v2 enabled.
Se muestra una vez al cargar la página cuando google-consent-mode está activado. Al mismo tiempo se pone en cola el valor predeterminado con todo denegado.
[PrivacyKit] Google Consent Mode v2 update queued.
Se puso en cola una actualización de consentimiento en el dataLayer, al cargar la página y con cada cambio de consentimiento. Google la aplica cuando se cargan sus etiquetas.
openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): voidRenderiza su contenido cuando la expresión de consentimiento indicada se evalúa como verdadera.
| Atributo | Tipo | Predeterminado / Obligatorio | Descripción |
|---|---|---|---|
| consent | string | unset | Expresión de consentimiento que debe cumplirse antes de renderizar el contenido. |
| source | string | unset | De dónde se lee el consentimiento. Si no se define, el guard usa el consentimiento del diálogo de consentimiento de PrivacyKit. "google-consent-mode" lee el consentimiento recogido por tu banner de consentimiento actual a través de Google Consent Mode v2. Los valores desconocidos mantienen el guard bloqueado. |
| Expresión | Consentimiento requerido | Descripción |
|---|---|---|
| Todas las categorías | Si se omite el atributo consent, todas las categorías deben ser aceptadas para que el guard se active. | |
| necessary | Ninguno | Evita falsos positivos en Consent Validator para recursos necesarios que no son reconocidos automáticamente por PrivacyKit. |
| preferences | Preferencias | |
| analytics | Análisis | |
| marketing | Marketing | |
| preferences+analytics | Preferencias Y Análisis | Para scripts que necesitan ambos tipos de consentimiento, p. ej., el seguimiento de HubSpot. |
| preferences|analytics | Preferencias O Análisis | Para contenedores que comprueban el consentimiento por etiqueta, p. ej., Google Tag Manager. |
| preferences+marketing | Preferencias Y Marketing | Para scripts que necesitan ambos tipos de consentimiento, p. ej., el seguimiento de HubSpot. |
| preferences|marketing | Preferencias O Marketing | Para contenedores que comprueban el consentimiento por etiqueta, p. ej., Google Tag Manager. |
| analytics+marketing | Análisis Y Marketing | Para scripts que necesitan ambos tipos de consentimiento, p. ej., el seguimiento de HubSpot. |
| analytics|marketing | Análisis O Marketing | Para contenedores que comprueban el consentimiento por etiqueta, p. ej., Google Tag Manager. |
Ejemplo 1 – Proteger scripts
<consent-guard consent="analytics">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
Ejemplo 2 – Proteger contenido incrustado
<consent-guard consent="analytics+marketing">
<iframe
title="YouTube video"
data-src="https://www.youtube.com/embed/abc123"
width="560"
height="315"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowfullscreen>
</iframe>
</consent-guard>
Importante: Ten en cuenta que los recursos gestionados en los ejemplos usan data-src en lugar de src, y type="text/plain" se utiliza para scripts. PrivacyKit activa el contenido gestionado después de que se otorgue el consentimiento — de lo contrario, los recursos pueden cargarse inmediatamente y aparecer como hardcodeados en Consent Validator.
Los guards pueden aplicar el consentimiento que recoge tu banner actual. Añade source="google-consent-mode" a <consent-guard> y el guard leerá el consentimiento de tu banner en lugar del diálogo de consentimiento de PrivacyKit. Los scripts y el contenido incrustado dentro del guard solo se cargan cuando el visitante ha aceptado.
window.dataLayer, en cada carga de página y cada vez que cambia la elección.Usar el consentimiento de tu banner actual
<!-- Tu banner de consentimiento actual, con Google Consent Mode v2 activado. -->
<script src="https://cdn.your-consent-banner.com/banner.js"></script>
<!-- PrivacyKit -->
<script type="module" src="https://cdn.privacykit.eu/v1/privacykit.esm.js"></script>
<!-- Hotjar solo se carga cuando el visitante acepta la analítica en tu banner -->
<consent-guard consent="analytics" source="google-consent-mode">
<script type="text/plain" data-src="https://static.hotjar.com/c/hotjar-XXXXXXX.js?sv=6" data-async></script>
</consent-guard>
<!-- Contenido incrustado que requiere consentimiento de marketing -->
<consent-guard consent="marketing" source="google-consent-mode">
<iframe title="YouTube video" data-src="https://www.youtube.com/embed/abc123" width="560" height="315"></iframe>
</consent-guard>
Puedes usar PrivacyKit con Google Tag Manager de dos maneras: estricta, en la que Tag Manager espera al consentimiento, o flexible, en la que Tag Manager se carga de inmediato y su propia configuración de consentimiento decide qué etiquetas se activan. En ambos casos, añade google-consent-mode a <consent-dialog> para que las etiquetas de Tag Manager sepan lo que ha elegido el visitante.
No se carga nada de Tag Manager ni se envía nada a Google hasta que el visitante da su consentimiento. Un tribunal alemán (VG Hannover, 2025) ha dictaminado que cargar Google Tag Manager requiere consentimiento, y el modo estricto sigue esa interpretación. Ajusta el consentimiento del guard a lo que activa el contenedor: analytics o marketing si activa un solo tipo de etiquetas, o analytics|marketing si activa etiquetas de ambos tipos, para que se cargue en cuanto el visitante acepte cualquiera de los dos. A partir de ahí, Tag Manager gestiona el consentimiento de cada etiqueta.
<consent-dialog google-consent-mode></consent-dialog>
<consent-guard consent="analytics|marketing">
<script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX" data-async></script>
</consent-guard>
Carga Tag Manager como siempre. Las etiquetas de Google siguen las señales de Consent Mode del diálogo. Las demás etiquetas del contenedor, como Meta o LinkedIn, necesitan configuración de consentimiento en Tag Manager. Consent Validator muestra Tag Manager como no protegido por un guard. Es así por diseño: el Validator informa de todo lo que no está dentro de un guard.
El modo flexible es también la configuración para los sitios web que usan Consent Mode Advanced a propósito. Con el consentimiento denegado, las etiquetas de Google siguen enviando datos sin cookies, como la dirección de la página y los datos del dispositivo, para que Google pueda modelar conversiones. PrivacyKit admite esta configuración. Si es adecuada para tu sitio web es una decisión tuya y de tu asesor legal.
Muestra contenido alternativo cuando un consent-guard asociado bloquea la experiencia principal.
| Atributo | Tipo | Predeterminado / Obligatorio | Descripción |
|---|---|---|---|
| for | string | obligatorio | Id del elemento <consent-guard> relacionado. |
Ejemplo
<consent-guard id="analytics-guard" consent="analytics">
<script type="text/plain" data-src="https://example.com/analytics.js"></script>
</consent-guard>
<consent-missing for="analytics-guard">
Acepta las cookies de análisis para continuar.
</consent-missing>
Consent Validator observa las solicitudes salientes y valida la cobertura de los guardas de consentimiento en tu sitio web, detectando rastreadores no gestionados y regresiones introducidas por cambios en el sitio. Inactivo por defecto, permanece invisible para los visitantes y es seguro incluirlo en producción.
| Atributo | Tipo | Predeterminado / Obligatorio | Descripción |
|---|---|---|---|
| debug | boolean | false | Habilita el panel de Consent Validator al cargar la página. Solo para entornos de desarrollo. |
| delay | number | 5000 | Ventana de observación de red (en milisegundos) antes de que Consent Validator comience a validar el uso de endpoints y la cobertura de los guardas de consentimiento. |
| ignore-first-party-subdomains | boolean | true | Cuando es true, las solicitudes a subdominios del dominio actual se ignoran silenciosamente. |
| fab-position | left | right | right | Controla en qué lado del viewport se fija el FAB de Consent Validator. |
Ejemplo
<consent-validator debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></consent-validator>
Consent Validator permanece oculto para los visitantes incluso cuando se incluye en el paquete de producción. La forma recomendada de activarlo en un sitio web en producción es añadir ?privacykit=validate a la URL — activa el validador solo para esa sesión del navegador, sin afectar la experiencia del visitante.
Activar mediante programación:
window.PrivacyKit?.toggleConsentValidator();
Evita parpadeos antes de que los web components terminen de cargar. Sin este fragmento, el HTML en slots o guardado puede mostrarse brevemente cuando:
consent-dialog puede parpadear brevemente si usas elementos con slot y se renderizan antes de que cargue la definición del componente.consent-guard puede parpadear brevemente si se usa para HTML condicional y el contenido se renderiza antes de que el componente se active.consent-missing puede parpadear brevemente si se usa como fallback y se renderiza antes de que el componente se active.Añade estilos en tu propio light DOM para evitar parpadeos.
consent-dialog:not(:defined) [slot] {
display: none;
}
consent-guard:not([active]) {
display: none;
}
consent-missing:not([active]) {
display: none;
}