HADES React SDK

The HADES React SDK provides a simple React component that integrates with the HADES platform for real-time face authentication, face registration, and anti-spoofing.

Installation

npm install hades-react-sdk

Setup

Create a .env file in your project root.

VITE_HADES_SOCKET=wss://your-socket-url
VITE_HADES_PROJECT_ID=your_project_id
VITE_HADES_PROJECT_SECRET=your_project_secret
VITE_HADES_API_BASE=https://your-api-base

Example configuration:

export const HADE_CONFIG = {
    SOCKET: import.meta.env.VITE_HADES_SOCKET,
    PROJECT_ID: import.meta.env.VITE_HADES_PROJECT_ID,
    PROJECT_SECRET: import.meta.env.VITE_HADES_PROJECT_SECRET,
    API_BASE: import.meta.env.VITE_HADES_API_BASE,
};

Note

The environment variable prefix (VITE_) is required only for Vite projects. For Next.js, CRA, or other frameworks, use the environment variable conventions of your framework.

Creating a HADES Project

Before using the SDK, create a project on the HADES Face Authentication Platform.

After creating a project, you will receive:

• Project ID
• Project Secret

These credentials are required for all SDK sessions.

Basic Usage

import { HADESWrapper } from "hades-react-sdk";

<HADESWrapper
    server={HADE_CONFIG.SOCKET}
    projectId={HADE_CONFIG.PROJECT_ID}
    projectSecret={HADE_CONFIG.PROJECT_SECRET}
    apiBase={HADE_CONFIG.API_BASE}
    sessionMode="INFERENCE"
    externalUserId="anant"
    onReady={() => console.log("Camera ready")}
    onVerdict={(verdict) => console.log(verdict)}
    onRegistered={(data) => console.log(data)}
    onError={(error) => console.error(error)}
    onSessionRenewed={(data) => console.log(data)}
/>

Component Props

Connection Configuration

| Prop | Type | Required | Description | |-------|------|----------|-------------| | server | string | Yes | WebSocket endpoint used for real-time communication. | | projectId | string | Yes | Project ID obtained from the HADES dashboard. | | projectSecret | string | Yes | Project Secret obtained from the HADES dashboard. | | apiBase | string | Yes | Base URL of the HADES REST API. |

Session Configuration

sessionMode

sessionMode="INFERENCE"

Supported values:

INFERENCE
FACE_REGISTRATION

INFERENCE

Starts an inference session.

Depending on the modules enabled for your project, this can perform:

• Face Recognition
• Passive Anti-Spoofing
• Additional inference modules configured for the project

FACE_REGISTRATION

Starts a face registration session.

Use this mode to register a new user's face into the HADES Face Recognition system.

This mode is only available if the Face Recognition module is enabled for your project.

externalUserId

externalUserId="user_123"

Required when using Face Recognition.

The externalUserId is your application's unique identifier for a user.

HADES stores this identifier alongside the registered facial embeddings, allowing future authentication sessions to be mapped back to the corresponding user in your application.

Example:

Your Application
----------------
ID: 42
Username: anant

↓

HADES Face Recognition

externalUserId = "42"

This allows authentication responses to be associated with the correct user without exposing your internal database.

Event Callbacks

The SDK exposes several lifecycle callbacks that allow your application to react to session events.

onReady

Triggered when the SDK has finished initialization.

This indicates that:

• Camera permissions have been granted
• Camera stream is active
• Connection to the HADES backend has been established
• Frames are ready to be transmitted

Example:

onReady={() => {
    console.log("HADES initialized");
    console.log("Camera connected");
    console.log("Streaming started");
}}

onVerdict

Triggered whenever an inference result is received from the server.

Example:

onVerdict={(response) => {
    console.log("Inference Result");

    console.log(response);

    /*
    Example Response

    {
        success: true,
        result: {
            verdict: "REAL",
            confidence: 0.998,
            timestamp: 1722345234
        }
    }
    */
}}

Typical use cases:

• Display authentication results
• Update UI
• Navigate user after successful verification
• Log inference data

onRegistered

Called after a successful face registration.

Example:

onRegistered={(response) => {
    console.log("Face Registration Complete");

    /*
    Example Response

    {
        success: true,
        userId: "42",
        registered: true
    }
    */
}}

Typical use cases:

• Redirect user
• Show registration success
• Store registration metadata

onSessionRenewed

Triggered whenever the SDK automatically renews an authentication session.

Example:

onSessionRenewed={(response) => {
    console.log("Session renewed");

    /*
    Example Response

    {
        success: true,
        sessionId: "...",
        expiresAt: 1722350000
    }
    */
}}

onError

Triggered whenever an SDK or network error occurs.

Example:

onError={(error) => {
    console.error("HADES Error");

    console.error(error);

    /*
    Example

    {
        code: "CAMERA_PERMISSION_DENIED",
        message: "User denied camera access."
    }
    */
}}

Recommended handling:

• Display user-friendly error messages
• Retry failed operations when appropriate
• Log unexpected failures for debugging

Complete Example

import { HADESWrapper } from "hades-react-sdk";
import { HADE_CONFIG } from "./config";

export default function App() {
    return (
        <HADESWrapper
            server={HADE_CONFIG.SOCKET}
            projectId={HADE_CONFIG.PROJECT_ID}
            projectSecret={HADE_CONFIG.PROJECT_SECRET}
            apiBase={HADE_CONFIG.API_BASE}
            sessionMode="INFERENCE"
            externalUserId="anant"

            onReady={() => {
                console.log("SDK Ready");
            }}

            onVerdict={(result) => {
                console.log("Inference Result", result);
            }}

            onRegistered={(data) => {
                console.log("Registration Complete", data);
            }}

            onSessionRenewed={(session) => {
                console.log("Session Renewed", session);
            }}

            onError={(error) => {
                console.error("SDK Error", error);
            }}
        />
    );
}

Notes

• Camera permission is required before a session can begin.
• externalUserId is primarily intended for Face Recognition workflows.
• Keep your Project Secret confidential and never expose production credentials in public repositories.
• The SDK automatically manages camera initialization, WebSocket communication, and session lifecycle.