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.

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

Ejemplo

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

Botón de preferencias de consentimiento

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>

Personaliza el 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	Contenido de logotipo opcional que se muestra en el encabezado del diálogo.
dialog-logo-alt	Ubicación alternativa para un logotipo de marca, mostrada en la parte superior derecha del texto de dialog-summary-part-1.
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" 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>

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-bg-color	Color de fondo de todo el contenedor del diálogo.
--pk-paper-color	Color de papel para tarjetas, acordeones y paneles dentro del diálogo.
--pk-text-color	Color base aplicado a encabezados y cuerpo de texto.
--pk-primary-color	Acento principal para CTA, focos y enlaces.
--pk-text-color-on-primary	Color de texto usado en elementos rellenos con el color primario, como botones sólidos.
--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-border-color	Color de borde para contornos de paneles, tablas y divisores.
--pk-border-width	Ancho de borde para contornos de paneles, tablas y divisores.
--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-radius	Radio de esquina para botones, campos y controles interactivos.
--pk-dialog-radius	Radio de esquina para el contenedor exterior del diálogo de consentimiento.
--pk-dialog-shadow	Sombra de caja aplicada al 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.

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-radius: 10px;
  --pk-dialog-radius: 20px;
  --pk-dialog-shadow: 10px 20px rgba(0, 0, 0, 0.5);
  --pk-dialog-max-height: 50vh;
">
</consent-dialog>

Métodos

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.

Propiedad	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 - Bloquear/cargar scripts

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

Ejemplo 2 - Bloquear/cargar HTML

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.

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

Propiedad	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();