GBG Developers

Guides   |   Using the Liveness Service

Using the Liveness Service

The Liveness service automatically prompts the user to face the camera and perform actions such as looking in a different direction, or smiling. After a number of actions, the SDK responds with a result indicating the liveness status.

The conf variable in this example is used to configure the service.

let conf = IDSLivenessConfig.defaultConfig
conf.numberOfMaxFailures = 4
conf.numberOfActions = 3

The configurable parameters are:

  1. actionTimeout - a value in seconds to allow for an action to be performed before it times out
  2. numberOfActions - the number of actions required in order for a user to pass the Liveness test
  3. numberOfFaceImages - the number of image frames that should be captured for a callback (see the receivedFace function further below)
  4. numberOfMaxFailures - the maximum amount of failures allowed to occur before a Liveness pass result is no longer possible
  5. minTimeoutTime - a value in seconds to represent the minimum time for a user Liveness action; a value which is too short provides a bad user experience
  6. passFrames - a number of image frames that must be seen containing an action before it can result in a pass
  7. jumpsAllowed - the maximum number of jumps in the video feed allowed before a Liveness pass result is no longer possible. Set to -1 to disable jump detection

Liveness cannot be the first service used; a person identifier, customer reference and document verification identifier are needed from a previous document verification. In order to access these identifiers you can use the GBGVerifyResponseManager object which is a singleton instance that provides storage and access to them for use with any services in the SDK.

The code snippet below is used to create the Liveness view controller, and pass in the Liveness configuration and the identifiers from the GBGVerifyResponseManager object. The present method launches the service.

let gbgLivenessVC = GBGLivenessViewController(config: conf, personId: GBGVerifyResponseManager.shared.personId ?? "", documentVerificationId: GBGVerifyResponseManager.shared.verificationId ?? "", delegate: self)
gbgLivenessVC.modalPresentationStyle = .overFullScreen
self.present(gbgLivenessVC, animated: true)

When the code runs, a delegate is required in order to handle the actions from the view controller. The code shown below handles the Liveness service response and failure cases by printing a message to the console. The didFinishLiveness function is executed when the Liveness capture was completed and the GBG cloud service has come back with a Liveness service response. Use this didFinishLiveness function in your app to handle Liveness pass or failure responses. The serviceResult variable can be used to examine if the result was a pass or failure.

The didFailLiveness function can also be called in some failure situations such as if images failed to be captured while running the Liveness service. The reason for the error is printed to the console in this example.

The receivedFace function can be left empty; this function is called for each image frame as the Liveness feature is being used. If the application requires the frames, that can be done using this receivedFace function.

extension StartLivenessVerificationViewController: GBGLivenessDelegate {
    func didFinishLiveness(_ livenessController: GBGLivenessViewController, with livenessResult: GBGLivenessResult, with serviceResult: GBGResponse<GBGLivenessResultResponse>) {
        print("liveness service response \(serviceResult.body)")
    func didFailLiveness(_ livenessController: GBGLivenessViewController, with error: Error) {
        print("liveness failure \(error)")
    func receivedFace(_ image: UIImage) {

When the code is run, the camera will start up and a message and animated graphic will appear, to prepare the user.

After the user has proceeded to continue with the Liveness detection, further prompts and animated graphics will appear to guide the user to perform the physical liveness actions.