Docs version: 1.1.4
Last updated: July 08, 2019
Xenchain SDK for iOS is SDK that allows the use of ID Scanning Features and Face Match capabilities into Android Applications. This version is an overhaul to existing Xenchain SDK for iOS Platform, featuring improvement of Performance and ease of integration in comparison to older version.
Jovial Tan (jovial.tan@xenchain.io)
| Version | Author | Date | Description |
|---|---|---|---|
| 1.1.0 | Jovial | 2019-05-17 |
|
| 1.1.1 | Jovial | 2019-06-10 |
|
| 1.1.2 | Jovial | 2019-06-18 |
|
| 1.1.3 | Jovial | 2019-06-19 |
|
| 1.1.4 | Jovial | 2019-07-08 |
|
| Feature List |
|---|
| • ID Card Reader |
| • ID Card Verification |
| • Passport NFC Verification (Coming Soon) |
| • Face Verification |
| • Video Recording for Face Verification (Coming Soon) |
Kindly note that the project requires the use of a real physical iOS Device in order for the SDK to compile and work properly. Otherwise, will result in either compilation error or no access to the camera.
Step 1: Download XenchainSDK.framework file. Please note that you are required to use Git LFS to download the Frameworks folder. Otherwise, manually download the XenchainSDK and Microblink files and replace them respectively as shown below. Failure to do so will results in App Crash during the InitSDK process.
Step 2: On your project import additional frameworks and libraries in the "Linked frameworks and libraries" section of your target settings
- libc++.tbd
- libz.tbd
- libiconv.tbd
- AudioToolbox.framework
- AVFoundation
- CoreMedia.framework
Step 2: Import the .framework file into your project
- Open the project navigator
- Drag the XenchainSDK.framework to your project Framework group folder
- Drag the MicroBlink.framework to your project Framework group folder
- In your target settings, add XenchainSDK.framework and MicroBlink.framework into "Embedded Binaries" section. If any, remove any duplicates of XenchainSDK.framework and MicroBlink.framework from the "Linked Frameworks and Libraries" section.
Please follow the red oval below to setup for the frameworks which is crucial for scanning ID cards.
Kindly add the below configuration setup to allow iOS to bypass the HTTPS checking for Xenchain URL. In addition, please setup Privacy – Camera Usage Description and Privacy – Photo Library Usage Description. Please note that the contents of these Privacy can be anything. Finally, the key for apiurl must be replaced and will be provided by Xenchain.
<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>apiurl</key>
<dict>
<key>NSExceptionAllowsInsecureHTTPLoads</key>
<true/>
<key>NSIncludesSubdomains</key>
<true/>
</dict>
</dict>
</dict>
<key>NSCameraUsageDescription</key>
<string>Capture Face Image of the User for Face Match Feature</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Upload Image of the User for App Features</string>
Kindly add the script configuration below to remove all the Device Architecture from the Framework as shown in the image above. Please add the script on the very last of the Build Phase. Failure to do so might result in rejection when upload to the Apple Store.
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r
FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
EXTRACTED_ARCHS=()
for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
done// For Swift Implementation
import XenchainSDK;// For Objective-C Implementation
#import <XenchainSDK/XenchainSDK.h>;Please ensure that you execute the below code first before proceeding to other features of the SDK.
// For Swift Implementation
XenchainSDK.initSDK("SampleAPIKey", apiURL: "SampleAPIURL", onPremSaveData: false, completionHandler: XenchainSDKCallback)// For Objective-C Implementation
[XenchainSDK InitSDK:@"SampleAPIKey" apiURL:@"SampleAPIURL" onPremSaveData:false completionHandler:XenchainSDKCallback];| Parameter | Description |
|---|---|
| apiKey | API Key for activating SDK Features. |
| apiURL | URL Server Address which can be configured to point another server should client request private server. The value of this parameter will need to be requested from Xenchain Admin. |
| onPremSaveData | Determines whether the data returned from SDK will be saved into on-premise server. Only applicable if the client decided to host the backend server into client's own server. |
| completionHandler | Callback function for returning the results of initSDK function. Refer to |
// For Swift Implementation
func initSDKStatus(_ status: Bool, message: String!)// For Objective-C Implementation
- (void)InitSDKStatus:(bool)status message:(NSString *)message;Description:
Callback function that is used to determine the status of the Initialization of XenchainSDK
Parameters:
- status : Determines whether the SDK can be used or not.
- message : Contains the error message if the SDK cannot be initialized.
// For Swift Implementation
XenchainSDK.setScanningSound(Bundle(identifier: "com.example.reader")!.bundlePath + "/example_sound.mp3")// For Objective-C Implementation
XenchainSDK.scanningSound = [[NSBundle bundleWithIdentifier:@"com.example.reader"].bundlePath stringByAppendingString:@"/example_sound.mp3"]Kindly note that the input must be in String Path format.
// For Swift Implementation
XenchainSDK.setLoadingLogo(UIImage())// For Objective-C Implementation
XenchainSDK.loadingLogo = [[UIImage alloc] init];Kindly note the input must be in UIImage based format.
// For Swift Implementation
XenchainSDK.setLoadingView(UIView())// For Objective-C Implementation
XenchainSDK.loadingView = [[UIView alloc] init];Kindly note the input must be in UIView Data Type format.
Before proceed calling the deployScanner function, the app must have an Extended XScannerViewController class, in which the extended class will be used to Scan ID Card. The minimum implementation of the Extended XScannerViewController class is shown below.
/** Sample Swift Class of Extended XScannerViewController */
class CameraViewController: XScannerViewController {
override func viewDidLoad() {
super.viewDidLoad()
}
override func startScanHologram() {
print("Start Scan Hologram")
}
override func setHologramProgress(_ progress: Double) {
print("Hologram Progress")
}
override func hasScanHologram() {
print("Has Scan Hologram")
}
override func startScanFontSize() {
print("Start Scan Font Size")
}
override func hasScanFontSize() {
print("Has Scan Font Size")
}
override func startScanFront() {
print("Start Scan Front")
}
override func hasScanFront(_ frontImage: UIImage) {
print("Has Scan Front")
}
override func startScanBack() {
print("Start Scan Back")
}
override func hasScanBack(_ backImage: UIImage) {
print("Has Scan Back")
}
}/** Sample Objective-C Class of Extended XScannerViewController */
@interface CameraViewController : XScannerViewController
@end
@implementation CameraViewController
- (void)viewDidLoad {
[super viewDidLoad];
}
- (void)startScanHologram {
NSLog(@"Start Scan Hologram");
}
- (void)setHologramProgress:(double)progress {
NSLog(@"Hologram Progress");
}
- (void)hasScanHologram {
NSLog(@"Has Scan Hologram");
}
- (void)startScanFontSize {
NSLog(@"Start Scan Font Size");
}
- (void)hasScanFontSize {
NSLog(@"Has Scan Font Size");
}
- (void)startScanFront {
NSLog(@"Start Scan Front");
}
- (void)hasScanFront:(UIImage *)frontImage {
NSLog(@"Has Scan Front");
}
- (void)startScanBack() {
NSLog(@"Start Scan Back");
}
- (void)hasScanBack:(UIImage *)backImage {
NSLog(@"Has Scan Back");
}
@end// For Swift Implementation
XenchainSDK.deployScanner(scanConfig, inputController: self, extendedController: self.storyboard!.instantiateViewController(withIdentifier: "CameraViewController"), completionHandler: self)// For Objective-C Implementation
[XenchainSDK DeployScanner:scanConfig inputController:self extendedController:[self.storyboard instantiateViewControllerWithIdentifier:@"CameraViewController"] completionHandler:self];| Parameter | Description |
|---|---|
| scanConfig | Scan Configuration, which must be configured at App level, that determines the scanning behavior. Refer to Scanning Configuration for list of available configuration. |
| inputController | ViewController class that is used to call the scanner. |
| extendedController | The extended XScannerViewController class that is used as overlay for the Camera ViewController. |
| completionHandler | Callback function for ID Scanning. |
Kindly note that the below code is required to be executed after scanResults function being called. Otherwise, for each scanning, the SDK will charged the scan.
// For Swift Implementation
XenchainSDK.completeScanDeployment(onBoardingID, cardFrontReferenceID: mRefFrontImage, faceReferenceID: mRefFaceImage, cardBackReferenceID: mRefBackImage, cardResult: cardResult, completionHandler: self)// For Objective-C Implementation
[XenchainSDK CompleteScanDeployment:onBoardingID cardFrontReferenceID:mRefFrontImage faceReferenceID:mRefFaceImage cardBackReferenceID:mRefBackImage cardResult:cardResult completionHandler:self];| Parameter | Description |
|---|---|
| onBoardingID | The Overall Transaction ID for the whole Onboarding Process. |
| cardFrontReferenceID | The reference ID of the refFrontID from scanMetaResults function. |
| faceReferenceID | The reference ID of the refFace from scanMetaResults function. |
| cardBackReferenceID | The reference ID of the refBackID from scanMetaResults function. |
| completionHandler | Callback function for ID Scanning. |
// For Swift Implementation
func scanResults(_ cardResult: XCardResult!, onBoardingID: String!, errorMessage: String!)// For Objective-C Implementation
- (void)ScanResults:(XCardResult *)cardResult onBoardingID:(NSString *)onBoardingID errorMessage:(NSString *)errorMessage;Description:
Callback function that provides Scanning Results from ID Scanning Process
Parameters:
- cardResult : Result card info from the reader.
- onBoardingID : The Overal Transaction ID for the whole Onboarding Process.
- errorMessage : Error passed from processing ID Card result.
// For Swift Implementation
func scanMetaResults(_ idFaceImage: UIImage!, refFace: String!, idFrontImage: UIImage!, refFrontID: String!, idBack idBackImage: UIImage!, refBackID: String!, errorMessage: String!)// For Objective-C Implementation
- (void)ScanMetaResults:(UIImage *)idFaceImage refFace:(NSString *)refFace idFrontImage:(UIImage *)idFrontImage refFrontID:(NSString *)refFrontID idBackImage:(UIImage *)idBackImage refBackID:(NSString *)refBackID errorMessage:(NSString *)errorMessage;Description:
Callback function that provides Meta Scan Results from ID Scanning Process
Parameters:
- idFaceBitmap : Refers to Cropped Face Image from ID Card Image.
- refFace : The reference ID of the Cropped Face Image.
- idFrontBitmap : The ID Card Image from ID Scanner.
- refFrontID : The reference ID of the ID Card Image.
- idBackBitmap : The Back ID Card Image from ID Scanner.
- refBackID : The reference ID of the Back ID Card Image.
- errorMessage : Error passed from processing ID Card result.
// For Swift Implementation
func scanLandmarkInformation(_ landmarkScores: [AnyHashable : Any]!)// For Objective-C Implementation
- (void)ScanLandmarkInformation:(NSDictionary *)landmarkScores;Description:
Callback function that provides the Landmark Scores of the ID Cards. Used to determine the legitimacy of the ID Card.
Parameters:
- landmarkScores : The landmark scores for each field that is captured by the ID Scanner.
// For Swift Implementation
func scanServiceReferenceID(_ serviceReferenceID: String!, errorMessage: String!)// For Objective-C Implementation
- (void)ScanServiceReferenceID:(NSString *)serviceReferenceID errorMessage:(NSString *)errorMessage;Description:
Callback function that is called for each OCR Scanning.
Parameters:
- serviceReferenceID : Billing reference is returned if all the important attributes of the ID Card are returned successfully during the scanning process.
- errorMessage : Error passed from processing ID Card result.
// For Swift Implementation
func scanCompleteDeployment(_ status: Bool, errorMessage: String!)// For Objective-C Implementation
-(void) ScanCompleteDeployment:(bool)status errorMessage:(NSString *)errorMessage;Description:
Callback function that is called when the Scanning has been charged completely.
Parameters:
- status : Represents whether the
completeScanDeploymentis successfully called or not. - errorMessage : Error passed from processing
completeScanDeployment.
The behavior of scanning must be configured through the implementation of the class below. Each of the class represents each each countries that are supported by the SDK.
| Scan Config Class | Description |
|---|---|
| MyKadConfig | MyKad Scanning Configuration |
| PassportConfig | Passport Scanning Configuration |
Kindly note that depending on the type of ID Card being scanned and/or the information contained in the MRZ (Machine Readable Zone), each of the function represented below may be null/empty.
// For Swift Implementation
var mDocumentType: String
var mDocumentNumber: String
var mCardNumber: String
var mArmyNumber: String
var mBackDocumentNumber: String
var mFrontName: String
var mBackName: String
var mBloodType: String
var mAddress: String
var mVillage: String
var mRTRW: String
var mDistrict: String
var mCity: String
var mProvince: String
var mReligion: String
var mStatus: String
var mJob: String
var mGender: String
var mCitizenship: String
var mNationality: String
var mRace: String
var mPlaceOfBirth: String
var mDateOfBirth: String
var mCountryOfBirth: String
var mFrontDateIssued: String
var mBackDateIssued: String
var mDateUpdated: String
var mFrontExpiry: String
var mBackExpiry: String
var mChipNumber: String
var mSerialNumber: String
var mEmployerInfo: String
var mSector: String
var mEmploymentOccupation: String
var mDateOfApplication: String
var mForeignIdentificationNo: String
var mFacultyInfo: String
var mFacultyCityZipcodeState: String
var mFacultyAddress: String
func toString() -> String!// For Objective-C Implementation
@property (nonatomic, strong) NSString* mDocumentType;
@property (nonatomic, strong) NSString* mDocumentNumber;
@property (nonatomic, strong) NSString* mCardNumber;
@property (nonatomic, strong) NSString* mArmyNumber;
@property (nonatomic, strong) NSString* mBackDocumentNumber;
@property (nonatomic, strong) NSString* mFrontName;
@property (nonatomic, strong) NSString* mBackName;
@property (nonatomic, strong) NSString* mBloodType;
@property (nonatomic, strong) NSString* mAddress;
@property (nonatomic, strong) NSString* mVillage;
@property (nonatomic, strong) NSString* mRTRW;
@property (nonatomic, strong) NSString* mDistrict;
@property (nonatomic, strong) NSString* mCity;
@property (nonatomic, strong) NSString* mProvince;
@property (nonatomic, strong) NSString* mReligion;
@property (nonatomic, strong) NSString* mStatus;
@property (nonatomic, strong) NSString* mJob;
@property (nonatomic, strong) NSString* mGender;
@property (nonatomic, strong) NSString* mCitizenship;
@property (nonatomic, strong) NSString* mNationality;
@property (nonatomic, strong) NSString* mRace;
@property (nonatomic, strong) NSString* mPlaceOfBirth;
@property (nonatomic, strong) NSString* mDateOfBirth;
@property (nonatomic, strong) NSString* mCountryOfBirth;
@property (nonatomic, strong) NSString* mFrontDateIssued;
@property (nonatomic, strong) NSString* mBackDateIssued;
@property (nonatomic, strong) NSString* mDateUpdated;
@property (nonatomic, strong) NSString* mFrontExpiry;
@property (nonatomic, strong) NSString* mBackExpiry;
@property (nonatomic, strong) NSString* mChipNumber;
@property (nonatomic, strong) NSString* mSerialNumber;
@property (nonatomic, strong) NSString* mEmployerInfo;
@property (nonatomic, strong) NSString* mSector;
@property (nonatomic, strong) NSString* mEmploymentOccupation;
@property (nonatomic, strong) NSString* mDateOfApplication;
@property (nonatomic, strong) NSString* mForeignIdentificationNo;
@property (nonatomic, strong) NSString* mFacultyInfo;
@property (nonatomic, strong) NSString* mFacultyCityZipcodeState;
@property (nonatomic, strong) NSString* mFacultyAddress;
-(NSString *) toString;@property (nonatomic, strong) NSString* mDocumentType;Description:
Get document type from ID Card.
@property (nonatomic, strong) NSString* mDocumentNumber;Description: Get document ID Number from ID Card.
@property (nonatomic, strong) NSString* mCardNumber;Description: Get ID card Number for the Passport.
@property (nonatomic, strong) NSString* mArmyNumber;Description: Get Army Number from ID Card.
@property (nonatomic, strong) NSString* mBackDocumentNumber;Description: Get document ID Number from Back ID Card.
@property (nonatomic, strong) NSString* mFrontName;Description: Get Name from Front ID Card.
@property (nonatomic, strong) NSString* mBackName;Description: Get Name from Back ID Card.
@property (nonatomic, strong) NSString* mBloodType;Description: Get blood type from ID Card.
@property (nonatomic, strong) NSString* mAddress;Description: Get address from ID Card.
@property (nonatomic, strong) NSString* mVillage;Description: Get village from ID Card (Only in Indonesia eKTP).
@property (nonatomic, strong) NSString* mRTRW;Description: Get RT/RW from ID Card (Only in Indonesia eKTP).
@property (nonatomic, strong) NSString* mDistrict;Description: Get district from ID Card (Only in Indonesia eKTP).
@property (nonatomic, strong) NSString* mCity;Description: Get city from ID Card.
@property (nonatomic, strong) NSString* mProvince;Description: Get province from ID Card (Only in Indonesia eKTP).
@property (nonatomic, strong) NSString* mReligion;Description: Get religion status from ID Card.
@property (nonatomic, strong) NSString* mStatus;Description: Get marital status from ID Card.
@property (nonatomic, strong) NSString* mJob;Description: Get job from ID Card.
@property (nonatomic, strong) NSString* mGender;Description: Get gender from ID Card.
@property (nonatomic, strong) NSString* mCitizenship;Description: Get citizenship from ID Card.
@property (nonatomic, strong) NSString* mNationality;Description: Get nationality from ID Card.
@property (nonatomic, strong) NSString* mRace;Description: Get race from ID Card.
@property (nonatomic, strong) NSString* mPlaceOfBirth;Description: Get place of birth from ID Card.
@property (nonatomic, strong) NSString* mDateOfBirth;Description: Get date of birth from ID Card.
@property (nonatomic, strong) NSString* mCountryOfBirth;Description: Get country of birth from ID Card.
@property (nonatomic, strong) NSString* mFrontDateIssued;Description: Get date of issued from front ID Card.
@property (nonatomic, strong) NSString* mBackDateIssued;Description: Get date of issued from Back ID Card.
@property (nonatomic, strong) NSString* mDateUpdated;Description: Get date of updated from ID Card.
@property (nonatomic, strong) NSString* mFrontExpiry;Description: Get date of expiry from front ID Card.
@property (nonatomic, strong) NSString* mBackExpiry;Description: Get date of expiry from Back ID Card.
@property (nonatomic, strong) NSString* mChipNumber;Description: Get chip number from ID card.
@property (nonatomic, strong) NSString* mSerialNumber;Description: Get Serial Number from ID Card
@property (nonatomic, strong) NSString* mEmployerInfo;Description: Get Employer Info from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mSector;Description: Get Employer Sector from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mEmploymentOccupation;Description: Get Employment Occupation from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mDateOfApplication;Description: Get Date of Application from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mForeignIdentificationNo;Description: Get Foreign Identification No from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mFacultyInfo;Description: Get Faculty Information from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mFacultyCityZipcodeState;Description: Get Faculty City Zip Code State from ID Card (Only in Singapore PASS or Work Permit).
@property (nonatomic, strong) NSString* mFacultyAddress;Description: Get Faculty Address from ID Card (Only in Singapore PASS or Work Permit).
-(NSString *) toString;Description: Get JSON String format of this object.
Kindly note that ID Scan Feature must be implemented first and executed before proceed to Face Match Feature.
// For Swift Implementation
XenchainSDK.deployFaceMatch(se;f, onBoardingID: mOnBoardingID, imageRef: mRefFaceImage, completionHandler: self)// For Objective-C Implementation
[XenchainSDK DeployFaceMatch:self onBoardingID:mOnBoardingID imageRef:mRefFaceImage completionHandler:self];| Parameter | Description |
|---|---|
| onBoardingID | Refers to the particular OnBoarding Transaction ID. |
| imageRef | The reference ID of the refFace from scanMetaResults function. |
| completionHandler | Callback function for Face Match Scanning. |
// For Swift Implementation
func faceMatchResult(_ isMatched: Bool, percentMatched: Double, serviceReferenceID: String!, error: String!)// For Objective-C Implementation
- (void)FaceMatchResult:(bool)isMatched percentMatched:(double)percentMatched serviceReferenceID:(NSString *)serviceReferenceID error:(NSString *)error;Description:
Callback function that provides Face Match Results from Face Match Process
Parameters:
- isMatched : True for Matched Face. Otherwise, False.
- percentMatched : Percentage of Face Matching.
- serviceReferenceID : Refers to the Service Reference/Transaction ID for this process..
- error : Error passed from processing Face Match result.
// For Swift Implementation
func faceMatchMetaResult(_ outputImage: UIImage!, outputRef: String!)// For Objective-C Implementation
- (void)FaceMatchMetaResult:(UIImage *)outputImage outputRef:(NSString *)outputRef;Description:
Callback function that provides meta Face Match Results from Face Match Process
Parameters:
- outputBitmap : The Face Image captured during Face Match Process.
- outputRef : The reference ID of the image captured.
Please note that Xendity does not support nor encourage the use of other Mobile Application Framework, such as React Native, Angular JS (and its mobile support framework), Appcelerator, and so on, to implement this SDK. Should the Project Requirements requires the use of Mobile Application Framework to build the App, the developers are required to build their own wrapper or middleware (A type of interface to interact with this SDK) at their own risk. The support of this SDK will be limited to only for Native Android (Java/Kotlin) or iOS (Objective-C/Swift) language support only.