NeoFace ID SDK Web

SDK para captura e reconhecimento facial em aplicações web.

Instalação

npm install @neofaceid/web-sdk

Uso Básico

import { start } from '@neofaceid/web-sdk';

// Inicialize o SDK com seu token de aplicação
start('seu-token-de-aplicacao', {
  onSuccess: (user) => {
    console.log('Usuário autenticado:', user);
    // user contém: { name, email, documentId }
  },
  onError: (code, message) => {
    console.error('Erro:', code, message);
  }
});

Versão

O SDK segue o padrão de versionamento semântico (SemVer):

import { VERSION, RELEASE_DATE } from '@neofaceid/web-sdk';

console.log(`Usando NeoFace ID SDK versão ${VERSION} (lançada em ${RELEASE_DATE})`);

Histórico de Versões

| Versão | Data | Mudanças | |--------|------|----------| | 1.0.0 | 2023-06-15 | Lançamento inicial do SDK |

Parâmetros

applicationToken (string)

Token de autenticação da sua aplicação. Obtenha este token no painel de administração do NeoFace ID.

callbacks (object)

onSuccess (function)

Chamado quando o reconhecimento facial é bem-sucedido.

• Parâmetros: user (object) - Contém name, email e documentId do usuário reconhecido.

onError (function)

Chamado quando ocorre um erro durante o processo.

• Parâmetros:
  • code (string) - Código do erro
  • message (string) - Mensagem descritiva do erro

Códigos de Erro

| Código | Descrição | |--------|-----------| | TOKEN_VALIDATION_ERROR | Token de aplicação inválido ou expirado | | NO_CAMERA | Câmera não disponível ou permissão negada | | FACE_NOT_DETECTED | Nenhum rosto detectado na imagem | | MULTIPLE_FACES | Múltiplos rostos detectados na imagem | | FACE_NOT_CENTERED | Rosto não está centralizado no frame | | LIVENESS_CHECK_FAILED | Verificação de vivacidade falhou | | RECOGNITION_FAILED | Falha no reconhecimento facial | | NETWORK_ERROR | Erro de conexão com o servidor | | TIMEOUT | Tempo limite excedido durante o processo |

Customização

O modal de captura facial pode ser customizado através de CSS. Adicione as seguintes classes ao seu CSS:

/* Container principal */
#neoface-modal-container {
  /* Estilos para o container */
}

/* Modal */
#neoface-modal-container .modal {
  /* Estilos para o modal */
}

/* Botões */
#neoface-modal-container .button {
  /* Estilos para os botões */
}

/* Mensagens */
#neoface-modal-container .message {
  /* Estilos para as mensagens */
}

/* Guia de posicionamento */
#neoface-modal-container .guide {
  /* Estilos para o guia de posicionamento */
}

Requisitos de Segurança

HTTPS

O SDK requer uma conexão HTTPS para funcionar. Em ambiente de desenvolvimento, você pode usar localhost.

Permissões

O SDK solicita permissão para acessar a câmera do dispositivo. Esta permissão é essencial para o funcionamento do reconhecimento facial.

HSTS

Recomendamos configurar HTTP Strict Transport Security (HSTS) no servidor para garantir que todas as conexões sejam feitas via HTTPS.

Privacidade

O SDK não armazena dados biométricos localmente. Todas as imagens são processadas em tempo real e descartadas após o reconhecimento.

Notas de Performance

• Resolução Adaptativa: O SDK ajusta automaticamente a resolução da câmera com base nas capacidades do dispositivo.
• Compressão JPEG: As imagens são comprimidas antes do envio para otimizar o uso de banda.
• Timeout: O processo de reconhecimento tem um timeout de 10 segundos para evitar que o usuário fique aguardando indefinidamente.

Compatibilidade

Navegadores Suportados

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

Responsividade

O SDK é totalmente responsivo e funciona em dispositivos desktop e mobile. Em dispositivos móveis, o modal ocupa a tela inteira para uma melhor experiência do usuário.

Integração com .NET Framework

O NeoFace ID SDK Web pode ser facilmente integrado em aplicações web desenvolvidas com .NET Framework 4.8 ou superior. Siga os passos abaixo para implementar a autenticação facial em seu projeto ASP.NET:

1. Instalação via NuGet

Adicione o pacote ao seu projeto .NET:

Install-Package NeoFaceId.WebSdk

Ou adicione a referência ao seu arquivo .csproj:

<PackageReference Include="NeoFaceId.WebSdk" Version="1.0.2" />

2. Configuração no Web.config

Adicione a configuração do token no seu arquivo Web.config:

<configuration>
  <appSettings>
    <add key="NeoFaceId:ApplicationToken" value="seu-token-de-aplicacao" />
  </appSettings>
</configuration>

3. Implementação no Código

No Controller (C#)

using System.Web.Mvc;
using NeoFaceId.WebSdk;

public class AuthenticationController : Controller
{
    private readonly string _applicationToken;

    public AuthenticationController()
    {
        _applicationToken = System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"];
    }

    public ActionResult Index()
    {
        return View();
    }

    [HttpPost]
    public JsonResult AuthenticateUser(string name, string email, string documentId)
    {
        // Processar a autenticação do usuário
        // Este método é chamado após o reconhecimento facial bem-sucedido
        
        // Exemplo: Criar sessão do usuário
        Session["UserName"] = name;
        Session["UserEmail"] = email;
        Session["UserDocumentId"] = documentId;
        
        return Json(new { success = true });
    }
}

Na View (Razor)

@{
    ViewBag.Title = "Autenticação Facial";
}

<div class="container">
    <h2>Autenticação Facial</h2>
    
    <button id="startFaceAuth" class="btn btn-primary">Iniciar Autenticação Facial</button>
    
    <div id="authResult"></div>
</div>

@section Scripts {
    <script src="~/Scripts/neoface-id-sdk.js"></script>
    <script>
        document.getElementById('startFaceAuth').addEventListener('click', function() {
            // Inicializar o SDK com o token da aplicação
            NeoFaceId.start('@System.Configuration.ConfigurationManager.AppSettings["NeoFaceId:ApplicationToken"]', {
                onSuccess: function(user) {
                    // Enviar dados do usuário para o servidor
                    $.ajax({
                        url: '@Url.Action("AuthenticateUser", "Authentication")',
                        type: 'POST',
                        data: {
                            name: user.name,
                            email: user.email,
                            documentId: user.documentId
                        },
                        success: function(response) {
                            if (response.success) {
                                document.getElementById('authResult').innerHTML = 
                                    '<div class="alert alert-success">Autenticação bem-sucedida!</div>';
                                // Redirecionar para a página principal após autenticação
                                setTimeout(function() {
                                    window.location.href = '@Url.Action("Index", "Home")';
                                }, 1500);
                            }
                        },
                        error: function() {
                            document.getElementById('authResult').innerHTML = 
                                '<div class="alert alert-danger">Erro ao processar autenticação no servidor.</div>';
                        }
                    });
                },
                onError: function(code, message) {
                    document.getElementById('authResult').innerHTML = 
                        '<div class="alert alert-danger">Erro: ' + message + '</div>';
                }
            });
        });
    </script>
}

4. Personalização do Modal

Para personalizar a aparência do modal de captura facial, adicione os estilos CSS ao seu arquivo Site.css ou ao layout principal:

/* Estilos para o modal de captura facial */
#neoface-modal-container .modal {
    border-radius: 8px;
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

#neoface-modal-container .button {
    background-color: #007bff;
    color: white;
    border: none;
    padding: 8px 16px;
    border-radius: 4px;
    cursor: pointer;
}

#neoface-modal-container .button:hover {
    background-color: #0069d9;
}

5. Considerações de Segurança

• Sempre valide os dados recebidos do cliente no servidor
• Utilize HTTPS para todas as comunicações
• Armazene o token de aplicação de forma segura (nunca no código-fonte)
• Considere implementar rate limiting para evitar abusos
• Implemente logs de auditoria para rastrear tentativas de autenticação

Deploy Automático

O SDK é publicado automaticamente no NPM quando há push na branch master. O workflow:

1. Valida que está rodando na branch master
2. Verifica se a versão atual já existe no NPM (idempotente)
3. Determina o tipo de bump (patch/minor) baseado no commit message
4. Incrementa a versão em todos os arquivos (package.json, package-lock.json, src/version.ts)
5. Commita e faz push das mudanças com retry logic
6. Builda o pacote
7. Publica no NPM com retry automático em caso de falhas temporárias

Convenções de Commit

• feat: ou feature: → bump minor (1.0.0 → 1.1.0)
• fix: ou patch: → bump patch (1.0.0 → 1.0.1)
• Outros commits → bump patch por padrão

Idempotência

O workflow é idempotente: se a versão já existe no NPM, o deploy é pulado automaticamente sem erro.

Retry Logic

• Git sync: 3 tentativas com backoff exponencial
• NPM publish: 3 tentativas com backoff exponencial
• Erro 409: Verifica se versão existe antes de falhar

Licença

MIT