Integrate the native app SDK on iOS to implement eKYC - ID Verification - Alibaba Cloud - ID Verification

Limitations

Requires an iPhone or iPad with iOS 9 or later.
Requires camera and network permissions.

Download and configure the SDK

Get the SDK

Download the iOS SDK from the Client SDK release notes. Extract the package and copy all frameworks into your project folder. You can also download the iOS Demo to try out the features.

Add required permissions

Add the following permissions to your Info.plist file. The permission descriptions are for reference only.

Add xcframeworks in Xcode

Go to Build Settings > Build Phases > Link Binary With Libraries and add the xcframeworks.

Add all the xcframeworks included in the SDK:

AliyunIdentityFace.xcframework
AliyunIdentityPlatform.xcframework
AliyunIdentityUtils.xcframework
AliyunIdentityOcr.xcframework
AliyunOSSiOS.xcframework
faceguard.xcframework
IDVMNN.xcframework

Add the following system 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

Go to Build Settings > Build Phases > Copy Bundle Resources and add the resource files.

AliyunIdentityPlatform.bundle: Find this resource in AliyunIdentityPlatform.xcframework/ios-arm64/AliyunIdentityPlatform.framework.
AliyunIdentityFace.bundle: Find this resource in AliyunIdentityFace.xcframework/ios-arm64/AliyunIdentityFace.framework.
AliyunIdentityOCR.bundle: Find this resource in AliyunIdentityOcr.xcframework/ios-arm64/AliyunIdentityOcr.framework.

Configure linker flags

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:

The options parameter, which is null by default, specifies optional data collection settings.

Important

The ID Verification client includes a built-in security module known as the device helper. The device helper provides various data reporting regions to meet local data collection compliance requirements. You can set CustomUrl and CustomHost to specify different reporting sites based on user attributes.
Only one data reporting region can be specified per application session lifecycle. The region for server-side queries must match the reporting region. The supported regions vary by product. For more information, see Supported regions.
For each region, the CustomUrl is as follows:
- China (Hong Kong): https://cloudauth-device.cn-hongkong.aliyuncs.com
- Singapore: https://cloudauth-device.ap-southeast-1.aliyuncs.com
- Indonesia (Jakarta): https://cloudauth-device.ap-southeast-5.aliyuncs.com
- US (Silicon Valley): https://cloudauth-device.us-west-1.aliyuncs.com
- Germany (Frankfurt): https://cloudauth-device.eu-central-1.aliyuncs.com
- Malaysia (Kuala Lumpur): https://cloudauth-device.ap-southeast-3.aliyuncs.com

Parameter	Description	Example
IPv6	Indicates whether to use an IPv6 domain name to report device information: 0 (default): No (uses an IPv4 domain name) 1: Yes (uses an IPv6 domain name)	"1"
DataSwitch	Controls when to report device information: 0 (default): When the SDK initializes 1: When you obtain a token Note The default setting is recommended.	"1"
CustomUrl	Sets the server domain name for data reporting.	See CustomUrl for each region.
CustomHost	Sets the server host for data reporting.	"cloudauth-device.ap-southeast-1.aliyuncs.com" Note This example is for the Singapore region. For server hosts in other regions, see CustomUrl for each region.

Get metaInfo

- (NSString *)getMetaInfo;

Your server must obtain metaInfo from the client before calling the Initialize API.

The client retrieves metaInfo and sends it to your server, which then calls the Initialize API to obtain the TransactionId.

Start verification

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

Parameters

Parameter	Type	Description
certifyId	NSString	Obtained from the server-side InitializeV2 API.
viewController	UIViewController	The current `UIViewController`.
extParams	NSDictionary	Custom parameters. Pass `null` if not needed. For a list of supported parameters, see extParams configuration.
completeBlock	AliyunIdentityVerifyBlock	Callback that returns the verification result upon completion.

extParams configuration

Key	Description	Example (string)
kIdentityParamKeyNextButtonColor	Color of the bottom button on the OCR recognition result page.	#FF0000
kIdentityParamKeyRoundProgressColor	Color of the circular progress indicator during the face scan.	#FF0000
kIdentityParamKeyOcrSelectPhoto	Whether to show the photo album upload option during ID OCR recognition: 1 (default): Show 0: Do not show	1
kIdentityParamKeyShowOcrResult	Whether to show the recognition result page after ID OCR recognition: 1 (default): Show 0: Do not show	1
kIdentityParamKeyEditOcrResult	Whether the recognition result page is editable during ID OCR recognition: 1 (default): Editable 0: Not editable	1
kIdentityParamKeyMaxRetryCount	Maximum number of retries. Valid values: 3 to 10. Default value: 10.	10
kIdentityParamKeyCardOcrTimeOutPeriod	Timeout for OCR recognition, in seconds. Valid values: 20 to 60. Default value: 20.	20
kIdentityParamKeyFaceVerifyTimeOutPeriod	Timeout for liveness detection, in seconds. Valid values: 20 to 60. Default value: 20.	20
kIdentityParamKeyCardOcrEditTimeOutPeriod	Duration (in seconds) that the OCR recognition result page remains editable. Valid values: 60 to 180. By default, the duration is unlimited.	180
kIdentityParamKeyLanguage	SDK display language. By default, the SDK uses the system language. Note For a list of supported languages, see Customize languages for the Android and iOS SDKs.	zh-Hans
kIdentityParamKeyDefaultLanguage	Default SDK language. For valid values, refer to kIdentityParamKeyLanguage. The default value is en (English).	en
kIdentityParamKeyCloseButtonPosition	Position of the close button in the SDK UI: left (default) right	left
kIdentityParamKeyWatermark	Watermark text displayed after successful OCR recognition.	Test watermark text
kIdentityParamKeyProtocol	Pre-fetched SDK protocol content. Note Obtain the protocol from the server-side Initialize API and pass it here to reduce internal SDK API calls and improve startup performance.	968412EB*******...

Error codes

Error code	Billing status	Subcode	Description
1000	Yes	A1000_1	The user completed face verification with a suggested result of "Pass". This is for reference only. Call the server-side CheckResult API for the final result.
1001	Yes	A1001_1	The user completed face verification with a suggested result of "Fail". This is for reference only. Call the server-side CheckResult API for the final result and failure reason.
1002	No	A1002_1	The machine learning model failed to load.
		A1002_3	Failed to load the module.
		A1002_4	iOS version is earlier than 9.0.
		A1002_5	Network interface error.
1003	No	A1003_1	Initialize API call failed: empty response content.
		A1003_2	Initialize API call failed: invalid content format.
		A1003_3	Failed to parse the client-side initialization protocol.
		A1003_4	Initialize API call failed: content decryption error.
		A1003_5	Initialize API call failed.
		A1003_6	Initialize API call failed: empty OSS field in response.
		A1003_7	The context is empty.
1004	No	A1004_1	Front-facing camera error.
		A1004_2	Failed to open the camera.
		A1004_3	User denied camera permission.
1005	No	A1005_1	Network error during the Initialize API call.
1005	No	A1005_2	Network error during the authentication API call.
1006	No	A1006_1	User canceled the process.
1006	No	A1006_2	Process timed out after 15 minutes of inactivity.
1007	No	A1007_1	Invalid authentication ID.
1014	No	A1014_1	Maximum retries exceeded.
1017	No	A1017_1	Invalid product code.

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];
}

// You must implement this function to send the metaInfo to your server and retrieve a transaction ID.
- (NSString *)sentMetaInfoAndGetTransactionId:(NSString*) metaInfo {
    return @"Get the transaction ID from your server."; // TODO: Replace this with an actual call to your server.
}

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

    // Set the sdk language.
    NSDictionary *extParams = @{
        kIdentityParamKeyLanguage:@"en"
        kIdentityParamKeyProtocol:@"968412EB......................."// Configure this protocol to reduce 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

Component trimming

Trimmable	Module	Description	Size
Trimmable	AliyunIdentityNFC	Disables the NFC feature.	3.7M
Trimmable	OpenSSL	Required for the NFC feature.	3.7M
Trimmable	AliyunIdentityOcr	Disables the OCR feature and the eKYC authentication feature.	0.8M
Trimmable	faceguard	Protects the client-side authentication environment during face verification. Trimming this module reduces the effectiveness of security countermeasures.	0.74M
Trimmable	AliyunIdentityFace	Disables the face liveness feature.	2.2M
Not trimmable	AliyunIdentityPlatform	Core platform module.	0.04M
Not trimmable	AliyunIdentityUtils	Provides essential utility functions.	0.04M
Trimmable	MNN	Disables far/near liveness detection, face quality, and automatic OCR scanning.	0.09M
Not trimmable	AliyunOSSiOS	Provides object storage functionality.	0.23M