integration-default-ui-mode

Integration Documentaion(Default UI)

This document explains how to use the default UI component to to quickly achieve the desired functionality.

Installation

CocoaPods

Specify the SDK name and url in the Podfile:


pod 'AAIGlobalIQASDK', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-global-IQA/1.4.0/iOS-GlobalIQA-SDK-V1.4.0.tar.bz2', type: :tbz

# Optional dependency
pod 'AAIGlobalIQAUI', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-global-IQA/1.4.0/iOS-GlobalIQA-UI-V1.4.0.tar.bz2', type: :tbz

# Optional dependency
pod 'AAIGlobalIQAModel', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAIGlobalIQAModel/1.0.0/AAIGlobalIQAModel-V1.0.0.tar.bz2', type: :tbz

pod 'AAINetwork', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAINetwork/AAINetwork-V1.0.4.tar.bz2', type: :tbz

pod 'AAICore', :http => 'https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-libraries/AAICore/1.0.1/AAICore-V1.0.1.tar.bz2', type: :tbz

Install the dependencies in your project:
```
pod install
```

Add camera usage description in Info.plist as below. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the card</string>

Swift package manager

Download the SDK SPM package, then unzip it.
In Xcode, select Project -> Package Dependencies -> Add Local..., then select the AAIGlobalIQASDK folder of unzipped folder.

Add camera usage description in Info.plist as below. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the face movements</string>

Refer to the demo project LivenessSDKSwiftDemo_SPM of the unzipped folder to see how to use the SDK.

Carthage

Add the following lines to your Cartfile:


binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-global-IQA/Carthage/AAIGlobalIQASDK.json" == 1.4.0

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAINetwork.json" == 1.0.4

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-liveness-detection/Carthage/AAICore.json" == 1.0.1

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-global-IQA/Carthage/AAIGlobalIQAModel.json" == 1.0.0

binary "https://prod-guardian-cv.oss-ap-southeast-5.aliyuncs.com/sdk/iOS-global-IQA/Carthage/AAIGlobalIQAUI.json" == 1.4.0

Run carthage update --platform iOS --use-xcframeworks to download the SDK.
Add the AAIGlobalIQA.xcframework, AAIGlobalIQAModel.xcframework, AAINetwork.xcframework ,AAICore.xcframeworkof Carthage/Build folder to the Frameworks, Libraries, and Embedded Content section in the General settings tab of your application targets. Note Embed & Sign should be selected.

Add camera usage description in Info.plist as below. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the card</string>

Download the carthage demo project AAIGlobalIQASDKSwiftDemo to see how to use the SDK.

Manually

Download the following SDK and frameworks:
- AAIGlobalIQASDK
- AAIGlobalIQAUI
- AAIGlobalIQAModel
- AAINetwork
- AAICore After downloading, extract the files, add the resulting .xcframework files to your Xcode project, and set the embedding option to "Embed & Sign".
Choose "TARGETS -> General" add the following system libraries and frameworks in the Frameworks, Libraries, and Embedded Content section:
- libc++.tbd
- libz.tbd
- AVFoundation.framework
- CoreGraphics.framework
- MediaPlayer.framework
- SystemConfiguration.framework
- Accelerate.framework

Add camera usage description in Info.plist as below. Ignore this step if you have added those.


<key>NSCameraUsageDescription</key>
<string>Use the camera to detect the card</string>

Usage

Import SDK and initialize with region and cardType and cardSide:


import AAIGlobalIQASDK
// Specify the `region`, `cardType` and `cardSide`
let config = AAIGlobalIQAConfig.initWithRegion("ID", cardType: .idCard , cardSide: .front)
config.delegate = self
// If you set YES, then the method `iqaOnDetectionComplete:` is called after the IQA page is dismissed.
config.callbackAfterPageDismissed = true

/*
// Specify the operating mode of the SDK.
/// The SDK can have different operating modes, such as real-time scanning mode, photo mode, default mode(Scanning + Photo). Default is 'AAIIQAOperatingModeDefault'.
// e.g.
config.operatingMode = .scanning;
*/

// Init SDK
AAIGlobalIQASDK.initWith(config);

User binding (Optional, but highly recommended).
You can use this method to pass us your unique user ID or other reference id, and we will establish a mapping relationship based on that ID. It's easy to track logs with us in case of problems.
```
AAIGlobalIQASDK.bindUser("your-user-id")
```

Configure SDK license, then show SDK page:


// Note that the "setLicenseAndCheck:" method MUST BE CALLED before calling "startWithRootVC:".
let result = AAIGlobalIQASDK.setLicenseAndCheck(demoLicenseContent)
if result == "SUCCESS" {
    // Show SDK page
    AAIGlobalIQASDK.start(withRootVC: self)
} else {
    if result == "LICENSE_EXPIRE" {
        print("LICENSE_EXPIRE: please call your server's api to generate a new license")
    } else if result == "APPLICATION_ID_NOT_MATCH" {
        print("APPLICATION_ID_NOT_MATCH: please bind your app's bundle identifier on our cms website, then recall your server's api to generate a new license")
    } else {
        print("\(result)")
    }
}

Get detection results.


func iqa(onDetectionComplete result: AAIGlobalIQAResult) {
     // Please save eventId for tracking issue
     let eventId = result.eventId
     print("eventId: \(eventId)")
     if result.success {
         // The final output captured card image in base64 format.
         // Note that this image data is suitable for uploading to the server as it has been appropriately compressed.
         // You can also obtain this image by calling server side api 'openapi/face-identity/image-quality-check/v1/query'
         let finalImgBase64Str = result.cardImgBase64String
                 
         // The raw output captured card image without any compression.
         // Note that this image is generally used for preview purposes.
         // If you want to upload the image to the server, you should use the `cardImgBase64String` property.
         let cardImg = result.cardImg
         
         // The identifier string that corresponds to the captured card image, which can be used to retrieve the image
         // by calling the server side api 'openapi/face-identity/image-quality-check/v1/query'.
         let idvid = result.idvid
                 
         let transactionId = result.transactionId
         
         let pictureType = result.pictureType
         
         if let ocrResult = result.ocrResult {
             // Use ocrResult dictionary
         }
         
         if let idForgeryResult = result.idForgeryResult {
             // Use idForgeryResult dictionary
         }
     } else {
         let errorCode = result.errorCode
         if let errorMsg = result.errorMsg {
             // Use errorMsg
         }

         if let transactionId = result.transactionId {
             // Use transactionId
         }
     }
 }

Customizable UI

Regarding UI customization:

Basic Modifications: If you are using the default UI module (AAIGlobalIQAUI), to adjust colors or styles, simply modify the corresponding fields in uiConfig, or inherit specific UI component classes for more complex styling. Refer to the custom UI examples in the Demo project for usage and effects.

Advanced Customization: If existing UI interfaces are insufficient or complex interaction logic is required, use the core view AAIIQACameraWrapperView provided by the SDK to fully implement UI (examples are also available in the Demo). This approach grants complete control over UI appearance and interaction logic. See this document for how to use AAIIQACameraWrapperView.

The following is the related code for Basic Modifications:


let config = AAIGlobalIQAConfig.initWithRegion("ID", cardType: .idCard , cardSide: .front)

// Whether to callback the AAIGlobalIQADelegate method `iqaOnDetectionComplete:` after the view controller is dismissed.
// Default is NO, which means that the `iqaOnDetectionComplete:` method will be called before the IQA page is closed,
// If you set YES, then the method `iqaOnDetectionComplete:` is called after the IQA page is dismissed.
config.callbackAfterPageDismissed = true

// Specify the operating mode of the SDK.
/// The SDK can have different operating modes, such as real-time scanning mode, photo mode, default mode(Scanning + Photo). Default is 'AAIIQAOperatingModeDefault'.
// e.g.
config.operatingMode = AAIIQAOperatingModeScanning;
// You can determine the language used by the SDK by setting this property.
// Available languageLprojName are "en", "id", "th", "zh-Hans"
config.languageLprojName = "id"

// e.g.
config.uiConfig.flipCameraBtnVisible = false
config.uiConfig.lightBtnVisible = false

// Whether the show the timer label in the upper right corner of the view. Default is YES.
config.uiConfig.timerLabelVisible = false

config.uiConfig.navBarTitleTextColor = .red
config.uiConfig.navBarBackgroundColor = .white
config.uiConfig.statusBarStyle = .default
config.uiConfig.tipIconVisible = false
config.uiConfig.pageBackgroundColor = .red
config.uiConfig.viewfinderColor = .green
config.uiConfig.primaryTextColor = .yellow
config.uiConfig.toolButtonThemeColor = .blue
config.uiConfig.orientation = .portrait
config.uiConfig.takePhotoTipTextColor = .white
config.uiConfig.takePhotoTipBackgroundColor = .blue
config.uiConfig.previewPhotoTipBackgroundColor = .blue
config.uiConfig.previewPhotoTipTextColor = .white
config.detectionTimeoutInterval = 20
config.returnEmptyOfOCR = false

// Set the left and right margin on x-axis of cameraView when device in portrait mode.
config.uiConfig.cameraViewMarginLRInPortraitMode = 12

// The duration of the alert view displayed when SDK are about to enter the photo mode,
// the default is 0s, which means the alert view will not be displayed.
config.takePhotoAlertViewTimeoutInterval = 0

// If you want to add custom UI on the SDK page, just register the custom class to the SDK, see demo project for more details.
/*
// You can customize the scan page UI by inheriting `AAIIQAScanController` class, then register your custom class to the SDK. See demo project for more detail.
config.register(CustomScanController.self, for: .scanController)
*/

/*
// You can customize the preview photos taken page UI by inheriting `AAIIQAPreviewImgController` class, 
// then register your custom class to the SDK. See demo project for more detail.
config.register(CustomPreviewImgController.self, for: .previewImgController)
*/

/*
// You can customize the camera overlay view UI of `AAIIQAScanController` page by inheriting `AAIIQAOverlayView` class, 
// then register your custom class to the SDK. See demo project for more detail.
config.register(CustomOverlayView.self, for: .overlayViewOfScanVC)
*/

/*
// You can customize the camera overlay view UI of `AAIIQAPreviewImgController` page by inheriting `AAIIQAOverlayView` class, 
// then register your custom class to the SDK. See demo project for more detail.
config.register(CustomOverlayView.self, for: .overlayViewOfPreviewImgVC)
*/

/* imageName list:
  advance_iqa_scan: An image to show the scan animation.
  advance_iqa_tip_capture: The icon in the countdown pop-up view after the scan times out.
  iqa_back: Icon of navigation bar back button.
  iqa_land_confirm: Confirm button icon in landscape take photo mode.
  iqa_land_retake: Retake button icon in landscape take photo mode.
  iqa_light_off: Icon of flashlight off button.
  iqa_light_on: Icon of flashlight on button.
  iqa_scan_processing: The icon displayed at the bottom of the vertical screen (local string key is: "hold_phone").
  iqa_scan_successfully: The icon displayed at the bottom of the vertical screen (local string key is: "iqa_scan_successfully").
  iqa_scan_warning: The icon displayed at the bottom of the vertical screen (local string key is: "iqa_card_poor_quality").
  iqa_take_photo_tip: The tip icon displayed at the bottom of the viewfinder view (local string key is: "iqa_take_photo_tips").
  iqa_take_photo: Icon of take photo button.
  iqa_transform_camera: Icon of switch camera button.
 */
// You can implement this block to customize the images used in the SDK.
config.uiConfig.loadImage = {(imgName, img) -> UIImage in
    if imgName == "iqa_scan_successfully" {
        return UIImage(named: "ok")!
    }
    return img
}

/*
// You can implement this block to customize the localization string used in the SDK.
// For all available keys, see "AAIGlobalIQASDK.framework/AAIIQALanguageString.bundle/en.lproj/Localizable.strings"
*/
config.uiConfig.loadLocalizedString = {(key, value, language) -> String in
    if key == "iqa_top_desc" && language == "en" {
        return "My test string"
    }
    // Using default SDK localizable string value
    return value
}

Error code

Name	Description
USER_GIVE_UP	User tapped the back button
DEVICE_NOT_SUPPORT	This device is not supported
CAMERA_PERMISSION_DENIED	Permission to access the camera is not authorized
NETWORK_REQUEST_FAILED	Network request failed
CAMERA_OPEN_FAILED	Failed to open camera
MODEL_ERROR	Failed to load model
SCAN_TIMEOUT	Scan timeout. Note this code appears only when you set the `operatingMode` of `AAIGlobalIQAConfig` to "AAIIQAOperatingModeScanning".
Other error code	Other error codes from server side