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 six published packages:

@moveris/shared                       Core business logic (platform-agnostic)
    |
    +-- @moveris/react                React (Web) components & hooks
    |
    +-- @moveris/react-native         React Native components & hooks
    |
    +-- @moveris/webrtc               WebRTC transport (KVS DataChannel)
    |
    +-- @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, useWebRTCLiveness, 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/webrtc provides WebRTCLivenessClient for observer-based WebRTC transport—single peer connection + DataChannel instead of per-batch REST uploads. Used by useWebRTCLiveness in @moveris/react.
  • @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.22.3 Core client, types, constants — Mixed V3.1.1 models, platform-aware adaptive thresholds (detectPlatform, PLATFORM_BLUR_PARAMS), CameraStabilizer cold-start retry, v2 upload-first methods, liveCheck(), realScore on LivenessResult
@moveris/react 3.22.4 React web components and hooks — requireLandmarks for live-check capture, platform-aware adaptive blur/brightness, useWebRTCLiveness, useLivenessV2, fast-png encoder
@moveris/react-native 3.22.3 React Native components and hooks aligned with @moveris/shared 3.22.3
@moveris/webrtc 3.22.3 WebRTC transport — WebRTCLivenessClient for KVS DataChannel liveness; appends model on observer config; optional deviceIntelligence on start
@moveris/cognito-check 0.3.1 Framework-agnostic embeddable verification checkbox/widget — now includes Mixed V3 and V3.1 model entries
@moveris/cognito-check-react 2.0.1 React bindings for the embeddable cognito-check widget — Mixed V3 and V3.1 model entries

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 -- 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), upload-first v2 pipeline (v2Upload → v2FastCheck), and WebRTC observer transport (WebRTCLivenessClient / useWebRTCLiveness)
  • 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