startFaceAuthSDK(viewController: UIViewController, mobileToken: String, personId: String)
mobileToken: Usage token associated with your CAF accountpersonId: 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..setStage(stage: CAFStage)
Used to redirect the SDK to the desired environment in caf api. It has the following options: .beta or .prod.
.setFilter(filter: Filter)
Set the camera filter applied to the camera preview. It has the following options: .natural or .lineDrawing
.setLoadingScreen(withLoading: Bool)
This boolean parameter determines whether the loading screen will be implemented via a delegate or if you will use the default screen. If set to 'true,' the loading screen will be a standard SDK screen. In the case of 'false,' you should use the 'LoadingScreen' session and implement the delegates.
| No | **false** | |.setImageUrlExpirationTime(time: Time)
Use to change the default image URL expiration time to retrieve the scan capture. It has the following options: .threeHours, .thirtyDays or .thirtyMin.
.setAuthBaseUrl(authBaseUrl: String)
Enables the use of a reverse proxy to execute SDK's authentications. Sets the base URL for authentication; protocol must be HTTPS. Adds a trailing slash if missing.
| No | **Default Caf URL** | |.setLivenessBaseUrl(livenessBaseUrl: String)
Enables the use of a reverse proxy to execute face liveness checks. Sets the base URL; protocol must be WSS. Adds a trailing slash if missing. Requires certificates set via .setCertificates for security.
.setCertificates(certificates: \[String])
Sets the SHA256 Base64-encoded protocols for secure communication in reverse proxy implementations. Required when using custom URLs for authentication or face liveness checks.
| No | **Empty list** | |.setCustomLocalization(named: String?)
This method allows you to specify a custom localization resource name for the iProov module. When a name is provided, the SDK will load the matching localization file instead of the default resource bundle. For further details on the localization files format and integration, please refer to the iProov Localization documentation.
| No | **nil** | ### Reverse Proxy To configure reverse proxy settings, please follow these instructions: #### CafFaceAuth Reverse Proxy * Set your proxy to communicate with the URL that corresponds to the `CAFStage` you are using: * `CAFStage.PROD` -> `https://api.public.caf.io/v1/sdks/faces/` * `CAFStage.BETA` -> `https://api.public.beta.caf.io/v1/sdks/faces/` * `CAFStage.DEV` -> `https://api.public.dev.caf.io/v1/sdks/faces/` * Use the method `.setLivenessBaseUrl` to set the URL on which FaceLiveness should run. * **The URL's protocol must be WSS.** * Use the `.setCertificates` method to set the certificates, which should be the base64-encoded SHA-256 hash of the certificate's Subject Public Key Info. * **Certificates are required for the FaceLiveness reverse proxy to work properly.** ```swift faceAuthenticator = FaceAuthSDK.Build() .setLivenessBaseUrl("wss://my.proxy.io/ws/") .setCertificates(certificates: [ "4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=", "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=", "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9=" ]) .build() ``` #### Authentication reverse proxy * Set your proxy to communicate with \`wss\://us.rp.secure.iproov.me/ws´. * Use the method `.setAuthBaseUrl` to set the URL on which the authorization requests must run. * **The URL's protocol must be HTTPS.** ```swift faceAuthenticator = FaceAuthSDK.Build() .setAuthBaseUrl("https://my.proxy.io/v1/faces/") .build(); ``` ### SDK Returns #### Success cases At the end of a successful execution, you will receive an object of type `FaceAuthenticatorResult`. This object carries a `signedResponse` property containing a JWT token with the execution result. This token should be decrypted to obtain the execution results details. ```swift faceAuthenticatorResult.signedResponse ``` Within the `signedResponse`, the parameter `isAlive` defines the execution of liveness, where `true` is approved and `false` is rejected ([Error case](#error-cases) will be returned). **SignedResponse params** | Event | Description | | ------------ | -------------------------------------------------------------------------------------- | | `requestId` | Request identifier. | | `isAlive` | Validation of a living person, identifies whether the user passed successfully or not. | | `isMatch` | Face match validation result. | | `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. | | `message` | Return message. | {% hint style="warning" %} The **isAlive** parameter is **VERY IMPORTANT**, as it dictates whether the validation process proceeds or halts. When `isAlive: true`, the user gains passage to continue their journey; conversely, if `isAlive: false`, the user is deemed invalid and access to further stages of the journey should be denied. Additionally, the `isMatch` parameter indicates the success or failure of the face match, returning `isMatch: true` for successful matches and `isMatch: false` otherwise. This parameters plays a pivotal role in guiding the flow of operations. {% endhint %} #### Error cases In the event of execution errors, you will receive an object of type `FaceAuthenticatorErrorResult`. This object encompasses an enum containing the `errorType`, and a `description`. | ErrorType | 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/ios/standalone-modules/caffaceauth/references.md?ask=