Saltar al contenido principal

Personalización del widget

El widget se renderiza dentro de un Shadow DOM (mode: 'open'). El CSS de tu página no alcanza sus internos, y su CSS no se filtra a tu página. Ese aislamiento es la razón por la que la personalización ocurre a través de una superficie chica y explícita, y no a través de hojas de estilo.

Color de acento​

El atributo accent-color define el fondo del botón principal, el color de los enlaces, el contorno de foco, el spinner y el relleno de progreso.

<veridia-widget accent-color="#7C3AED"></veridia-widget>

El valor por defecto es #0f172a — slate-900, muy cerca del negro. Si no definís nada, obtenés un botón casi negro. Es intencional (es neutro contra casi cualquier marca), pero sorprende a quien espera azul.

El valor se inyecta tal cual como la propiedad personalizada CSS --accent, así que funciona cualquier color CSS válido, no solo hexadecimal:

<veridia-widget accent-color="rgb(124 58 237)"></veridia-widget>
<veridia-widget accent-color="oklch(0.55 0.22 264)"></veridia-widget>
<veridia-widget accent-color="var(--brand-primary)"></veridia-widget>

La última forma es útil: var() se resuelve contra el elemento anfitrión, así que el widget puede heredar un color de tus propios design tokens.

El texto de los botones sobre la superficie de acento es blanco. Elegí un color con contraste suficiente contra el blanco para cumplir WCAG AA: los pasteles no lo cumplen.

Idioma​

locale acepta exactamente tres valores: en, es, pt.

<veridia-widget locale="es"></veridia-widget>

Si lo omitís, el widget lee navigator.language y cae a inglés para cualquier cosa que no reconozca. Cualquier otro valor que pases se ignora y aplica el fallback al idioma del navegador: el atributo se valida, no se confía en él.

Definilo explícitamente siempre que tu app ya sepa el idioma del usuario. El idioma del navegador y el de la aplicación no coinciden más seguido de lo que uno esperaría, sobre todo en dispositivos compartidos o corporativos.

locale se puede cambiar en tiempo de ejecución y el widget re-renderiza inmediatamente, pero leé primero la advertencia en Configuración si configurás el widget de forma programática.

En los pasos de captura del documento, el widget muestra un enlace "o / Subir desde la galería" debajo de los botones de cámara. El usuario elige: cámara o un archivo de su dispositivo.

Tres cosas que vale la pena saber:

  1. Es solo para el documento. El selector se renderiza exclusivamente en la rama de documento de la vista de captura, y además la función de captura rechaza en tiempo de ejecución el rol de selfie. La selfie y la ráfaga de prueba de vida activa solo pueden venir de una cámara en vivo. Son dos puntos de control independientes, y es deliberado: un dato biométrico que aceptás como archivo es un dato biométrico que un atacante puede proveer.
  2. El usuario elige; la cámara sigue siendo el valor por defecto. No hay atributo para forzar solo galería, ni para desactivar el selector.
  3. Cada cuadro se etiqueta con su procedencia (camera o upload) y esa etiqueta llega al backend.

Un límite honesto sobre el punto 3, porque tu equipo de cumplimiento lo va a preguntar: la etiqueta de procedencia es autodeclarada por el navegador y trivialmente falsificable: un atacante simplemente envía camera. Es telemetría y triaje, no un control antifraude. Su valor real es que el tráfico honesto se etiqueta con la verdad, lo que evita que las subidas desde la galería contaminen la calibración de las señales de forense documental que sí detectan documentos inyectados. Solo una atestación de plataforma podría hacer la procedencia no falsificable, y eso está fuera del alcance de un widget web.

Lo que le podés decir a cumplimiento con confianza: la captura de la selfie y de la prueba de vida no puede provenir de un archivo. Lo que no debés afirmar: que un documento marcado como camera fue fotografiado con una cámara.

Si un archivo elegido se rechaza — tipo incorrecto, o más de 20 MB — el widget muestra un mensaje inline y se queda en el paso de captura. La cámara sigue estando ahí mismo. No emite veridia:error por eso.

Tamaño​

La tarjeta interna del widget está limitada a max-width: 440px y es fluida por debajo de ese valor. No define ninguna altura mínima en su contenedor.

Ese límite está dentro del Shadow DOM, así que darle al anfitrión una caja más ancha no ensancha la tarjeta: obtenés una tarjeta de 440px dentro de un hueco vacío. Dimensioná el anfitrión a lo que realmente querés:

veridia-widget {
  display: block;
  width: 100%;
  max-width: 440px;
  margin: 0 auto;
}

No hay media queries basadas en ancho dentro del widget. Se ve bien en teléfonos porque el layout es fluido hasta 440px, no porque un breakpoint móvil lo cambie. Nada cambia en 480px.

Subclasear el custom element​

La clase del widget se exporta, así que podés extenderla y registrar tu propia etiqueta. Es la vía de escape soportada cuando los atributos no alcanzan.

import { VeridiaWidget } from 'https://widget.xxuxe.online/veridia-widget.min.js';

class AcmeKyc extends VeridiaWidget {
  connectedCallback() {
    // Valores por defecto para todas las instancias de nuestra app.
    if (!this.hasAttribute('locale')) this.setAttribute('locale', 'es');
    if (!this.hasAttribute('accent-color')) this.setAttribute('accent-color', '#7C3AED');
    super.connectedCallback();
  }
}

customElements.define('acme-kyc', AcmeKyc);
<acme-kyc publishable-key="qv_pubt_YOUR_KEY" user-ref="customer-12345"></acme-kyc>

Notas que te van a ahorrar tiempo:

  • Llamá a super en los callbacks de ciclo de vida que sobreescribas. connectedCallback lee los atributos y renderiza; saltear super te deja un elemento que nunca dibuja nada.
  • Importar el bundle registra <veridia-widget> como efecto secundario. El registro está protegido contra doble registro, así que la etiqueta de tu subclase convive con la original.
  • El shadow root es mode: 'open', así que this.shadowRoot es alcanzable desde una subclase. Pero render() reemplaza innerHTML en cada transición de estado: cualquier cosa que inyectes en el shadow root se destruye en el siguiente render. No construyas funcionalidades sobre eso.
  • Todo excepto la clase y los cuatro tipos públicos es interno y puede cambiar sin una versión mayor. Subclaseá para definir valores por defecto, envolver comportamiento o agregar tus propios listeners. No metas mano en campos privados.

Para cualquier cosa más profunda — otra tipografía, otro overlay de captura, otro flujo — la ruta soportada no es una subclase. Contactá a soporte.

Qué está fijo deliberadamente​

No podés cambiar la tipografía interna, el espaciado, el overlay de captura y la guía de encuadre, los textos, ni el orden de los pasos. Ni por CSS (Shadow DOM), ni por atributos.

El overlay de captura en particular está calibrado contra los controles de calidad: la guía de encuadre es lo que hace que el documento caiga en la región que evalúa el control de nitidez. Rediseñarla cambia las tasas de aceptación.

Qué sigue​

  • Configuración — la referencia completa de atributos.
  • Eventos — los dos eventos y los códigos de error.
  • Ejemplos — integraciones completas.