> ## 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 LivenessFacetecSDK Web v10 via CDN com uma única tag de script

O `LivenessFacetecSDK` Web é distribuído **exclusivamente via CDN**. Você adiciona **uma única tag** `<script>` à sua aplicação e o SDK carrega automaticamente o motor FaceTec — não é preciso adicionar uma segunda tag para o FaceTec.

## Visão geral

<CardGroup cols={2}>
  <Card title="Integração com uma tag" icon="code" iconType="regular">
    Carregue o SDK inteiro com uma única tag `<script>`
  </Card>

  <Card title="B2B by design" icon="shield-check" iconType="regular">
    A `x-api-key` nunca toca o navegador — vive no seu backend
  </Card>

  <Card title="Sem ponto de montagem" icon="expand" iconType="regular">
    A captura abre como camada full-screen sobre a página
  </Card>

  <Card title="Customização completa" icon="palette" iconType="regular">
    Locales pt-BR/en-US e temas que espelham a API do FaceTec
  </Card>
</CardGroup>

## Requisitos

| Requisito              | Descrição                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **HTTPS**              | Obrigatório em produção. A API `getUserMedia` exige contexto seguro. `localhost` é permitido para desenvolvimento.      |
| **Câmera**             | Câmera acessível pelo navegador.                                                                                        |
| **Backend próprio**    | Endpoint server-side que chama [`POST /api/v2/sessions`](/plataforma/liveness/facetec/v10/servico) com `x-api-key`.     |
| **Domínio autorizado** | Envie à equipe da Valid os domínios (produção e homologação) que vão carregar o SDK, para liberação na licença FaceTec. |

<Warning>
  Sem a liberação do domínio na licença FaceTec, a inicialização do SDK falha (veja [`INITIALIZATION_FAILED`](/plataforma/liveness/facetec/v10/sdk/web/troubleshooting)). Envie os domínios à equipe da Valid antes de testar em produção.
</Warning>

## Instalação via CDN

Não há pacote npm público — 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/facetec/v10/latest/prd/facetec-sdk.js"></script>
```

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

| Variante                  | Cache            | Quando usar                                                                                     |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `latest`                  | 5 minutos        | **Recomendado.** Recebe atualizações automaticamente, sem trabalho manual de atualizar a versão |
| Versão fixa (`v{versão}`) | 1 ano (imutável) | 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/facetec/v10/latest/manifest.json
# { "version": "2.0.0", "updated": "..." }
```

## Verificando o carregamento

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

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

<Info>
  Assim que o script termina de carregar, o SDK já dispara sozinho o [preload](/plataforma/liveness/facetec/v10/sdk/web/implementacao#preload) do motor FaceTec — você não precisa chamar nada manualmente para isso.
</Info>

## Estrutura HTML mínima

```html theme={"theme":"catppuccin-latte"}
<!doctype html>
<html>
  <head>
    <script src="https://cdn.hub-liveness-service.app/facetec/v10/latest/prd/facetec-sdk.js"></script>
  </head>
  <body>
    <!-- Nenhum elemento de montagem é necessário: a captura abre como camada full-screen -->
  </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/v2/sessions` e devolva apenas `sessionId`/`sessionToken` ao cliente.

<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](/plataforma/liveness/facetec/v10/servico) para o fluxo recomendado.
</Warning>

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/facetec-vendor/api/v2/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();
  res.json({
    sessionId: session.sessionId,
    sessionToken: session.sessionToken,
  });
});

app.listen(8080);
```

## Próximos passos

<CardGroup cols={2}>
  <Card title="Implementação" icon="code" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/implementacao">
    Inicialize o SDK e dispare uma verificação de liveness
  </Card>

  <Card title="Customização" icon="palette" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/customizacao">
    Personalize cores, textos, fontes e idioma da UI
  </Card>

  <Card title="Solução de problemas" icon="wrench" iconType="regular" href="/plataforma/liveness/facetec/v10/sdk/web/troubleshooting">
    Mapeamento de erros, causas e diagnóstico
  </Card>

  <Card title="Serviço" icon="server" iconType="regular" href="/plataforma/liveness/facetec/v10/servico">
    Contrato HTTP do backend que emite o token de sessão
  </Card>
</CardGroup>