A liveness detection SDK is only useful when it survives the parts of integration that happen outside the model: camera permissions, poor lighting, interrupted sessions, assistive technology, retries and a release process that can explain every decision. This guide gives web and mobile engineering teams a practical path from platform choice to production monitoring.
What Does a Liveness Detection SDK Actually Do?
A liveness detection SDK analyzes camera input to determine whether a live person is present, rather than accepting a photo, replayed video, mask, or other presentation attack. It produces a liveness result. It does not, by itself, prove that the person is a particular named identity. Identity matching is a separate control.
That distinction should shape both the user experience and the backend contract. A liveness result answers, “Is a live person present in this capture?” A face comparison result answers, “Does this capture match a reference identity?” A uniqueness check asks whether the same person has already been associated with another account. Those signals can work together, but they are not interchangeable.
In a typical flow, the SDK handles camera capture, frame quality, face presence, and the liveness assessment. Your application owns the surrounding decisions: when to start, what consent to show, what to do when permission is denied, how to bind the session to a transaction and whether a failed attempt should be retried, reviewed or stopped.
Realeyes documentation separates cloud APIs and Web SDKs from the Native SDK. Review the VerifEye Cloud APIs and Web SDKs documentation for the web integration surface, and the VerifEye Native SDK overview for native platform capabilities.
Should You Use a Web or Native Mobile SDK?
Choose a web SDK when the verification journey must run in a browser with minimal installation and broad device reach. Choose a native mobile SDK when your app needs tighter camera control, predictable lifecycle handling, offline-capable processing, or deeper integration with iOS and Android permission and capture APIs. Many enterprise products support both, but they should not share one assumption set.
| Decision area | Web SDK | Native mobile SDK |
|---|---|---|
| Capture surface | Browser camera stream and browser permission UI | App-managed camera session and OS permission UI |
| Primary constraints | HTTPS, browser support, iframe policy, device permissions | App lifecycle, OS versions, camera session state, package size |
| Best fit | Web onboarding, account recovery, embedded verification | High-volume app journeys that need native control |
| Failure handling | Browser errors, blocked permissions, tab suspension | Denied permissions, backgrounding, interruptions, thermal limits |
| Release surface | Web deployment and SDK version pinning | App release train, store review, SDK and model compatibility |
Start with the customer journey, not the SDK catalog. If a user can complete the journey in a browser, a web flow may reduce installation friction. If the product already lives in a native app, a native integration usually gives the team better control over camera state and accessibility behavior. A shared backend contract can keep both channels consistent while the capture layers remain platform-specific.
Do not treat “mobile” as one platform. A mobile browser has browser permissions and browser lifecycle behavior. An iOS or Android app has OS-level permissions, app lifecycle events, camera session configuration, and a separate release process. Test all three where the product supports them.
How Should Camera Permissions Be Implemented?
Request camera access at the moment the user starts a verification step, after explaining what the camera is needed for. The application should detect permission state, handle denial without trapping the user, and release the camera as soon as the capture ends. Permission management is part of the trust experience, not a setup detail to hide.
Web permissions
If you are building a custom capture layer against the Cloud APIs, web camera access uses navigator.mediaDevices.getUserMedia(). MDN documents that it requires a secure context, normally HTTPS, and explicit user permission, and it documents failure states such as NotAllowedError and NotFoundError. Use those states to show a useful next action rather than a generic “verification failed” message.
If you are using the VerifEye Web SDK instead, the VerifyVerifier component requests camera access and shows its own consent screen before capture, so you do not call getUserMedia() yourself for the standard flow. The consentSkipMode prop controls whether that screen appears, and onServiceError reports backend-side failures during the flow. The one case where the SDK expects you to hold a stream yourself is a headless integration that reruns verification on a short interval — acquire one stream and pass it in as mediaStream so the SDK does not reopen the camera on every check:
// Acquire once, reuse across repeated headless checks
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
<VerifyVerifier
headless
sessionId={session.sessionId}
accessToken={session.accessToken}
region="eu"
mediaStream={stream}
onVerificationCompleted={() => onCompleted(session.sessionId)}
/>
// Stop the tracks yourself once you're done running checks
stream.getTracks().forEach(track => track.stop());Either way, if the flow is embedded in an iframe, check the relevant Permissions Policy configuration. The top-level page must explicitly allow camera access to the embedded origin. Also stop every media track when the session ends. A camera indicator that remains active after a user has left the flow is a small defect with an outsized trust cost.
iOS permissions
Apple requires an app-specific camera usage message in Info.plist and permission before capture. Apple’s camera authorization guidance also recommends checking authorizationStatus(for:) and requesting access only when the feature needs it. Keep the explanation specific, such as “Allow camera access to check that a live person is completing this verification,” rather than relying on a vague label.
Android permissions
Android camera access is a runtime permission. Android’s permission guidance recommends evaluating whether the permission is necessary, explaining why it is needed when appropriate, and handling the user’s response through the platform permission contract. Account for one-time permission choices and for users who previously denied access. A settings deep link can help, but it should not be the only recovery path.
Across platforms, capture should be a small state machine: idle, permission_pending, ready, capturing, processing, passed, failed_retryable and failed_terminal. Explicit states make analytics, accessibility announcements, and QA much easier than a chain of callbacks with a single success flag.
How Do Passive and Active Flows Change the Integration?
Passive liveness evaluates natural camera input with little or no prompted movement. Active liveness asks the user to complete a challenge, such as turning their head. The choice changes capture duration, user guidance, accessibility requirements and the fallback plan. It should follow the risk model and journey context, not a preference for fewer screens.
For a passive flow, the integration should prioritize framing guidance, lighting feedback, stable capture and a clear processing state. Avoid adding unnecessary motion prompts to a flow designed to be passive. For an active flow, the SDK or application must communicate one instruction at a time, confirm progress, and allow a user to recover from a missed instruction without restarting the entire journey.
- Passive flow: Use when a short, low-friction check fits the risk decision and the capture conditions are controlled.
- Active flow: Use when a prompted interaction is appropriate to the assurance requirement and the user can complete it comfortably.
- Risk escalation: Use a stronger or additional control when the signal is inconclusive, the transaction is high risk, or the environment is outside policy.
- Fallback: Define a separate route for permission denial, unsupported devices, repeated quality failures, and users who cannot complete the selected interaction.
Do not use a liveness pass as a substitute for identity matching. In an onboarding flow, the product may need liveness plus face comparison, document verification, or account-level uniqueness. In account recovery, liveness may be paired with a previously verified credential. The right combination depends on the decision being made.
What Should You Test for Presentation Attacks?
Presentation-attack testing checks whether a biometric capture system resists an artifact or human characteristic presented to interfere with the system’s policy. NIST’s FATE PAD program describes examples such as printed photos, replay attacks and other presentation attack instruments. Build a test matrix around those attack classes, not only around a clean selfie on a modern phone.
| Test family | Examples to include | Record |
|---|---|---|
| Replay | Phone or tablet displaying a face video, different brightness levels, cropped playback | Device, display, distance, result, latency |
| Print and cutout | Printed face, cutout mask, glossy and matte paper | Material, lighting, angle, result |
| Digital manipulation | Screen replay, synthetic face video, virtual camera where permitted by policy | Source, transport path, result |
| Capture quality | Low light, glare, motion blur, partial face, multiple faces | Quality code, user guidance, retry outcome |
| Operational abuse | Rapid retries, session reuse, token reuse, parallel sessions | Rate limits, correlation ID, server decision |
Separate model behavior from integration behavior. A failure caused by a camera stream that never starts is not the same as a liveness rejection. Your test harness should preserve the SDK result, capture quality, permission state, device context, and backend decision separately. Otherwise the team will spend a week tuning the wrong layer, which is a very technical way to lose a week.
Use the NIST FATE PAD reference to keep presentation-attack terminology consistent. Do not publish a vendor accuracy percentage unless it comes from a current, attributable evaluation with a defined test set and operating conditions.
How Can the Flow Be Accessible and Resilient?
An accessible liveness integration gives users understandable instructions, visible status, keyboard and assistive-technology support around the flow, and a meaningful alternative when camera capture is not possible. It does not assume that every user can perform a timed head movement, hold a phone at a particular angle, or see a small face guide.
Apply the relevant WCAG 2.2 success criteria to the surrounding experience. W3C guidance includes target-size, error-identification, focus and accessible-authentication considerations. The biometric component still needs product-specific testing, but the host page must not make the component harder to use than it needs to be.
- Give camera instructions in text, not only through color, animation, or audio.
- Announce state changes such as permission needed, face not found, processing, retry available, and completed.
- Keep controls large enough to operate and make focus visible when the flow includes buttons or links.
- Do not make a time-limited motion challenge the only possible route for a user with a mobility, vision, hearing, or speech limitation.
- Offer a documented fallback that meets the same risk policy, such as manual review or another approved verification method.
- Explain why a retry is needed and what the user should change, such as lighting or distance.
Resilience also means recovering from ordinary device events. Test browser tab suspension, orientation changes, app backgrounding, incoming calls, camera contention, thermal throttling, network loss and a user closing the flow midway. Persist only the state needed to resume safely. Never assume that a camera stream or verification token will remain valid after the app lifecycle changes.
Which Telemetry and Backend Controls Matter?
Telemetry should explain the verification funnel without collecting more biometric data than the service requires. Log event names, timestamps, correlation IDs, SDK version, platform, app or web version, permission outcome, quality outcome, retry count, latency and final decision. Avoid raw frames, screenshots, or face templates unless a documented product and legal requirement explicitly authorizes them.
| Layer | Useful signal | Operational question |
|---|---|---|
| Capture | Permission, camera start, frame quality, face presence | Can the user reach a usable capture? |
| SDK | SDK version, model version, result code, processing time | Did a release change behavior or latency? |
| Session | Session age, retries, cancellation, replayed token | Is the flow being abused or abandoned? |
| Decision | Liveness result, companion signals, policy outcome | Was the decision pass, reject, review, or retry? |
| Business | Completion, escalation, support contact, downstream fraud signal | Does the control improve the intended journey? |
Keep the client responsible for presentation and the server responsible for trust boundaries. API keys, signing secrets, final policy thresholds and high-value decision rules should not live in browser code. Bind the verification session to a transaction, user journey, or recovery attempt, then validate the result server-side before granting access or creating an account.
Use the VerifEye API documentation to confirm the current authentication, regional endpoint, and response contract before implementation. Pin SDK versions, record them in telemetry and make a contract test fail when a response field or terminal state changes unexpectedly.
What Belongs in Release Governance?
A liveness SDK release should be treated as a security-sensitive change, even when the application code change looks small. Require a versioned test matrix, privacy review, accessibility review, failure-mode review, and staged rollout. A green unit-test suite cannot tell you whether a camera permission prompt is comprehensible on a real device.
- Pin and review: Record the SDK and model versions, release notes, supported platforms, and any changed result codes.
- Run representative captures: Test real devices, browsers, OS versions, lighting conditions, camera quality, and the presentation-attack matrix.
- Exercise failure paths: Deny permission, revoke permission, interrupt capture, disconnect the network, repeat a session and submit an incomplete result.
- Check user impact: Review instructions, focus order, screen-reader output, motion requirements, retry language, and approved alternatives.
- Stage the rollout: Use a controlled percentage or cohort, monitor completion and rejection changes and keep rollback artifacts ready.
- Reconcile outcomes: Compare client events with server decisions and downstream fraud or support signals before widening the release.
For teams evaluating a production deployment, the Realeyes VerifEye liveness solution describes a privacy-focused approach to liveness. The VerifEye Recover application shows how human verification can fit an account-recovery journey. Use those pages alongside the developer documentation to separate product fit from implementation detail.
Frequently Asked Questions
What is a liveness detection SDK?
A liveness detection SDK is a set of software components that uses camera input to assess whether a live person is present. It can manage capture and liveness analysis, while the application remains responsible for consent, session binding, identity matching, policy decisions and fallback handling.
Is liveness detection the same as face recognition?
No. Liveness detection checks for a live person and resistance to presentation attacks. Face recognition or face comparison checks whether a captured face matches a reference identity. A product can use both signals, but a liveness pass does not identify the person by itself.
Should liveness run in the browser or in a mobile app?
Use a web SDK for browser-based journeys and broad reach. Use a native mobile SDK when the product needs app-level camera control, lifecycle handling, or native release governance. The decision should follow the journey, risk model, support matrix, and privacy requirements.
What happens if a user denies camera permission?
Show a clear explanation and provide an approved alternative or a path to retry after changing permissions. Record the permission outcome separately from the liveness result. Do not label a permission denial as proof that the user failed liveness.
How should teams test liveness integrations?
Test normal captures, low-quality conditions, interrupted sessions, permission states, device and browser combinations and presentation attacks such as printed photos and replayed videos. Preserve both the SDK result and the integration state so the team can identify the failing layer.
Does a liveness detection SDK store camera images?
Storage depends on the product architecture and configuration, so verify it in the provider’s current documentation and contract. The integration should minimize collection, avoid logging raw frames by default, document retention and make any captured data flow explicit to users and reviewers.