Instala Cookies directamente

Instala Cookies directamente

Agrega el loader como el primer script del <head>, antes de cualquier tag de Google o tag opcional. Usa una versión fija: el loader carga el SDK principal desde esa misma versión. Si también usas el SDK web por npm, sigue usa el banner junto al SDK web por npm.

head

<script
  src="https://cdn.jsdelivr.net/npm/@soyio/soyio-widget@3.24.0/dist/cookie-loader.js"
  data-site-token="csite_TU_TOKEN"
  data-consent-mode="gtag"
></script>

Para sandbox, agrega data-sandbox="true". En producción omítelo o usa false. Para probar en tu máquina, sigue prueba el banner en local.

El banner detecta el idioma del navegador y usa español si no encuentra un idioma compatible. Agrega data-locale="es" o data-locale="en" para forzar un idioma.

No agregues async ni defer. El loader pesa menos de 5 KB comprimido y debe ejecutarse antes que cualquier otro script. Así fija las señales de Google en denied antes de que un gtag('config') envíe datos. El banner y el SDK principal se cargan después, sin bloquear la página.

Si el loader detecta un config o event de Google antes de su estado inicial, muestra una advertencia en la consola del navegador.

Señales de Google

El loader configura estas señales antes de importar el SDK principal:

Señal	Estado inicial	Categoría que la habilita
analytics_storage	denied	analytics
ad_storage	denied	marketing
ad_user_data	denied	marketing
ad_personalization	denied	marketing
functionality_storage	denied	functional
personalization_storage	denied	personalize
security_storage	granted	Siempre activa

El valor wait_for_update es 500 ms y no aplica regiones distintas. Soyio actualiza las señales solo después de validar el consentimiento guardado o persistir una decisión nueva.

Lee el estado validado

El loader expone window.SoyioCookieConsent. Su estado es null hasta completar la validación.

const current = window.SoyioCookieConsent?.getState();

const unsubscribe = window.SoyioCookieConsent?.addConsentListener((state) => {
  if (!state) return;

  console.log(state.decision);
  console.log(state.acceptedCategories);
  console.log(state.googleConsent);
});

// Cuando ya no necesites escuchar cambios
unsubscribe?.();

Si agregas el listener después de validar una decisión, recibe el estado actual de inmediato.

Permite cambiar las preferencias

Por defecto, el loader deja un botón flotante después de guardar una decisión. Puedes ubicarlo a la izquierda o derecha, u ocultarlo con Sin botón, desde la apariencia del banner.

Si lo ocultas, agrega un enlace en el footer o en la política de cookies para que cada persona pueda volver a abrir el diálogo.

footer

<button id="cookie-preferences" type="button">
  Preferencias de cookies
</button>

<script>
  document.getElementById('cookie-preferences').addEventListener('click', () => {
    window.SoyioCookieConsent?.showPreferences();
  });
</script>

También puedes sobrescribir la configuración desde la instalación con data-persistence-display="none", o usar data-fob-position="left" para cambiar el lado del botón.

Abre los documentos sobre tu página

Por defecto, los documentos del banner se abren en una pestaña nueva. Agrega data-document-viewer="lightbox" para abrir los documentos de privacidad en PDF en un visor sobre tu página, sin que la persona salga del sitio. Los enlaces externos y los documentos que no son PDF siguen abriéndose en una pestaña nueva.

El visor se carga desde el mismo dominio del banner, así que no necesitas cambiar tu CSP.

Para mostrar un botón de descarga del PDF en el visor, agrega también data-allow-document-download="true". Déjalo sin agregar en tótems y otros dispositivos compartidos.

Configura CSP

Ajusta estas fuentes a tu política existente:

Content-Security-Policy

script-src 'self' https://cdn.jsdelivr.net https://www.googletagmanager.com;
connect-src 'self' https://app.soyio.id https://sandbox.soyio.id;
frame-src https://cookies.soyio.id https://sandbox-cookies.soyio.id;

Si usas nonces para scripts inline, conserva el atributo nonce en el script inerte. Soyio lo copia al activarlo.

Usa el banner junto al SDK web por npm

Si tu sitio también muestra ConsentBox, ConsentFormBox o PrivacyCenterBox con el paquete @soyio/soyio-widget, la página tiene dos copias del SDK: la que carga el loader y la de tu bundle. Las dos deben estar en 3.24.0 o superior:

1. Usa 3.24.0 o superior en la URL de cookie-loader.js
2. Actualiza @soyio/soyio-widget a 3.24.0 o superior en tu proyecto

Si una de las copias es anterior a 3.24.0, la que carga después falla con Request listener already exists for IFRAME_HEIGHT_CHANGE y el box o el banner no aparece. Revisa soluciona problemas.

Prueba el banner en local

En sandbox, el banner también carga en localhost, en subdominios *.localhost y en 127.0.0.1, con el mismo sitio que registraste con tu dominio real. No necesitas crear otro sitio ni configurar HTTPS.

1. Crea y activa el sitio en sandbox con tu dominio real, por ejemplo example.com. Sigue configura y publica
2. Instala el loader 3.21.0 o superior con el token csite_... de sandbox y data-sandbox="true"
3. Abre tu servidor local, por ejemplo http://localhost:3000

head

<script
  src="https://cdn.jsdelivr.net/npm/@soyio/soyio-widget@3.24.0/dist/cookie-loader.js"
  data-site-token="csite_TU_TOKEN_SANDBOX"
  data-sandbox="true"
  data-consent-mode="gtag"
></script>

En local, Soyio guarda la cookie con la decisión solo para ese host y sin el atributo Secure. Así la decisión se mantiene al recargar, aunque uses http.

Para probar en un entorno publicado, como staging, usa cualquier subdominio del dominio registrado, por ejemplo staging.example.com.

En producción, el banner solo carga en el dominio registrado y sus subdominios. Fuera de sandbox no carga en localhost ni en una IP.

Sigue con bloqueo y verificación para convertir tus tags opcionales.