Integrar Winclus en tu sitio

Guía técnica para el widget 0.8.6. Winclus es tecnología de apoyo que se añade a un sitio: no lo hace conforme con la norma por sí solo. Para saber cómo está tu sitio, usa Winclus Audit.

1. Una línea

Antes de </body>, en la plantilla común de todas las páginas:

<script src="https://winclus.com/widget.js" async></script>

widget.js es siempre la última versión: cuando publicamos una mejora, tu sitio la tiene en menos de 5 minutos, sin cambiar nada. Es la forma recomendada.

No frena la página. widget.js es un cargador de unos 3 KB comprimido: el widget completo (winclus-widget.min.js, minificado) se pide cuando la página ya se pintó, o enseguida si la persona ya usa Winclus (tiene ajustes guardados, dejó la cámara encendida o llega con su perfil en el enlace). Alt+Mayús+W lo trae al momento. El código legible está en winclus-widget.js, para auditarlo.

Versión fija con integridad (solo si tu política de seguridad la exige)

Si tu entidad exige integridad de subrecursos (SRI) para los scripts de terceros, usa la copia fija de una versión con su hash:

<script src="https://winclus.com/widget-0.8.6.js" async
        integrity="sha384-SsvxH2DmER/b/WH6fN73Ud8ZtI67cpzF6HKAnPqsSlHO6jpXCjC3PlfIfPHj61ml"
        crossorigin="anonymous"></script>

El atributo integrity es el hash SHA-384 del archivo: el navegador comprueba que lo que llega es exactamente esa versión y, si no coincide, no lo ejecuta. A cambio, esta versión no se actualiza nunca: para recibir las mejoras tienes que cambiar tú el número y el hash por los de la última versión publicada aquí. widget.js no lleva hash porque cambia.

Atributos opcionales en el mismo <script>:

2. Política de seguridad de contenido (CSP)

Winclus vive en un shadow root y no usa atributos style en línea, así que no necesita 'unsafe-inline'. Si tu CSP usa nonce, ponlo en el <script>: el widget lo propaga a los <style> que inyecta. Directivas mínimas:

script-src 'nonce-XYZ' https://winclus.com;
style-src  'nonce-XYZ';
img-src    https://static.arasaac.org data:;       /* pictogramas */
connect-src https://winclus.com https://api.arasaac.org https://es.wiktionary.org;
           /* winclus.com: detector de caras y diccionario de palabras, la primera vez. ARASAAC y Wikcionario: opcionales,
              solo para «Diccionario al tocar una palabra»; sin ellos responde el glosario del sitio (data-glosario) */
font-src   https://winclus.com;                    /* opcional: la letra para dislexia (OpenDyslexic); sin esto, usa Verdana */
media-src  blob:;                                  /* la cámara, si se permite */

<script nonce="XYZ" src="https://winclus.com/widget.js" async></script>

3. Web component, React, Vue, Angular, Svelte

Con winclus-elemento.js el widget es un elemento HTML. Sirve en cualquier framework y evita manipular el <head> a mano.

<script src="https://winclus.com/winclus-elemento.js" async></script>
<winclus-widget posicion="izquierda" idioma="es-CO"></winclus-widget>

React (en el componente raíz, una sola vez):

useEffect(() => {
  const s = document.createElement("script");
  s.src = "https://winclus.com/widget.js"; s.async = true; s.dataset.idioma = "es-CO";
  document.body.appendChild(s);
}, []);

Vue (en App.vue, onMounted) es idéntico. Angular: en ngOnInit del componente raíz. Svelte: en onMount. En todos los casos, el widget se inicializa una vez y sobrevive a la navegación interna (SPA); si el contenido cambia, no hace falta avisarle.

Desde JavaScript puedes hablarle: Winclus.abrir(), Winclus.cerrar(), Winclus.leer(), Winclus.decir("texto"), Winclus.teclado(), Winclus.orden("baja"), Winclus.ajustes (los ajustes vivos), Winclus.caja (el shadow root).

3b. Arreglos al vuelo para todas las ayudas técnicas

Al cargar, y cada vez que llega contenido nuevo, Winclus pone en la página lo que le falta para NVDA, JAWS, VoiceOver, TalkBack o el Narrador, no solo para su propio lector: lang en <html>, alt en imágenes a partir de lo que ya dice la página (título, pie de foto, texto del enlace o nombre del archivo; con data-describir, la descripción de tu servicio; nunca un texto inventado), nombre de botones y enlaces que solo llevan un icono, enlaces «aquí» y «leer más» con su contexto, etiquetas de campos sin etiqueta, enlace «Saltar al contenido», zona principal, foco visible cuando el sitio lo quita, zoom permitido cuando el viewport lo prohíbe, título de los iframes, cabeceras de tablas y controles en vídeos que arrancan solos con sonido.

Lo que no se puede arreglar sin riesgo (ids repetidos, saltos de nivel en los títulos, tabindex positivos, controles ocultos con aria-hidden, imágenes sin ninguna pista) se anota. En la pestaña Más del panel, «Lo que Winclus arregló en esta página» lista cada arreglo con su selector y deja copiarla para quien mantiene el sitio: un parche al vuelo ayuda hoy, pero no es cumplimiento; la corrección va en el código. Desde JavaScript: Winclus.arreglos(), Winclus.pendientes() y Winclus.informeArreglos().

En sitios públicos, informe en vez de arreglos. La Comisión Europea, el Foro Europeo de la Discapacidad y la IAAP piden que la accesibilidad se arregle en el código, no en el navegador. Por eso, en un dominio de gobierno (o con data-entidad="publica") Winclus no cambia nada de la página: prueba los mismos arreglos, los anota y los deshace en el acto. La lista dice a la entidad qué poner en su código y de dónde sacar cada dato. La ayuda a la persona (lupa, lectura, voz, cara, pulsador, pictogramas) funciona igual.

4. WordPress, Drupal, Joomla, PrestaShop y 20 plataformas más

Dónde pegar la línea en cada plataforma (Magento, Shopify, Wix, Squarespace, Webflow, Framer, HubSpot, Ghost, Moodle, Odoo, Blogger, Weebly, Jimdo, SharePoint…), el plugin de Joomla, el módulo de PrestaShop y la etiqueta lista para Google Tag Manager: winclus.com/plataformas.

WordPress: copia la carpeta integraciones/wordpress/winclus (se entrega con el acuerdo) a wp-content/plugins/ y actívalo. En Ajustes → Winclus eliges posición, cámara, idioma, Centro de Relevo, servicio de IA y la versión: por defecto «Siempre la última», que recibe las mejoras sola; la fija con integridad es para quien la exija.

Drupal 9, 10 u 11: copia integraciones/drupal/winclus a modules/custom/ y actívalo (drush en winclus). Adjunta a todas las páginas widget.js, que se actualiza solo; los atributos y la versión fija con integridad (winclus/widget_fija) están en winclus.libraries.yml.

5. Sedes electrónicas en Colombia: GOV.CO y MiColombiaDigital

Las plantillas de GOV.CO y de MiColombiaDigital permiten incluir scripts en el pie de todas las páginas desde la administración del sitio (bloque de «código en el pie» o el pie de la plantilla). Pega ahí la línea del punto 1 con data-idioma="es-CO". Recomendaciones para sujetos obligados por la Resolución 1519:

• Usa widget.js para recibir las mejoras sin tocar el sitio. Si tu política de seguridad exige integridad de subrecursos, usa la versión fija del punto 1 y anota el número en tu declaración de accesibilidad.
• Publica tu declaración de accesibilidad y enlázala desde el pie. Winclus Audit te genera el borrador.
• Añade a tu política de tratamiento de datos que el widget procesa la cámara en el navegador del usuario y que el dictado usa el reconocedor del navegador (texto de referencia en winclus.com/privacidad).
• No describas Winclus como «cumplimiento» ni «certificación»: descríbelo como tecnología de apoyo para usar el sitio con la cara, la voz, un solo pulsador y pictogramas.

6. Lectura fácil con tu propio servicio de IA

Con data-explicar="https://tu-servidor/explicar", el botón «Explicar en fácil» envía el texto de la página a tu servicio y muestra lo que devuelve (así los datos van a un servidor tuyo, no a uno de Winclus). Contrato:

POST /explicar            Content-Type: application/json
{ "texto": "…texto de la página…", "idioma": "es", "titulo": "Título" }

200 OK                    Content-Type: application/json
{ "texto": "# Resumen\n\nFrases cortas…\n\n# Pasos\n\n…" }   /* párrafos separados por línea en blanco; «# » hace un título */

Si el servicio falla, el widget usa las reglas locales. Un ejemplo de servicio con la API de Claude en Node o Python cabe en 30 líneas: recibe el texto, pide «reescríbelo en lenguaje claro, frases de menos de 20 palabras, sin jerga, con los pasos en lista» y devuelve el resultado.

7. Winclus Audit, Winclus Monitor y el informe de conformidad (ACR)

Escáner de accesibilidad: axe-core (WCAG 2.1 y 2.2 AA) en escritorio y móvil, más comprobaciones de la Resolución 1519 (texto al 200 %, declaración, ir al contenido, subtítulos, CAPTCHA que bloquean el trámite y sesiones que caducan sin aviso), cada una con el número y el nombre oficial de su criterio del Anexo 1. Genera un informe agrupado por criterio con cómo corregir cada cosa y un borrador de declaración de accesibilidad.

Se entrega con el acuerdo de soporte. Ejecución: node auditar.js https://tu-sitio.gov.co --entidad "Alcaldía de …" --salida informe. Pídelo en hola@winclus.com.

Informe de conformidad (ACR, plantilla VPAT 2.5). En la misma ejecución sale acr.html y acr.md: los 55 criterios de nivel A y AA de las WCAG 2.1 y 2.2, cada uno con su cláusula de la EN 301 549 y la Sección 508, en tres estados: «No cumple» con los elementos, «Cumple (evaluación automática)» y «Pendiente de revisión manual» con lo que hay que comprobar. Nunca marca «Cumple» a secas: una persona lo completa y lo firma. Es el documento que piden los pliegos y los compradores públicos.

Winclus Monitor: que nada empeore sin que nadie se entere. node monitor.js monitor.json pasa el escáner cada día por las páginas de la lista y por las del sitemap.xml, compara con la vez anterior, guarda el historial, actualiza un panel (panel.html: total, evolución, cada página con su cambio, si tiene el widget y el enlace a la declaración) y avisa por correo, por webhook (Slack, Teams, n8n, Make) o abriendo un issue si aparece una barrera nueva, una página deja de responder, el widget desaparece o se pierde la declaración. Se programa con monitor.ps1 (Programador de tareas de Windows), con cron o con la plantilla de GitHub Actions integraciones/github/winclus-monitor.yml. Sin límite de páginas ni de sitios.

Un escáner detecta entre el 30 y el 50 % de las barreras; el resto sale de la revisión manual y de probar con personas con discapacidad. El informe lo dice.

7b. Panel de cliente: clave de sitio, marca, cifras y monitor alojado

En winclus.com/panel se entra con un enlace al correo (sin contraseña) y se crea el sitio. Cada sitio recibe una clave que se añade a la línea: data-clave="…". Desde ese momento:

• Panel con tu marca: logo, nombre, color, lado del botón, pestañas que no quieres mostrar, cámara, idioma de la voz y a dónde llegan los avisos de barrera. Se cambia en el panel y se aplica en unos cinco minutos en todas las páginas.
• Cifras de uso: al salir de cada página el widget manda solo números (cuántas veces se abrió el panel y qué opciones se tocaron), sin identificador, sin dirección ni navegador. Se guardan sumados por día. Está dicho en «Acerca de» del panel y en la política de datos.
• Monitor alojado: las páginas que añadas se revisan cada madrugada en escritorio y móvil, con capturas, comparación con el día anterior y avisos por webhook (Slack, Teams, n8n, Make…). El motor es el mismo Winclus Monitor que puedes correr en tu servidor.
• Escáner en línea: winclus.com/escanear revisa una página en medio minuto sin cuenta.

Los límites de cada plan (sitios, sitios de prueba, páginas vigiladas, personas del equipo) están en precios.

8. Idiomas del panel

El panel habla el idioma de la página (atributo lang, o data-ui). De fábrica, 101 idiomas: las 24 lenguas oficiales de la Unión Europea, catalán, euskera y gallego; las grandes lenguas de Asia, África y Oriente Medio; chino simplificado y tradicional (Taiwán y Hong Kong, detectado por el lang de la página); y en América, quechua, guaraní, aimara y criollo haitiano. La lista completa con su nombre en cada lengua está en el panel en 101 idiomas. Español e inglés van dentro del widget; los demás son archivos idiomas/pt.json, fr.json, ar.json… (el código de dos letras del idioma) que el cargador trae solo cuando hacen falta. En árabe el panel entero se voltea de derecha a izquierda (con la versión fija hay que servirlos junto al script o cargarlos como abajo). Para otro idioma, copia uno de esos archivos, tradúcelo y sírvelo como idiomas/xx.json junto a tu copia del widget, o define antes de cargar el widget un objeto con las cadenas en español como clave:

<script nonce="XYZ">
  window.WinclusIdiomas = { pt: { "Ver mejor": "Ver melhor", "Tamaño del texto": "Tamanho do texto", /* … */ } };
</script>
<script nonce="XYZ" src="https://winclus.com/widget.js" data-ui="pt" async></script>

Lo que no esté traducido sale en español. Las voces, el reconocimiento y la lectura de la página siguen el idioma de la página (lang) y data-idioma. Para verlos sin instalar nada: el panel en 18 idiomas, con un selector.

Componentes de terceros

Pictogramas de ARASAAC (CC BY-NC-SA). Detector de caras MediaPipe (Google), que no patrocina ni respalda este producto.