Skip to content

SDK Overview

The Moveris SDK (v4) is a cross-platform SDK for integrating liveness detection into web and mobile applications. It provides ready-to-use components, hooks, and a type-safe API client so you can add liveness verification with minimal code.

In plain terms

The SDK provides drop-in UI components (camera preview, face guide, capture button) and handles camera access, frame capture, face detection, and API calls for you. Use it when building React web apps or React Native mobile apps. For other platforms, use LivenessClient from @moveris/shared.

SDK vs Raw API

The SDK is the recommended integration path for React and React Native projects. It handles camera access, frame capture, face detection, quality checks, and API communication out of the box. For other platforms or custom integrations, use LivenessClient from @moveris/shared.

Architecture

The SDK is organized as a monorepo with three published packages:

@moveris/shared                       Core business logic (platform-agnostic)
    |
    +-- @moveris/react                React (Web) components & hooks
    |
    +-- @moveris/react-native         React Native components & hooks
  • @moveris/shared is the foundation. It contains the LivenessClient HTTP client, all TypeScript types, constants, validators, retry logic, and feedback messages. Both platform packages depend on it.
  • @moveris/react adds web-specific components (LivenessView, LivenessModal) and hooks (useLiveness, useCamera, useSmartFrameCapture, useModels) built on top of @moveris/shared. It uses the browser MediaStream API and optionally MediaPipe for face detection.
  • @moveris/react-native provides the same component and hook patterns for React Native, using react-native-vision-camera for camera access and ML Kit or Expo Face Detector adapters for face detection.

Packages

Package Version Description
@moveris/shared 4.1.2 Core client, types, constants — Mixed V3.1.1 only (mixed-30-v3_1_1 default), DEFAULT_MODEL, consecutive-sequence capture, 1280×720 downscale
@moveris/react 4.1.3 React web components and hooks — onSequenceReset / restartCapture(), requireLandmarks, platform-aware adaptive blur/brightness. Loads in strict browser bundlers such as Next.js Turbopack
@moveris/react-native 4.1.2 React Native components and hooks aligned with @moveris/shared 4.1.2

API v2 JSON envelope

REST responses use { "data", "success", "message" }. LivenessClient in @moveris/shared unwraps this automatically when you use a current package version. See the Changelog for release notes; if you call the API without the SDK, read the payload from data.

Current models

The SDK compiles against Mixed V3.1.1 only. Default is mixed-30-v3_1_1 (30 frames).

Model ID Frames
mixed-30-v3_1_1 30 (default)
mixed-60-v3_1_1 60
mixed-120-v3_1_1 120

Use getModels() or useModels() for the live registry. See Models overview.

Key Features

  • Drop-in UI components -- LivenessView provides camera preview, face guide overlay, capture controls, and result display in a single component
  • Smart frame capture -- Adaptive quality gates calibrate blur and brightness to each user's environment and platform (iOS, Android, HarmonyOS, desktop); face alignment, blur, and lighting are checked before each frame is accepted
  • Face detection -- Built-in face detection with adapters for MediaPipe (web), ML Kit (Android/iOS), and Expo Face Detector
  • Type-safe API client -- LivenessClient wraps all Moveris API endpoints with full TypeScript types and automatic retry with exponential backoff
  • Multiple capture modes -- Support for batch upload (fast-check), frame streaming (fast-check-stream), pre-cropped faces (fast-check-crops), V3 landmark path (live-check), and upload-first v2 pipeline (v2Upload → v2FastCheck)
  • Feedback system -- Built-in user feedback messages with localization support (English, Spanish)
  • Customizable styles -- All components accept style overrides for full visual customization

Supported API Endpoints

The SDK client supports all Moveris API (v2) endpoints:

Method Endpoint Frames Description
getModels() /api/v1/models -- Fetch available models (id, label, min_frames, deprecated)
fastCheck() /api/v1/fast-check by model Fast liveness check with server-side face detection
fastCheckCrops() /api/v1/fast-check-crops by model Fast check with pre-cropped 224x224 face images
fastCheckStream() /api/v1/fast-check-stream by model Parallel frame streaming for lowest latency
liveCheck() /api/v1/live-check by model V3 batch with client-supplied MediaPipe landmarks
v2Upload() /api/v2/upload chunks Buffer frames during capture (v2 pipeline)
v2FastCheck() /api/v2/fast-check — Inference by session_id after v2 upload
v2LiveCheck() /api/v2/live-check — V3 live-check variant after v2 upload with landmarks
verify() /api/v1/verify 50+ Spatial-feature analysis for standard KYC
hybridCheck() /api/v1/hybrid-check 50+ CNN + physiological hybrid model
hybrid50() /api/v1/hybrid-50 50+ 50-frame hybrid (93.8% accuracy)
hybrid150() /api/v1/hybrid-150 150+ 150-frame hybrid (96.2% accuracy)
health() /health -- Health check

Protocol

The SDK communicates with the Moveris API over HTTPS REST with JSON payloads. Authentication is via the X-API-Key header. All requests include automatic retry with exponential backoff (3 attempts, 1s--10s delays).

Next Steps