SDK web

O SDK web da Certivant é um pequeno script, sem dependências, que abre uma verificação dentro da sua página — em um modal ou inline em um contêiner — e informa ao seu código quando o solicitante chega a cada etapa e quando termina. O solicitante nunca sai do seu site, e nenhum dado pessoal passa pela sua página: o SDK informa apenas o nome de uma etapa, um status final e um id público.

Ele incorpora as mesmas páginas hospedadas que você já pode enviar por link:

1. Permita o seu site

Os navegadores só exibem uma página em um frame quando o responsável pela página concorda. Em Configurações → KYC → Incorporação, adicione as origens dos sites que vão incorporá-la — uma por linha:

https://app.example.com
https://*.example.org
http://localhost:3000

• Uma origem é https://host mais uma porta opcional, sem caminho.
• Um *. no início permite todos os subdomínios (https://*.example.org), nunca o domínio puro e nunca um sufixo isolado como *.com.
• http simples é aceito apenas para localhost, 127.0.0.1 e [::1].
• Até 20 origens. Qualquer outro site verá a mensagem de erro do navegador (refused to connect).

2. Crie a verificação

Crie a verificação com a API REST e obtenha o token hospedado dela (kvs_…) — veja Sessões. Faça isso no seu servidor: nunca coloque uma chave de API no navegador.

3. Adicione o script e abra-o

<script src="https://app.certivant.com/embed/certivant.js"></script>
<button id="verify">Verify my identity</button>
<script>
  document.getElementById("verify").addEventListener("click", function () {
    var flow = Certivant.open({
      token: "kvs_…", // from your server
      onReady: function () { console.log("loaded"); },
      onStep: function (e) { console.log("step", e.step); },
      onComplete: function (e) { console.log("done", e.status, e.requestId); },
      onCancel: function () { console.log("closed"); },
      onError: function (e) { console.error(e.code, e.message); }
    });
  });
</script>

A origem do script é a origem da Certivant que ele enquadra. Se você usar um domínio personalizado, carregue o script a partir dele ou passe origin: "https://id.yourbrand.com".

Inline

<div id="verification"></div>
<script>
  Certivant.open({
    mode: "inline",
    container: "#verification", // element or selector
    formSlug: "customer-onboarding",
    locale: "fr",
    minHeight: 640
  });
</script>

O frame cresce conforme o conteúdo (eventos resize) e nunca fica menor que minHeight.

Opções

Certivant.open() retorna um handle: close() (informa cancel, a menos que o fluxo já tenha sido concluído), destroy() (silencioso), on(event, fn), off(event, fn), além de iframe e origin.

Eventos

not_ready é disparado quando a página não informou ready após 20 segundos. A causa comum é que a origem do seu site não está em Incorporação, ou que o token já foi usado.

Modelo de segurança

• Quem pode enquadrar uma página. O proxy define Content-Security-Policy: frame-ancestors 'self' <suas origens> (e remove X-Frame-Options) nos seus links hospedados, formulários e páginas do Live ID. Um token desconhecido, um erro ou uma lista vazia deixam essas páginas impossíveis de enquadrar. Páginas do painel e de login nunca podem ser enquadradas.
• Em quem o SDK confia. A URL do frame é construída apenas a partir da origem do próprio SDK, de origin ou de trustedOrigins. Uma mensagem só é aceita se vier da janela desse iframe, da origem exata que foi enquadrada, e for um envelope versionado { "source": "certivant", "version": 1, … }. Todo o resto é ignorado.
• Com quem a página conversa. A página enquadrada envia mensagens apenas para a origem pai que o SDK anunciou (?parentOrigin=), e somente quando essa origem está na sua lista permitida (ou é igual à origem da própria página) e, quando o navegador expõe a informação, corresponde a location.ancestorOrigins. Nunca envia com destino *.
• Nenhum dado pessoal. Os eventos nunca incluem nomes, dados de documentos, pontuações ou imagens.

Câmera, microfone e localização

O SDK define allow="camera; microphone; geolocation; clipboard-write" no iframe, o que delega essas permissões à página incorporada. O Permissions-Policy da própria Certivant as permite para as suas páginas (camera=(self)…), então os dois lados concordam. Seu site precisa ser servido por HTTPS (ou localhost) e não pode enviar um cabeçalho Permissions-Policy que bloqueie camera ou microphone.

Iframe simples

Sem o SDK, você pode usar um iframe comum — permita primeiro a sua origem e adicione o atributo allow:

<iframe
  src="https://app.certivant.com/verify/kvs_…?embed=1&parentOrigin=https%3A%2F%2Fyour-site.example"
  allow="camera; microphone; geolocation; clipboard-write"
  style="width:100%;height:760px;border:0"
></iframe>

Os eventos são enviados ao parentOrigin que você anunciar, se ele estiver permitido; escute com window.addEventListener("message", …) e verifique você mesmo event.origin, event.source e o envelope.

Solução de problemas

Versionamento

O script informa a sua versão em Certivant.version e no cabeçalho de resposta X-Certivant-SDK-Version. O envelope de mensagem traz version: 1; acréscimos dentro da versão 1 são retrocompatíveis, e uma mudança incompatível será publicada como versão 2, mantendo a versão anterior disponível. O carregador fica em cache por alguns minutos.

Para aplicativos nativos, veja WebView móvel.