> ## Documentation Index
> Fetch the complete documentation index at: https://docs.deepidv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Face liveness

> Run deepidv's native face liveness check in an iOS app: as a workflow step, with CustomFaceLivenessView, or headless with your own camera.

Face liveness checks that a real person is in front of the camera, not a photo, a screen or a mask. The user moves closer to the camera; with the light challenge, the screen also flashes a short sequence of colors. deepidv scores the capture and decides whether it passed.

![Animation on iPhone: a face in an oval, with a green ring filling around the oval and 'Slowly move closer, keep your face inside the oval'.](https://mintcdn.com/deep-identity-inc/KR_jLd52VE3haGnp/images/ios/liveness-ring-sequence.webp?fit=max\&auto=format\&n=KR_jLd52VE3haGnp\&q=85\&s=05562462ee2fb8c5361c5f3c2fb1b4ce)

The ring fills as the user moves closer.

## Three ways to run it

| | How | Use when |
| - | - | - |
| **Workflow step** (recommended) | Add a **face liveness** step to the workflow; `DeepIDVWorkflowView` runs it. | Onboarding with ID and liveness. |
| **`CustomFaceLivenessView`** | Present the view with a workflow session whose current step is face liveness. | You run the ID part some other way. |
| **Headless** | `checkMovementLiveness` with frames from your own camera. | You must use your own camera screen. See [Liveness with your own camera](https://docs.deepidv.com/integrate/sdks/ios/headless/liveness.md). |

The challenge type (movement, or movement and light) and the pass threshold are set on the workflow step, not in the app.

## Screens and states

![Front-camera screen: an oval with 'Position your face in the oval, then hold still while the screen flashes colors'.](https://mintcdn.com/deep-identity-inc/KR_jLd52VE3haGnp/images/ios/liveness-position.webp?fit=max\&auto=format\&n=KR_jLd52VE3haGnp\&q=85\&s=2d6860044d11f91221b9f676b8b7ee5e)

![Front-camera screen: the oval with a green ring two-thirds filled and 'Slowly move closer'.](https://mintcdn.com/deep-identity-inc/KR_jLd52VE3haGnp/images/ios/liveness-ring.webp?fit=max\&auto=format\&n=KR_jLd52VE3haGnp\&q=85\&s=ddca0b8e50d046440863c6752b23d656)

![The whole screen tinted green during the light challenge, with 'Hold still, keep looking at the screen'.](https://mintcdn.com/deep-identity-inc/KR_jLd52VE3haGnp/images/ios/liveness-flash.webp?fit=max\&auto=format\&n=KR_jLd52VE3haGnp\&q=85\&s=5edabf68c5856b0db632077e66ed9ec5)

![Result screen: a green tick with 'Liveness confirmed, thanks, that's everything we need'.](https://mintcdn.com/deep-identity-inc/KR_jLd52VE3haGnp/images/ios/liveness-passed.webp?fit=max\&auto=format\&n=KR_jLd52VE3haGnp\&q=85\&s=884ea534a6836aff2c8315c29d6cb6cf)

| State | Message |
| - | - |
| Getting ready | **Getting ready** · Next, a quick check that it's really you |
| Before the light challenge | **Position your face in the oval** · Then hold still while the screen flashes colors |
| Before the movement challenge | **Position your face in the oval** · Look straight at the screen |
| Moving closer | **Slowly move closer** · Keep your face inside the oval, with the ring filling |
| Too close | **Move back a little** · Your whole face should fit in the oval |
| Before the flashes | **Hold still** · The screen will flash a few colors |
| Flashing | **Hold still** · Keep looking at the screen, with the screen tinted |
| Passed | **Liveness confirmed** (standalone view) |
| Not passed | **We couldn't verify you**, with **Try again** |

> [!WARNING]
>
> The light challenge flashes the screen with bright colors. The user is warned before it starts. If your users may be sensitive to flashing light, use the movement-only challenge on the workflow step.

## `CustomFaceLivenessView`

```swift theme={null}
CustomFaceLivenessView(client: client, sessionID: sessionID) { result in
    switch result {
    case .success(let liveness):
        // A check that ran but didn't pass is a success with passed == false.
        print(liveness.status, liveness.passed, liveness.confidence ?? 0)
    case .failure(let error):
        // Permission, cancellation, capture or network.
        print("liveness error:", error.kind)
    }
}
```

| Parameter | Type | Description |
| - | - | - |
| `client` | `DeepIDVClient` | |
| `sessionID` | `String` | A workflow session whose **current** step is face liveness. Out of order fails with `.conflict`. |
| `onResult` | `(Result<FaceLivenessResult, DeepIDVError>) -> Void` | Called once. |

### `FaceLivenessResult`

| Property | Type | Meaning |
| - | - | - |
| `status` | `.succeeded`, `.inProgress`, `.failed` | The check's state. |
| `passed` | `Bool` | Computed by deepidv against the workflow's threshold. |
| `confidence` | `Double?` | **0 to 100.** `nil` on a failed workflow attempt. |

No images come back to the app.

## Guidance for your users

* Use a well-lit room, and face the light.
* Hold the phone at eye level and move it, or your head, slowly toward each other.
* Keep the whole face in the oval; take off sunglasses.
* During the flashes, keep still and keep looking at the screen.

## Related

* [Re-verification](https://docs.deepidv.com/integrate/sdks/ios/re-verification.md) uses the same check to confirm a returning user.
* [Failures and retries](https://docs.deepidv.com/integrate/sdks/ios/workflows/failures.md): `.livenessFailed`, `.livenessIDMismatch`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.