Captura web

Conduza a pessoa pela captura em um navegador, usando o token e o link retornados pelo Human Plugin.

Markdown

Seu back-end cria o processo no Human Plugin com um fluxo Journey. A resposta 201 traz três valores de que o front-end precisa:

Campo	Usado para
id	O id do processo no Human Plugin. O SDK o recebe como transactionId, e seu back-end lê o resultado com ele
token	Inicia a captura no Journeys SDK
link	A página de captura hospedada

token e link são retornados somente pelo create. Repasse-os ao front-end na mesma requisição ou armazene-os por conta própria. Veja Human Token Journey.

Requisitos

A captura roda no navegador e precisa de acesso à câmera.

SO	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• As páginas devem ser servidas via HTTPS. A câmera só funciona em um contexto seguro.
• A navegação dentro de apps exige Android 8 (API 26) ou iOS 13 ou superior.
• Navegadores embutidos em aplicativos de redes sociais não são suportados.

Escolha um modelo

Modelo	Ideal para
Link hospedado	A configuração mais simples. Sem biblioteca: a pessoa acessa o link e volta para o seu callbackUri
Journeys SDK	A captura abre dentro da sua página, então a pessoa nunca sai dela

Link hospedado

Envie callbackUri na requisição de create. É a página para a qual a pessoa volta quando a captura termina.

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

Em seguida, envie a pessoa para o link, de duas formas:

• Redirecionamento. Navegue até o link. Ao final, a pessoa é enviada de volta para o callbackUri.
• Nova aba. Abra o link com window.open(), observe quando a aba chegar ao callbackUri e feche-a.

Quando a pessoa voltar, avise seu back-end, que chama GET /v1/processes/{id}.

Journeys SDK

O SDK abre a captura em um iFrame na sua página. Funciona com qualquer framework (React, Angular, Vue) ou com JavaScript puro.

Antes de começar, peça ao suporte da Unico para cadastrar seus domínios. Eles devem usar HTTPS.

1. Instale

npm install unico-journey-sdk

O SDK segue o versionamento semântico, então atualizações minor e patch são seguras. Mantenha-o atualizado: correções de segurança e de bugs são publicadas em novas versões.

2. Libere o SDK nos seus headers

Pule esta etapa se sua página não envia o header Content-Security-Policy nem Permissions-Policy. Caso contrário, adicione:

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io"),
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io")

3. Inicialize

Chame init assim que souber que a captura será necessária. Ele pré-carrega a captura.

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. Abra a captura

Parâmetro	Obrigatório	Valor
transactionId	Sim	O id do Human Plugin
token	Sim	O token retornado pelo create
onFinish	Sim	Chamado quando a captura termina ou a pessoa a fecha
onWidgetVisibilityChange	Não	Chamado quando a captura é exibida ou ocultada

ByUnicoSDK.open({
  transactionId: id, // the Human Plugin id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // The capture ended. Ask your back-end to read the outcome.
    }
    // type === 'CLOSE': the person closed it before the end.
  },
  // Optional: hide your own overlays while the capture is visible.
  onWidgetVisibilityChange: (visible) => {},
});

// To close it yourself:
ByUnicoSDK.close();

onFinish recebe:

Campo	Descrição
type	'FINISH' quando a captura terminou, 'CLOSE' quando a pessoa a fechou antes
transaction.redirectUrl	Para onde enviar a pessoa em seguida. Presente apenas em 'FINISH'

aviso

onFinish informa que a captura terminou, não como terminou. O resultado vem somente de GET /v1/processes/{id} no seu back-end.

Use onFinish também para levar a pessoa à próxima tela e para evitar criar um novo processo imediatamente caso ela comece de novo.

Solução de problemas

• O fluxo quebra ou se comporta de forma estranha. Garanta que nenhum script seu altere o iFrame do SDK no DOM.
• A captura aparece diferente. Regras de CSS amplas, como seletores de tag, podem atingir o iFrame. Os ids e classes do próprio SDK começam com unico.
• Erros inesperados após uma atualização. Instale o SDK apenas por npm ou yarn e nunca edite os arquivos dele.

Testes

Feche o DevTools do navegador antes de testar uma captura de ponta a ponta. Um DevTools aberto bloqueia o envio.

Configurações não suportadas

• O SDK dentro de uma WebView mobile. Em um app, abra o link. Veja os guias de Android, iOS, Ionic, React Native e Flutter.
• Seu próprio <iframe> apontando para a captura. Use o SDK, que gerencia o iFrame.