> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-sdk/flutter/standalone-modules/deprecated-sdks/faceliveness.md).
# FaceLiveness
Check out the SDK documentation in pub.dev to get more examples and extra information:
* [versions below 5.0](https://pub.dev/packages/new_face_liveness)
* [versions 5.0 and above](https://pub.dev/packages/caf_face_liveness)
## Requirements
| Flutter | Version |
| ------- | ------- |
| Flutter | 1.20+ |
| Dart | 2.15+ |
| Android | Version |
| ---------- | ------- |
| minSdk | 21 |
| compileSdk | 34 |
| iOS | Version |
| ---------- | ------- |
| iOS Target | 13.0 |
| Xcode | 15.4+ |
| Swift | 5.3.2+ |
#### Sending your app to Play Store
To publish your app on the *Google Play Store*, you must complete a data safety form. Since we integrate with the *FingerPrintJS SDK*, you'll need to provide the following information:
| Question in Google Play Console's data safety form | Response |
| ------------------------------------------------------------------- | ------------------------------------------- |
| Does your app collect or share any of the required user data types? | Yes. |
| What type of data is collected? | Device or other identifiers. |
| Is this data collected, shared, or both? | Collected. |
| Is this data processed ephemerally? | Yes. |
| Why is this user data collected? | Fraud Prevention, Security, and Compliance. |
## Runtime permissions
### Android
| Permission | Reason | Required |
| ---------- | --------------------------------------------------------- | -------- |
| `CAMERA` | Capturing the selfie in policies with facial verification | Yes |
### iOS
| Permission | Reason | Required |
| ------------------------------------ | --------------------------------------------------------- | -------- |
| `Privacy - Camera Usage Description` | Capturing the selfie in live facial verification policies | Yes |
## Platform Configurations
### Android
If your version of Gradle is earlier than 7, add these lines to your `build.gradle`.
```groovy
allprojects {
repositories {
...
maven { url 'https://repo.combateafraude.com/android/release' }
maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
maven { url 'https://maven.fpregistry.io/releases' }
maven { url 'https://jitpack.io' }
}
}
```
If your version of Gradle is 7 or newer, add these lines to your `settings.gradle`.
```groovy
dependencyResolutionManagement {
repositories {
...
maven { url 'https://repo.combateafraude.com/android/release' }
maven { url 'https://raw.githubusercontent.com/iProov/android/master/maven/' }
maven { url 'https://maven.fpregistry.io/releases' }
maven { url 'https://jitpack.io' }
}
}
```
Add support for Java 8 to your `build.gradle` file. Skip this if Java 8 is enabled.
```groovy
android {
...
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
```
### iOS
In the `info.plist` file, add the permissions below:
```swift
NSCameraUsageDescription
To capture the selfie
```
## Usage
| Parameter | Required |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `mobileToken`: Usage token associated with your CAF account | Yes |
| `personId`: Identifier of the user who will perform the face liveness verification. It's recommended to use the user's identification document in this field, such as their CPF (Brazilian document ID), but it could be any other value. | Yes |
```dart
FaceLiveness faceLiveness =
FaceLiveness(mobileToken: mobileToken, peopleId: personId);
// Your SDK customization parameters
final stream = faceLiveness.start();
stream.listen((event) {
if (event is FaceLivenessEventConnecting) {
// The SDK is connecting to the server. You should provide an indeterminate progress indicator
// to let the user know that the connection is taking place.
} else if (event is FaceLivenessEventConnected) {
// The SDK has connected, and the iProov user interface will now be displayed. You should hide
// any progress indication at this point.
} else if (event is FaceLivenessEventClosed) {
// The user canceled face verification, either by pressing the close button at the top of the screen, or sending
// the app to the background.
} else if (event is FaceLivenessEventSuccess) {
// The user was successfully verified/enrolled and the token has been validated.
// You can access the following properties:
final signedResponse = event.signedResponse;
} else if (event is FaceLivenessEventFailure) {
// The user was not successfully verified/enrolled, as their identity could not be verified,
// or there was another issue with their verification/enrollment (e.g. lost internet connection).
// You can access the following properties:
final errorType = event.errorType
final errorDescription = event.errorDescription
}
});
```
### FaceLiveness Options
| Option | Required | Default Value | Android | iOS |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------- | ------- | --- |
| .setStage(String stage)
Used to redirect the SDK to the desired environment in caf api.
| No | `CafStage.prod` | ✅ | ✅ |
| .setFilter(String filter)
Set the camera filter applied to the camera preview.
| No | `CameraFilter.lineDrawing` | ✅ | ✅ |
| .setEnableScreenshots(bool enable)
Used to enable screenshots during the SDK scan.
| No | `false` | ✅ | ❌ |
| .setEnableLoadingScreen(bool enable)
Used to determines whether the SDK's loading screen will be implemented through client side or if will be used the default screen. If set to 'true,' the loading screen will be a standard SDK screen. If 'false,' You should provide an indeterminate progress indicator.
| No | `false` | ✅ | ✅ |
| .setImageUrlExpirationTime(String time)
Use to change the default image URL expiration time to retrieve the facial capture.
| No | 30 min | ✅ | ✅ |
| .setReverseProxySettings(ReverseProxySettings settings)
Use to configure the reverse proxy settings for running the FaceLiveness and/or Authentication services.
| No | | ✅ | ❌ |
### ReverseProxySettings
The reverse proxy settings that will be used to run the FaceLiveness and Authentication services. These two services can operate independently of each other, FaceLiveness and Authentication.
**FaceLiveness reverse proxy:**
| Parameter | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `String? faceLivenessBaseUrl` | The base URL of the reverse proxy that will be used to run the FaceLiveness service. **The URL's protocol must be WSS**. |
| `List? certificates` | A list of certificates that will be used to authenticate the reverse proxy to run the FaceLiveness service. The certificates must be **base64-encoded SHA-256 hash of certificate' Subject Public Key Info**. |
**Authentication reverse proxy:**
| Parameter | Description |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `String? authenticationBaseUrl` | The base URL of the reverse proxy that will be used to run the Authentication service. **The URL's protocol must be HTTPS**. |
### Enums
#### CafStage
| Description | Values |
| -------------------------------------------------------------- | -------------------------------- |
| Used to set the SDK stage on `.setStage(String stage)` option. | `CafStage.prod`, `CafStage.beta` |
#### CameraFilter
| Description | Values |
| -------------------------------------------------------------------------- | -------------------------------------------------- |
| Used to set the SDK's camera filter on `.setFilter(String filter)` option. | `CameraFilter.natural`, `CameraFilter.lineDrawing` |
#### Time
| Description | Values |
| ---------------------------------------------------------------------------------------------- | ------------------------------------ |
| Used to set the image URL expiration time on `.setImageUrlExpirationTime(String time)` option. | `Time.threeHours`, `Time.thirtyDays` |
## FaceLiveness Event Streaming
### FaceLivenessEventConnecting
The SDK is loading, you can use this event return to set an action in your app, for example, a loading indicator.
### FaceLivenessEventConnected
The SDK is not loading anymore, you can use this event return to set a action in your app, for example, you can stop your loading indicator.
### FaceLivenessEventClosed
The execution has been cancelled by the user.
### FaceLivenessEventSuccess
| Event | Description |
| ------------ | -------------------------------------------------------------------------------------- |
| `requestId` | Request identifier. |
| `isAlive` | Validation of a living person, identifies whether the user passed successfully or not. |
| `token` | Request token. |
| `userId` | User identifier provided for the request. |
| `imageUrl` | Temporary link to the image, generated by our API. |
| `personId` | User identifier provided for the SDK. |
| `sdkVersion` | Sdk version in use. |
| `iat` | Token expiration. |
{% hint style="info" %}
The `isAlive` parameter is **very important**, based on this validation, the user can be guided to continue the flow or not. In case of `isAlive: true`, it would be able to continue with the journey. If `isAlive: false`, this user is not valid and should be prevented from continuing their journey.
{% endhint %}
### FaceLivenessEventFailure
| Parameter | Description |
| ------------------------- | ---------------------------------------------- |
| `String errorType` | Error type returned by the SDK |
| `String errorDescription` | Error description message returned by the SDK. |
| Error type cases | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `unsupportedDevice` | This error may occur if the device hardware or software does not meet the minimum requirements for facial recognition functionality. |
| `cameraPermission` | This error typically occurs when the user denies access to the camera or if the app lacks the necessary permissions. |
| `networkException` | This error may occur due to various network issues such as a lack of internet connection, server timeouts, or network congestion. |
| `tokenException` | This error may occur if the provided authentication token is invalid, expired, or lacks the necessary permissions to perform facial recognition tasks. |
| `serverException` | This error is typically returned when there is an issue with the server processing the facial recognition request. This could include server-side errors, misconfigurations, or service interruptions. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.caf.io/caf-sdk/flutter/standalone-modules/deprecated-sdks/faceliveness.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.