Skip to content

SDK Overview

The Moveris SDK (v2) 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 the raw API with code examples.

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, see the Code Examples section which shows direct API usage.

Architecture

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

@moveris/shared                       Core business logic (platform-agnostic)
    |
    +-- @moveris/react                React (Web) components & hooks
    |
    +-- @moveris/react-native         React Native components & hooks
    |
    +-- @moveris/cognito-check        Framework-agnostic embeddable widget
    |
    +-- @moveris/cognito-check-react  React wrapper for embeddable widget
  • @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.
  • @moveris/cognito-check provides a standalone embeddable verification widget as a Web Component (<cognito-check>) for non-React or mixed frontend stacks.
  • @moveris/cognito-check-react wraps the cognito widget with React props (apiKey, onSuccess, onError, style).

Packages

Package Version Description
@moveris/shared 3.10.0 Core client, types, constants, and utilities — includes API v2 envelope handling and inconclusive fallback behavior
@moveris/react 3.10.1 React web components and hooks — PNG capture pipeline and sRGB canvas pinning at 1280×720
@moveris/react-native 3.10.0 React Native components and hooks aligned with the current @moveris/shared client
@moveris/cognito-check 0.3.0 Framework-agnostic embeddable verification checkbox/widget for lightweight integrations
@moveris/cognito-check-react 2.0.0 React bindings for the embeddable cognito-check widget

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.

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 -- Automatic quality gates check face alignment, blur, and lighting before capturing each frame
  • 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), and pre-cropped faces (fast-check-crops)
  • 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
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