iOS client integration

Prerequisites

• Your app must run on a physical device running iOS 9.0 or later.

• You must use Objective-C++ to integrate the Real-Person Verification service.

SDK and demo code

• Download the iOS SDK.

• Download the iOS Demo.

  After downloading the iOS Demo, you must modify the bundle identifier.

Development setup

1. Configure the camera permission request in your Info.plist file.

   Add a key named Privacy - Camera Usage Description with the type String. For the value, provide a message that explains why your app needs camera access. For example: "This app requires camera access to perform face authentication."

2. In your Xcode build settings, disable the Bitcode option.

3. In your Xcode build settings, navigate to Linking > Other Linker Flags and add the -ObjC flag.

Resource files

Dependencies

Calling the SDK

1. Import the header file.

   #import <ZolozFaceAuthFacade/ZolozFaceAuthFacade.h>

2. Initialize the SDK.

   The code to initialize the SDK is as follows:

   [ZolozFaceAuthFacade init];

   This initialization method improves the user experience by preloading necessary data for face authentication. This method runs asynchronously and does not block the main thread. We recommend calling it in the application:didFinishLaunchingWithOptions: function of your app delegate:

   -(BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions

3. Get the metainfo data.

   [ZolozFaceAuthFacade getMetaInfo];

   The returned value is an NSDictionary. Your mobile client must convert it to a JSON string and pass this string to the MetaInfo parameter when calling the request for mobile client-based verification and authentication API.

4. Start the verification.

   • Call the SDK.

     [ZolozFaceAuthFacade verifyWith:self.verificationToken extParams:extParams onCompletion:^(ZIMResponse *response) {}];

   • Parameters

     • verificationToken: An NSString object. Obtain this value from the VerificationToken parameter returned by the request for mobile client-based verification and authentication API.

       Note

       The VerificationToken returned by the request for mobile client-based verification and authentication API is valid for 30 minutes from the time it is generated. Attempting to start face authentication with an expired token causes an error. Ensure you complete the verification within this time frame.

     • extParams: An NSDictionary object. You must pass the current view controller in this dictionary. The SDK uses it to display a loading indicator and present the verification view controller.

       [extParams setValue:self forKey:@"currentCtr"];

       (Optional) Return a video: To record a video of the verification process, add the returnVideo key with a value of true to the extParams dictionary. The verifyWith method then saves the video to the path specified in the videoFilePath field of the ZIMResponse object returned by the verifyWith method.

       [extParams setValue:@"true" forKey:@"returnVideo"];

   • Sample code

     [ZolozFaceAuthFacade verifyWith:self.verificationToken extParams:extParams onCompletion:^(ZIMResponse *response) {
         dispatch_async(dispatch_get_main_queue(), ^{
           NSString *title = @"Success";
           switch (response.code) {
             case 1000:
                 break;
             case 1001:
                 title = @"System Error";
                 break;
             case 1003:
                 title = @"User Canceled";
                 break;
             case 2002:
                 title = @"Network Error";
                 break;
             case 2006:
                 title = @"Verification Failed";
                 break;
             case 2003:
                 title = @"Incorrect Device Time";
                 break;
             default:
                 break;
         }
       });
     }];

   • The response.code property is an integer and has the following possible values:

     Code	Error code	Description
     1000	ZIMResponseSuccess	Indicates that the face authentication was successful. This result is for reference only. To get the final verification result, call the query of mobile client-based verification and authentication API.
     1001	ZIMInternalError	Indicates a system error.
     1003	ZIMInterrupt	Indicates that the user canceled the verification.
     2002	ZIMNetworkfail	Indicates a network error.
     2003	ZIMTIMEError	Indicates that the device time is incorrect.
     2006	ZIMResponseFail	Indicates that the face authentication failed. To obtain detailed failure reasons, call the query of mobile client-based verification and authentication API.

     For more information, see iOS client error codes.

     [ZolozFaceAuthFacade verifyWith:self.verificationToken extParams:extParams onCompletion:^(ZIMResponse *response) {}];

     response.imageContentData: The captured face image data, returned as an NSData object. This value is nil if the user cancels the process or if the operation times out. When uploading the image from the client, do not compress or resize the NSData object. The service performs an MD5 check on the image, and any modification will cause this check to fail. The following example shows how to convert the NSData object to an image:

     UIImage* newImage = [UIImage imageWithData:response.imageContentData];

     response.reason and response.retMessageSub: Strings that provide more details about the authentication result or failure.

App Store submission

When submitting your app to the App Store, you must include descriptions for the following required permissions in your Info.plist file. Failure to do so will result in your app being rejected:

• Camera permission: You must add a description for the Privacy - Camera Usage Description key in your Info.plist file.

• IDFA permission: You must add a description for the NSUserTrackingUsageDescription key in your Info.plist file. For example: "This permission is used only to identify the device, secure the real-person verification process, and improve service experience. It will not be used to track your activity across other companies' apps or websites."