Componentes web de PrivacyKit

Documentación pública de los web components consent-dialog, consent-guard, consent-missing y compliance-monitor.

Índice

<consent-dialog>

Componente principal de la interfaz de consentimiento y de la lógica de orquestación de PrivacyKit.

Atributos

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 usuario.
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

HTML
<consent-dialog theme="panel" variant="dark" expires-days="90" 
  version="1" locale="es" hide-marketing hide-privacy-policy-link dismissible>
</consent-dialog>

Localizació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.

Detección automática

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.

Anular el idioma

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.

HTML
<consent-dialog locale="es"></consent-dialog>

Design tokens

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>

Ranuras de contenido

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

HTML
<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>

Botón flotante del diálogo

Cuando show-fab se establece en true, <consent-dialog> muestra un botón de acción flotante (FAB) que permite a los usuarios volver a abrir sus opciones de consentimiento después del envío inicial. Usa fab-position para fijarlo en la esquina inferior izquierda o inferior derecha del viewport.

Reglas de visibilidad

Oculto hasta que se haya enviado el consentimiento inicial.
Oculto mientras el diálogo de consentimiento o el diálogo de política de privacidad esté abierto.
Oculto si show-fab no está establecido o está establecido en false.

HTML
<consent-dialog show-fab fab-position="left">
</consent-dialog>

Google Consent Mode v2

Cuando google-consent-mode está habilitado, PrivacyKit lee las decisiones de consentimiento del usuario 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 usuario cambia su consentimiento. No se requiere configuración adicional más allá de añadir el atributo.

Configuración recomendada

Combinar <consent-guard> alrededor de tu fragmento de GTM con google-consent-mode en el diálogo es un enfoque de aplicación estricta: GTM no puede cargarse en absoluto antes de que se otorgue el consentimiento, y las señales de Google Consent Mode v2 se envían de inmediato en cuanto lo hace. GTM es solo un contenedor: puede alojar etiquetas de análisis, de marketing o ambas, según lo que hayas configurado dentro de él. Ajusta la expresión consent en <consent-guard> según corresponda: marketing si GTM solo dispara etiquetas de marketing/anuncios, analytics si es solo de análisis, o analytics+marketing si dispara ambas.

HTML
<!-- Match the consent expression to what GTM actually fires: "analytics" or "marketing" -->
<consent-guard consent="analytics">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXXX"></script>
</consent-guard>

<consent-dialog google-consent-mode>
</consent-dialog>

Mapeo de señales de consentimiento

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.

Cómo se envían las señales

PrivacyKit comprueba si window.gtag está disponible (Google Tag Manager o gtag.js cargado). Si lo está, llama a:

JavaScript
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'
});

Si gtag no está disponible pero window.dataLayer sí, PrivacyKit envía la actualización de consentimiento directamente al dataLayer. Si no está presente ninguno de los dos, no se envía ninguna señal y no se pone nada en cola.

Cuando Google Tag Manager está protegido por <consent-guard> — es decir, que solo se carga después de que el usuario otorgue su consentimiento — PrivacyKit reintenta automáticamente la señal una vez que GTM termina de cargarse.

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 update emitted.
Se envió una señal de consentimiento a gtag o al dataLayer.
[PrivacyKit] Google Consent Mode v2 update skipped because no Google tag was detected.
No se detectó ni gtag ni dataLayer en el navegador, por lo que no se envió nada.

Métodos del diálogo

TypeScriptReferencia de API

openConsentDialog(): void
onConsentDialogClosed(callback: () => void): () => void
openPrivacyPolicyDialog(): void

<consent-guard>

Renderiza su contenido cuando la expresión de consentimiento indicada se evalúa como verdadera.

Atributos

Atributo	Tipo	Predeterminado / Obligatorio	Descripción
consent	string	unset	Expresión de consentimiento que debe cumplirse antes de renderizar el contenido.

Expresiones de consentimiento

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 Compliance Monitor para recursos necesarios que no son reconocidos automáticamente por PrivacyKit.
preferences	Preferencias
analytics	Análisis
marketing	Marketing
preferences+analytics	Preferencias Y Análisis
preferences\|analytics	Preferencias O Análisis
preferences+marketing	Preferencias Y Marketing
preferences\|marketing	Preferencias O Marketing
analytics+marketing	Análisis Y Marketing
analytics\|marketing	Análisis O Marketing

Ejemplo 1 – Proteger scripts

HTML
<consent-guard consent="marketing">
  <script type="text/plain" data-src="https://www.googletagmanager.com/gtm/js"></script>
</consent-guard>

Ejemplo 2 – Proteger contenido incrustado

HTML
<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 Compliance Monitor.

<consent-missing>

Muestra contenido alternativo cuando un consent-guard asociado bloquea la experiencia principal.

Atributos

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>

<compliance-monitor>

Compliance Monitor 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.

Atributos

Atributo	Tipo	Predeterminado / Obligatorio	Descripción
debug	boolean	false	Habilita el panel de Compliance Monitor al cargar la página. Solo para entornos de desarrollo.
delay	number	5000	Ventana de observación de red (en milisegundos) antes de que Compliance Monitor 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 Compliance Monitor.

Ejemplo

HTML
<compliance-monitor debug delay="5000" ignore-first-party-subdomains="true" fab-position="left"></compliance-monitor>

Compliance Monitor 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=monitor a la URL — activa el monitor solo para esa sesión del navegador, sin afectar la experiencia del visitante.

Activar mediante programación:

TypeScriptReferencia de API

window.PrivacyKit?.toggleComplianceMonitor();

Apéndices

Fragmentos CSS

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.

NPM

CSS
consent-dialog:not(:defined) [slot] {
  display: none;
}

consent-guard:not([active]) {
  display: none;
}

consent-missing:not([active]) {
  display: none;
}
Si usas contenido con slot o usas consent-guards con HTML, incluye este fragmento en tu hoja de estilos global o en una etiqueta <style> que se ejecute antes de que se rendericen los web components de PrivacyKit.