> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Instalação

> Carregue o LivenessIdentySDK Web via CDN com uma única tag de script

O `LivenessIdentySDK` Web é distribuído **exclusivamente via CDN**. Você adiciona **uma única tag** `<script>` à sua página e o SDK carrega sozinho os demais arquivos do motor IDENTY Face AI (estilos, imagens, worker e `.wasm`).

## Visão geral

> **Integração com uma tag**
>
> Carregue o SDK inteiro com uma única tag `<script>`

> **B2B by design**
>
> A `x-api-key` nunca toca o navegador — vive no seu backend

> **Segurança ligada por padrão**
>
> Liveness em `VERY_HIGH` e detecção de deepfake e câmera virtual ativas

> **Captura criptografada**
>
> A captura é enviada criptografada e analisada no servidor

## Autorize suas origens

O SDK só funciona em páginas autorizadas. **Antes de integrar, envie à equipe da Valid as origens** de onde o SDK vai rodar — sem essa liberação, a captura não funciona na sua página.

* **Origem** = protocolo + domínio + porta, sem caminho: `https://app.suaempresa.com.br`, `http://localhost:3000`.
* Envie as origens de **homologação e de produção** separadamente; cada ambiente é liberado no seu.
* Cada subdomínio é uma origem diferente (`www.` e sem `www.` contam como duas).
* Mudou ou ganhou um domínio? Envie a nova origem antes de publicar.

A `x-api-key` usada pelo seu backend para criar as sessões é gerada por você na Plataforma ID — veja [Chaves de API](https://docs-platform.services-valid.com.br/plataforma/chaves-de-api.md).

## Requisitos

| Requisito | Descrição |
| - | - |
| **HTTPS** | Obrigatório para acessar a câmera. `localhost` é permitido para desenvolvimento. |
| **Câmera** | Câmera acessível pelo navegador. |
| **Navegadores** | Chrome, Edge, Safari e Firefox atuais; Android 7 ou superior; iOS 13 ou superior (Safari). |
| **Iframe** | Se o SDK roda dentro de um iframe, ele precisa de `allow="camera"`. |
| **CSP** | Se a sua página usa Content Security Policy, libere os hosts listados em [Solução de problemas](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/troubleshooting.md#csp-e-hosts-de-rede). |
| **Backend próprio** | Endpoint server-side que chama [`POST /api/v1/sessions`](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/servico) com `x-api-key`. |
| **Origem autorizada** | Veja [Autorize suas origens](#autorize-suas-origens). |

## Instalação via CDN

Não há pacote npm — o SDK é carregado diretamente do CDN.

```html Produção — recomendado (sempre a mais recente) theme={"theme":"catppuccin-latte"}
<script src="https://cdn.hub-liveness-service.app/identy/v7/latest/prd/identy-sdk.js"></script>
```

```html Produção — versão fixa theme={"theme":"catppuccin-latte"}
<script src="https://cdn.hub-liveness-service.app/identy/v7/v1.0.0/prd/identy-sdk.js"></script>
```

| Variante | Atualização | Quando usar |
| - | - | - |
| `latest` | Recebe cada nova versão em até 5 minutos | **Recomendado.** Recebe atualizações automaticamente, sem trabalho manual de atualizar a versão |
| Versão fixa (`v{versão}`) | Nunca muda de comportamento | Se você quiser controle explícito de quando atualizar |

Para descobrir a versão publicada no momento:

```bash theme={"theme":"catppuccin-latte"}
curl https://cdn.hub-liveness-service.app/identy/v7/latest/manifest.json
```

> [!TIP]
>
> Inclua o script **cedo** na página, antes do clique do usuário. Assim que o script carrega, o SDK já começa a se preparar — a câmera abre mais rápido quando o usuário iniciar a verificação.

## Verificando o carregamento

Depois do carregamento, o objeto `LivenessIdentySDK` está disponível globalmente:

```javascript theme={"theme":"catppuccin-latte"}
if (typeof window.LivenessIdentySDK !== 'undefined') {
  console.log('LivenessIdentySDK carregado', window.LivenessIdentySDK.SDK_VERSION);
} else {
  console.error('Falha ao carregar o SDK');
}
```

## Estrutura HTML mínima

```html theme={"theme":"catppuccin-latte"}
<!doctype html>
<html>
  <head>
    <script src="https://cdn.hub-liveness-service.app/identy/v7/latest/prd/identy-sdk.js"></script>
  </head>
  <body>
    <!-- Nenhum elemento de montagem é necessário: a tela de captura é aberta pelo SDK -->
  </body>
</html>
```

## Backend obrigatório

O SDK **não embarca a `x-api-key`**. Você precisa expor um endpoint no seu backend que chame `POST /api/v1/sessions` e devolva apenas `sessionId` e `sessionToken` à página.

> [!WARNING]
>
> **Nunca exponha a `x-api-key` no navegador.** Mesmo ofuscada, qualquer chave embarcada no bundle JS pode ser extraída por DevTools. Veja [Serviço](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/servico.md) para o fluxo recomendado.

Exemplo mínimo (Node.js / Express):

```javascript theme={"theme":"catppuccin-latte"}
import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.use(express.json());

app.post('/api/create-session', async (req, res) => {
  const { ssid } = req.body;

  const r = await fetch('https://api.valid.com/vendor-identy/api/v1/sessions', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.PLATFORM_ID_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      clientRequestId: crypto.randomUUID(),
      ssid,
      platform: 'WEB',
    }),
  });

  if (!r.ok) return res.status(r.status).json(await r.json());

  const session = await r.json();
  // deviceScore / deviceSignals ficam no backend
  res.json({
    sessionId: session.sessionId,
    sessionToken: session.sessionToken,
  });
});

app.listen(8080);
```

## Próximos passos

> **[Implementação](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/implementacao.md)**
>
> Inicie uma verificação de liveness com `run()`

> **[Customização](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/customizacao.md)**
>
> Idioma, segurança, captura e visual da tela

> **[Solução de problemas](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/sdk/web/troubleshooting.md)**
>
> Mapeamento de erros, CSP e diagnóstico

> **[Serviço](https://docs-platform.services-valid.com.br/plataforma/liveness/identy/servico.md)**
>
> Criação da sessão no seu backend


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.