导入 SDK

远程安装

开始安装

  pod init

我们的 SDK 可以使用 CocoaPods 导入。

SDK	当前版本
ZaigIosFaceRecon	pod 'ZaigIosFaceRecon', '~> 6.1.1'

iOS Minimum Deployment Target

15.5

在搭载 arm64 芯片的 MacBook 上使用模拟器

目前，我们的 iOS FaceRecon SDK 不幸地不支持在搭载 arm64 架构芯片（M1/M2/M3/M4）的 MacBook 上运行的模拟器进行编译，除非使用 Rosetta（将 x86_64 架构翻译为 arm64）。

要开始安装，请在项目根目录中执行旁边的命令。

在 podfile 中添加 source

   source 'https://github.com/ZaigCoding/iOS.git'
   source 'https://cdn.cocoapods.org/'

下一步是在 podfile 文件中添加 QI Tech 的 source。

在 podfile 中添加 pod

  pod 'ZaigIosFaceRecon', '~> <version>'

最后，只需按照旁边的格式添加 pod 名称即可。

注意：

架构变更（v6.0.0+）从版本 6.0.0 起，SDK 开始以独占静态方式分发。在您的 Podfile 中，必须使用 :linkage => :static 配置。

Podfile 示例（版本 6.0.0 或更高）

  source 'https://github.com/ZaigCoding/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'ZaigIosFaceRecon', '~> 6.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end

Podfile 示例（旧版本）

  source 'https://github.com/ZaigCoding/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks!
    pod 'ZaigIosFaceRecon', '~> 5.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end

注意

在 iOS 中集成依赖项时，可能需要对某些库使用静态链接，对其他库使用动态链接。此配置对于确保兼容性、避免构建错误和优化项目性能非常重要。

混合依赖链接（如有必要）

混合链接的需求源于某些库有特定要求，一些库需要静态链接以避免内部冲突和符号重复，而其他依赖项可能需要动态链接，因为它们是为模块化和项目间共享而设计的。

静态链接与动态链接的区别

• 静态（static_framework）：库的代码直接嵌入到最终二进制文件中，减少运行时加载时间并消除运行时的外部依赖。
• 动态（dynamic_framework）：库在运行时作为单独文件加载。这减小了最终二进制文件的大小，便于独立更新/修改。

在 Podfile 中配置混合链接

...

use_frameworks! :linkage => :dynamic # 将默认链接模式设置为动态

...

static_frameworks = ['framework_1', 'framework_2', ...] # 包含所有需要静态链接的依赖项
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_frameworks.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_framework
      end
    end
  end
end

安装依赖项

  pod install

最后，执行 pod install 命令以下载和安装依赖项。

必要权限

为使 SDK 能够访问设备资源以采集用户自拍，需要向用户请求权限。

在 info.plist 文件中，添加以下权限：

权限	原因
Privacy - Camera Usage Description	访问相机以采集用户自拍。

启动 SDK

重要提示！

从版本 5.0.0 起，认证系统已更新，使用 clientSessionKey 代替 mobileToken。此外，还添加了新的反馈屏幕配置选项。

获取 Client Session Key

在配置 SDK 之前，您必须通过服务器到服务器的请求向我们的人脸识别 API 生成一个临时的 clientSessionKey。

端点

环境	URL
沙盒	https://api.sandbox.zaig.com.br/face_recognition/client_session
生产	https://api.zaig.com.br/face_recognition/client_session

请求

Method: POST

Headers:

{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}

Body（可选，但推荐）：

{
  "user_id": "unique_user_identifier"
}

重要： user_id 字段强烈建议用于安全和反欺诈措施。请使用您应用程序中用户的唯一标识符。

响应

成功响应将包含需要传递给 SDK 配置的 client_session_key。

{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

SDK 初始化示例

import ZaigIosFaceRecognition

class ViewController: UIViewController, ZaigIosFaceRecognitionControllerDelegate {

    var zaigFaceRecognitionConfiguration : ZaigIosFaceRecognitionConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupFaceRecognition()
    }

    func setupFaceRecognition() -> Void {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = ZaigIosFaceRecognitionEnvironment.Sandbox

        // ClientSessionKey is the key you got via Face Recognition request. Each environment requires a different API_KEY.
        let clientSessionKey = fetchClientSessionKey()

        self.faceRecognitionConfig = ZaigIosFaceRecognitionConfiguration(environment: environment,
                                            clientSessionKey: clientSessionKey,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            showInvalidTokenScreen: true,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let zaigFaceRecognitionController = ZaigIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
        zaigFaceRecognitionViewController.delegate = self
        let zaigFaceRecognitionViewController =  zaigFaceRecognitionController.getViewController()
        present(zaigFaceRecognitionViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech FaceRecognition's SDK successfully collected picture
    func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFinishWithResults results: ZaigIosFaceRecognitionControllerResponse) {

    }

    // Do something if QI Tech FaceRecognition's SDK found any error when collecting  picture
    func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFailWithError error: ZaigIosFaceRecognitionControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func zaigIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: ZaigIosFaceRecognitionController) {

    }
}

要将 SDK 嵌入到您的应用程序中，您必须通过 ZaigIosFaceRecognitionConfiguration 类配置自定义采集应用程序，然后实例化 ViewController ZaigIosFaceRecognitionController，并将自定义配置作为参数传递。

要启动面部分析过程，只需调用 present 函数来调用 QI Tech 的 ViewController 执行自拍采集。

重要的是要实现负责接收成功、错误或用户在验证任何步骤中中断旅程时的返回值的 Delegate。

旁边是完整的实现示例。

旧版本

SDK 初始化

import ZaigIosFaceRecognition

class ViewController: UIViewController, ZaigIosFaceRecognitionControllerDelegate {

    var zaigFaceRecognitionConfiguration : ZaigIosFaceRecognitionConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupFaceRecognition()
    }

    func setupFaceRecognition() -> Void {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = ZaigIosFaceRecognitionEnvironment.Sandbox

        // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
        let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"

        self.faceRecognitionConfig = ZaigIosFaceRecognitionConfiguration(environment: environment,
                                            mobileToken: mobileToken,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let zaigFaceRecognitionController = ZaigIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
        zaigFaceRecognitionViewController.delegate = self
        let zaigFaceRecognitionViewController =  zaigFaceRecognitionController.getViewController()
        present(zaigFaceRecognitionViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech FaceRecognition's SDK successfully collected  picture
    func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFinishWithResults results: ZaigIosFaceRecognitionControllerResponse) {

    }

    // Do something if QI Tech FaceRecognition's SDK found any error when collecting  picture
    func zaigIosFaceRecognitionController(_ faceRecognitionViewController: ZaigIosFaceRecognitionController, didFailWithError error: ZaigIosFaceRecognitionControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func zaigIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: ZaigIosFaceRecognitionController) {

    }
}

Mobile Token

我们使用 Mobile Token 来允许您的应用程序对我们的 API 进行认证访问。它可能已通过电子邮件发送给您。如果您尚未收到 token，请发送电子邮件至 suporte.caas@qitech.com.br。

我们的 API 期望在所有来自 SDK 的请求中接收 Mobile Token，因此必须通过上述方法将其作为配置参数包含在内。

注意

您必须将 "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" 替换为从支持团队收到的 Mobile Token。