Customização do widget

O widget renderiza dentro de um Shadow DOM (mode: 'open'). O CSS da sua página não alcança as entranhas dele, e o CSS dele não vaza para a sua página. Esse isolamento é a razão pela qual a customização acontece por uma superfície pequena e explícita, em vez de por folhas de estilo.

Cor de destaque

O atributo accent-color define o fundo do botão primário, a cor dos links, o contorno de foco, o spinner e o preenchimento da barra de progresso.

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

O default é #0f172a — slate-900, muito próximo do preto. Se você não definir nada, ganha um botão quase preto. Isso é intencional (é neutro contra praticamente qualquer marca), mas surpreende quem espera azul.

O valor é injetado literalmente como a custom property CSS --accent, então qualquer cor CSS válida funciona — não só hex:

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

A última forma é útil: var() resolve contra o element hospedeiro, então o widget pode herdar uma cor dos seus próprios design tokens.

O texto do botão sobre a superfície de destaque é branco. Escolha uma cor com contraste suficiente contra o branco para passar em WCAG AA — tons pastel não passam.

Idioma

locale aceita exatamente três valores: en, es, pt.

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

Se você omitir, o widget lê navigator.language e faz fallback para inglês em qualquer coisa que não reconheça. Qualquer outro valor que você passar é ignorado e o fallback do locale do navegador se aplica — o atributo é validado, não confiado.

Defina explicitamente sempre que seu app já souber o idioma do usuário. O locale do navegador e o do app divergem com mais frequência do que se espera, especialmente em dispositivos compartilhados ou corporativos.

locale pode ser mudado em tempo de execução e o widget re-renderiza imediatamente — mas leia primeiro o aviso em Configuração se você configura o widget programaticamente.

Upload da galeria para o documento

Nas etapas de captura de documento, o widget mostra um link "ou / Enviar da galeria" abaixo dos botões de câmera. O usuário escolhe: câmera ou um arquivo do dispositivo.

Três coisas que vale saber:

1. É só para documento. O seletor é renderizado exclusivamente no ramo de documento da tela de captura, e a função de captura adicionalmente recusa um papel de selfie em tempo de execução. A selfie e a rajada de prova de vida ativa só podem vir de uma câmera ao vivo. São dois pontos de aplicação independentes, e isso é deliberado: uma biometria que você aceita como arquivo é uma biometria que um atacante pode fornecer.
2. O usuário escolhe; a câmera continua sendo o padrão. Não há atributo para forçar apenas galeria, nem para desabilitar o seletor.
3. Todo quadro é rotulado com sua procedência (camera ou upload) e esse rótulo chega ao backend.

Um limite honesto sobre o ponto 3, porque seu time de compliance vai perguntar: o rótulo de procedência é autodeclarado pelo navegador e trivialmente falsificável — um atacante simplesmente envia camera. É telemetria e triagem, não um controle antifraude. Seu valor real é que o tráfego honesto se rotula com verdade, o que evita que uploads da galeria contaminem a calibração dos sinais de perícia documental que de fato pegam documentos injetados. Só atestação de plataforma poderia tornar a procedência não falsificável, e isso está fora do alcance de um widget web.

O que você pode dizer ao compliance com confiança: a selfie e a captura de prova de vida não podem vir de arquivo. O que você não deve afirmar: que um documento marcado como camera foi fotografado com uma câmera.

Se um arquivo escolhido for rejeitado — tipo errado, ou acima de 20 MB — o widget mostra uma mensagem inline e permanece na etapa de captura. A câmera continua ali mesmo. Ele não emite veridia:error para isso.

Dimensionamento

O card interno do widget é limitado a max-width: 440px e é fluido abaixo disso. Ele não define altura mínima no seu contêiner.

Esse limite está dentro do Shadow DOM, então dar ao hospedeiro uma caixa mais larga não alarga o card — você ganha um card de 440px sentado em um vão vazio. Dimensione o hospedeiro para o que você realmente quer:

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

Não há media queries baseadas em largura dentro do widget. Ele se lê bem em celulares porque o layout é fluido até 440px, não porque um breakpoint mobile o troca. Nada muda em 480px.

Estendendo o custom element por subclasse

A classe do widget é exportada, então você pode estendê-la e registrar sua própria tag. Esta é a saída de emergência suportada quando os atributos não bastam.

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

class AcmeKyc extends VeridiaWidget {
  connectedCallback() {
    // Defaults para toda instância no nosso 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>

Observações que vão te poupar tempo:

• Chame super nos callbacks de ciclo de vida que você sobrescrever. connectedCallback lê os atributos e renderiza; pular o super te dá um element que nunca desenha nada.
• Importar o bundle registra <veridia-widget> como efeito colateral. O registro é protegido contra registro duplicado, então sua tag de subclasse coexiste com a original.
• O shadow root é mode: 'open', então this.shadowRoot é alcançável a partir de uma subclasse. Mas render() substitui o innerHTML a cada transição de estado — qualquer coisa que você injete no shadow root é destruída no próximo render. Não construa funcionalidades em cima disso.
• Tudo, exceto a classe e os quatro tipos públicos, é interno e pode mudar sem uma versão major. Use subclasse para definir defaults, encapsular comportamento ou adicionar seus próprios listeners. Não mexa em campos privados.

Para qualquer coisa mais profunda — tipografia diferente, overlay de captura diferente, um fluxo diferente — a rota suportada não é uma subclasse. Fale com o suporte.

O que é deliberadamente fixo

Você não pode mudar a tipografia interna, os espaçamentos, o overlay de captura e o guia de enquadramento, os textos, ou a ordem das etapas. Nem por CSS (Shadow DOM), nem por atributos.

O overlay de captura em particular é calibrado contra as checagens de qualidade: o guia de enquadramento é o que faz o documento cair na região que a checagem de nitidez avalia. Redesenhá-lo muda as taxas de aceitação.

Próximos passos

• Configuração — a referência completa de atributos.
• Eventos — os dois eventos e os códigos de erro.
• Exemplos — integrações completas.