iOS integration - ID Verification - Alibaba Cloud Documentation Center

ID Verification provides a software development kit (SDK) for the iOS platform. This SDK helps you implement the electronic Know Your Customer (eKYC) remote identity verification feature in your mobile application. You must request and obtain a unique identifier (transactionId) from the server. Then, you can pass this identifier to call the corresponding feature of the SDK. This topic describes the integration process for the iOS platform and provides code examples.

Limits

Supports only mobile devices (iPhone or iPad) that run iOS 9 or later.
Required privacy permissions: Camera and Network.

Download and configure the SDK

Get the SDK

Download the iOS SDK and decompress the package. Then, copy all framework packages to your project folder.

Add required permissions

In the Info.plist file, add the following permissions. The descriptions are for reference only.

Add frameworks in Xcode

In your project settings, go to Build Settings > Build Phases > Link Binary With Libraries and add the frameworks.

Add all frameworks from the SDK:

AliyunIdentityFace.framework
AliyunIdentityPlatform.framework
AliyunIdentityUtils.framework
AliyunIdentityOcr.framework
ToygerService.framework
AliyunOSSiOS.framework
faceguard.framework
DTFUtility.framework
ToygerNative.framework
MNN.framework

Add system dependency libraries:

AudioToolbox.framework
CoreMedia.framework
CoreML.framework
AVFoundation.framework
SystemConfiguration.framework
UIKit.framework
CoreTelephony.framework
CoreMotion.framework
Accelerate.framework
libresolv.tbd
libsqlite3.tbd
libc++.tbd
libz.tbd

Copy resource files

In your project settings, go to Build Settings > Build Phases > Copy Bundle Resources and copy the resource files.

AliyunIdentityPlatform.bundle: The resource file is in AliyunIdentityPlatform.framework.
AliyunIdentityFace.bundle: The resource file is in AliyunIdentityFace.framework.
AliyunIdentityOCR.bundle: The resource file is in AliyunIdentityOcr.framework.
ToygerService.bundle: The resource file is in ToygerService.framework.

Configure linker flags

In your project settings, go to Build Settings > Other Linker Flags and add the -ObjC flag.

Call the SDK

Import the header file

#import <AliyunIdentityPlatform/AliyunIdentityPlatform.h>

Initialize the SDK

- (void)install;
- (void)installWithOptions:(NSMutableDictionary *)options;

Parameters:

options: Specifies optional parameters for information collection. This parameter is optional. The optional parameters are as follows:

Note

The ID Verification client has a built-in Device Guard security module. To meet data collection compliance requirements in different regions, it provides different data reporting sites. You can set CustomUrl and CustomHost to specify a reporting site based on user attributes.
Note: You can specify only one reporting site within a single application session lifecycle. The server query region must match the reporting site.
Specify a reporting site:
- Singapore site (default): https://cloudauth-device.ap-southeast-1.aliyuncs.com
- Indonesia site: https://cloudauth-device.ap-southeast-5.aliyuncs.com
- US West (Silicon Valley): https://cloudauth-device.us-west-1.aliyuncs.com
- Germany (Frankfurt): https://cloudauth-device.eu-central-1.aliyuncs.com
- China (Hong Kong): https://cloudauth-device.cn-hongkong.aliyuncs.com
For more information about the regions supported by product servers, see Supported regions.

Field name	Description	Example
IPv6	Specifies whether to use an IPv6 domain name to report device information: 0 (default): No (use an IPv4 domain name) 1: Yes (use an IPv6 domain name)	"1"
DataSwitch	The timing for reporting device information. 0 (default): At initialization 1: When getting the token Note We recommend using the default configurations.	"1"
CustomUrl	Sets the data reporting server domain name.	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
CustomHost	Sets the data reporting server host.	"cloudauth-device.ap-southeast-1.aliyuncs.com

Get metaInfo data

- (NSString *)getMetaInfo;

Your application server must first obtain the metaInfo from the client before it can call the Alibaba Cloud Initialize API.

Therefore, the client must first obtain the native metaInfo data and then use this metaInfo to complete the initialization and obtain the TransactionId.

Call the SDK to start verification

- (void)verifyWithCertifyId:(NSString *)certifyId
  withCurrentViewController:(UIViewController *)viewController
              withExtParams:(NSDictionary *)extParams
                   complete:(AliyunIdentityVerifyBlock)completeBlock;

Parameters

Name	Type	Description
transactionId	NSString	Obtained from the server-side Initialize API.
viewController	UIViewController	The current ViewController of the client application.
extParams	NSDictionary	Custom parameters. In most cases, you can pass null. For the currently supported parameter fields, see extParams configurations.
completeBlock	AliyunIdentityVerifyBlock	The callback at the end of the verification process. It contains the verification result.

extParams configurations

Key	Description	Example (String)
kIdentityParamKeyNextButtonColor	The color of the button at the bottom of the Optical Character Recognition (OCR) result page.	#FF0000
kIdentityParamKeyRoundProgressColor	The color of the circle during the face scan.	#FF0000
kIdentityParamKeyOcrSelectPhoto	Specifies whether to show the album upload entry during the certificate OCR step: 1: Show (default) 0: Hide	1
kIdentityParamKeyShowOcrResult	Specifies whether to show the result page during the certificate OCR step: 1: Show (default) 0: Hide	1
kIdentutyParamKeyEditOcrResult	Specifies whether the result page is editable during the certificate OCR step: 0: Not editable 1 (default): Editable	1
kIdentityParamKeyMaxRetryCount	The maximum number of retries. You can set this to a value from 3 to 10. The default value is 10.	10
kIdentityParamKeyCardOcrTimeOutPeriod	The timeout period for the OCR step. You can set this to a value from 20 to 60 seconds. The default value is 20 seconds.	20
kIdentityParamKeyFaceVerifyTimeOutPeriod	The timeout period for the liveness collection and detection step. You can set this to a value from 20 to 60 seconds. The default value is 20 seconds.	20
kIdentityParamKeyCardOcrEditTimeOutPeriod	The duration for which the OCR result page is editable. You can set this to a value from 60 to 180 seconds. By default, there is no limit.	180
kIdentityParamKeyLanguage	Custom language settings for the SDK. By default, the SDK uses the language of the mobile device's operating system. Note For a list of languages supported by the SDK, see Custom languages for Android and iOS SDKs.	zh-Hans
kIdentityParamKeyDefaultLanguage	The default language of the SDK. For valid values, see the kIdentityParamKeyLanguage field. The default value is en, which indicates English.	en
kIdentityParamKeyCloseButtonPosition	The position of the SDK's Close button: left: Left (default) right: Right	left
kIdentityParamKeyWatermark	The watermark text after successful OCR.	Test watermark text
kIdentutyParamKeyProtocol	The SDK protocol. Note Obtain the protocol from the server-side Initialize API and pass it in the extension parameters. This can reduce internal SDK API interactions and improve the network experience.	968412EB*******...

Error codes

Error code	Billed	Result code description
1000	Yes	The user completed the face scan process, and the recommended verification result is "pass". This result is for reference only. Call the server-side CheckResult API to get the final verification result for further processing.
1001	Yes	The user completed the face scan process, and the recommended verification result is "fail". This result is for reference only. Call the server-side CheckResult API to get the final verification result and the detailed reason for the failure for further processing.
1002	No	A system error occurred.
1003	No	The SDK failed to initialize. Check if the client time is correct.
1004	No	A camera error occurred. Try the following steps to resolve the issue: Before verification, make sure the application has been granted camera permission. If the permission error persists after authorization, try clearing the application cache and retry.
1005	No	A network error occurred.
1006	No	The user exited the process.
1007	No	The TransactionId is invalid.
1009	No	The client timestamp is incorrect.
1011	No	The submitted certificate type is incorrect.
1012	No	Key information is missing from the detected certificate, or the format verification failed.
1013	No	The image quality is poor.
1014	No	The number of errors exceeded the upper limit.

Sample code

#import "ViewController.h"
#import <AliyunIdentityPlatform/AliyunIdentityPlatform.h>

@interface ViewController ()
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
 
    // Initialize the SDK.
    [[AliyunIdentityPlatform sharedInstance] install];
 
    [self initUI];
}

// This function must be implemented by the user.
- (NSString *)sentMetaInfoAndGetTransactionId:(NSString*) metaInfo {
    return @"Get TransactionId from your server."; // Replace it.
}

- (void)onClickStart:(id) sender {
    NSString *metaInfo = [[AliyunIdentityPlatform sharedInstance] getMetaInfo];
    NSString *transactionId = [self sentMetaInfoAndGetTransactionId:metaInfo];

    // Set the SDK language.
    NSDictionary *extParams = @{
        kIdentityParamKeyLanguage:@"en"
        kIdentutyParamKeyProtocol:@"968412EB......................."// Configure this protocol to optimize network latency.
    };
    // Start verification.
    [[AliyunIdentityPlatform sharedInstance] verifyWithCertifyId:transactionId
                                       withCurrentViewController:self
                                                   withExtParams:extParams
                                                        complete:^(AliyunIdentityVerifyRes *response) {
        NSString *resContent = [NSString stringWithFormat:@"Code=%d Message=%@", response.code, response.message];
    }];
}

- (void)initUI {
    // ......
}

@end

Demo code package

Download the iOS demo code package to try it out.

Component trimming

Module	Trimmable	Description	Package size increase
AliyunIdentityNFC	Trimmable. You can trim this component if you do not use the NFC feature.	NFC module	3.7 M
OpenSSL	Trimmable. You can trim this component if you do not use the NFC feature.	NFC module dependency library	3.7 M
AliyunIdentityOcr	Trimmable. You can trim this component if you do not use the OCR feature. Note that a complete eKYC solution involves OCR.	OCR module	0.8 MB
faceguard	Not trimmable	Face Guard module	0.74 MB
AliyunIdentityFace	Not trimmable	Face detection module	2.2 M
ToygerService	Not trimmable	Liveness algorithm module	0.98 MB
ToygerNative	Not trimmable	Liveness algorithm module	0.98 MB
AliyunIdentityPlatform	Not trimmable	Base module	0.04 MB
AliyunIdentityUtils	Not trimmable	Base module	0.04 MB
MNN	Not trimmable	Liveness algorithm dependency library	0.09 MB
DTFUtility	Not trimmable	Base module	0.1 M
AliyunOSSiOS	Not trimmable	Face verification dependency library	0.23 MB