iOS - NFC Module¶

Introduction¶

The NFC Module has been developed to read immutable information contained in identity cards and passports that comply with ICAO 9303 standards. The process of reading the information from the chip is initiated with 3 parameters necessary for chip authentication. These parameters are the serial number of the identity, the expiration date of the identity, and the date of birth of the identity holder provided in a specific format that will be defined later.

NFC Module: Reading Identity Cards and Passports¶

The NFC module is used to read the chip data found on identity cards or passports. The NFC reading process is carried out according to a specific structure within the SDK, and there is a function to initiate the process. A callback is triggered based on the result of this function to provide information about the status of the operation.

Required Data:

In order to successfully read chip data, the following information must be provided:

• Serial Number (A11A11111)
• Identity Expiration Date (YYMMDD)
• Date of Birth (YYMMDD)

If this information is not provided, the NFC reading operation will fail, and data cannot be retrieved. The bacFailure code will be returned through EnQualifyNFCDelegate.nfcFailed.

EnQualifyNfc SDK Integration Steps for the Project¶

This guide explains how to integrate EnQualifyNfc SDK into the project. By following the steps below, you can achieve the integration quickly and easily.

What is the Core Module¶

Before adding the NFC module, the Core Module must be included in the project. To learn how to add the core module, you can visit the Core Module document.

Quick Implementation¶

To achieve rapid integration in your project, you can refer to the section How to Implement the NFC Module?.

Adding the NFC Module to the Project¶

EnQualify iOS SDK can be integrated directly into the project:

• Method: Add the SDK directly to the project by embedding the xcframework and loading the necessary dependencies via cocoapods.

// target 'MySampleProject' do
  use_frameworks!
  pod 'OpenSSL-Universal','3.3.2000' # CoreModule
end

post_install do |installer|
   installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        config.build_settings['EXPANDED_CODE_SIGN_IDENTITY'] = ""
        config.build_settings['CODE_SIGNING_REQUIRED'] = "NO"
        config.build_settings['CODE_SIGNING_ALLOWED'] = "NO"
        config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = ""
        config.build_settings['VALID_ARCHS'] = "arm64 x86_64"
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings["ONLY_ACTIVE_ARCH"] = "YES"
    end
  end
end

Explanation of Build Settings After Installation¶

BUILD_LIBRARY_FOR_DISTRIBUTION = YES:

Ensures that the framework is built for distribution, so it can be used as a binary or shared framework in other projects. This is particularly useful when creating XCFrameworks.

EXPANDED_CODE_SIGN_IDENTITY = "":

Clears the Code Signing Identity to ensure that no specific certificate is used during the build process.

CODE_SIGNING_REQUIRED = NO:

Disables the code signing requirement during the build process. This is useful during testing or in cases where signing is not required.

CODE_SIGNING_ALLOWED = NO:

Ensures that code signing is completely disabled.

EXCLUDED_ARCHS[sdk=iphonesimulator*] = "":

Removes all previously excluded architectures for the iPhone simulator. This setting provides compatibility during the build process.

VALID_ARCHS = "arm64 x86_64":

Specifies valid architectures for the build. Here, arm64 (M Series) and x86_64 (for intel-based Macs) are used.

IPHONEOS_DEPLOYMENT_TARGET = 14.0:

Sets the minimum iOS version that the application or framework supports. This ensures compatibility with devices running iOS 14.0 and above.

ONLY_ACTIVE_ARCH = YES:

Limits the build process to only the architecture of the active build device or simulator. This can speed up the build time during development.

XCFrameworks

• To integrate the EnQualify SDK directly into your project, you can add the core SDK files, namely OCRModule.xcframework, NFCModule.xcframework, FaceModule.xcframework, CoreModule.xcframework, and VideoCallModule.xcframework, directly to your project files.
• Alternatively, if you have already copied the XCFrameworks into your project, you can go to Project Settings > General and select Embed and Sign to add these frameworks to your project.
• For the dependencies of the EnQualify SDK added this way, you need to include them in your project with the version numbers specified in the "podspec" file of the relevant version or defined by the provider.

iOS - VideoCall Module

How to Implement the NFC Module?¶

This guide provides the necessary steps to include the EnQualifyNFC SDK into your project and easily integrate NFC operations. By following the instructions below, you can quickly implement it.

1. Adding Modules¶

1.1 Implementing the Core Module

The EnQualifyNFC Module must be included in the project before it is used. If you have not added it yet, you can check the details in the Core Module documentation.

1.2 Implementing the NFC Module

You can find the necessary instructions to add the NFC Module in the title Adding the NFC Module to the Project. By following these steps, the NFC module should be included in the project.

2. Permissions¶

2.1 Adding NFC Usage Permission to .entitlements File¶

First, you need to add NFC permission to the .entitlements file. Only TAG should be used as the NFC format; NDEF is not required.

<key>NFCReaderUsageDescription</key>
<string>Our application requests NFC access to read NFC tags</string>
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

2.2 Adding ISO 7816 Standard to Info.plist File¶

To read the contactless NFC chip, it's necessary to add the relevant content and value containing the ISO 7816 Standard to the info.plist file.

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
    <array>
        <string>A0000002471001</string>
    </array>

3. Adding the EnQualifyNFCDelegate Interface¶

EnQualifyNFCDelegate contains the necessary delegate methods for managing NFC operations. By implementing this interface, you can listen to and manage events related to NFC. For detailed information, you can refer to the EnQualifyNFC User Guide section.

3.1 Adding EnQualifyNFCDelegate to the Class¶

class ViewController: EnQualifyNFCDelegate {

3.2 Overriding Delegate Functions

class ViewController: EnQualifyNFCDelegate {
    func nfcFailed(error: NFCModule.EnQualifyNFCError) {}

    func nfcCompleted() {}

    func initializeCompleted(moduleName: String) {}

    func deinitializeCompleted(moduleName: String) {}

    func initializeFailed(with key: CustomNSError) {}

    func sessionCloseCompleted(status: String) {}

    func sessionCloseFailed() {}

    func tokenCreateCompleted() {}

    func tokenCreateFailed() {}

    func integrationAddCompleted() {}

    func integrationAddFailed() {}

    func sessionAddFailed() {}

    func settingGetFailed() {}

3. Initializing EnQualifyNFC and Token, Settings, and Session Operations¶

Before starting NFC operations, the EnQualifyNFC class must be initialized. This process enables the initialization of the required token, settings, and session operations. Additionally, it is important to notify the user that preparations for the NFC operation are complete and then to start the operation process.

func initialize(_ sender: Any?,
                sessionModel: SessionModelNFC? = nil,
                baseModel: BaseModelNFC? = nil) {

Parameters¶

After EnQualifyNFC is initialized, an EnQualifyNFC instance is created, and then the necessary operations to create the token, settings, and session are initiated. After initialization, the token, settings, and session are managed by the SDK.

After the EnQualifyNFC instance is created, the following steps are carried out in sequence:

1. Token Creation

2. EnQualifyNFC initiates the token creation process.

3. If an error occurs during the token creation process, the tokenCreateFailed delegate is triggered.

func tokenCreateFailed() {}

• When the token is successfully created, the next step, which is the session operation, is initiated.

• Initiating the Session Operation

• After the token has been successfully received, the session initiation process begins.

• If an error occurs during session initiation, the sessionAddFailed delegate is triggered.

func sessionAddFailed() {}

• When the session operation is successfully completed, the SDK establishes a connection with the backoffice and becomes ready to start the operation.

• Retrieving Settings

• After the session is successfully created, the process of retrieving the settings defined on the backoffice is initiated.

• If an error occurs during this process, the settingsGetFailed delegate is triggered, and the error message is communicated to the client side.

func settingGetFailed() {}

• When the settings are successfully retrieved, the SDK performs the necessary configurations and initiates the session operation.

• Completing the Operation

• When all steps are completed without issues, the initializeCompleted delegate is triggered. This indicates that the SDK has been successfully initialized and is ready for NFC operations.

func initializeCompleted(moduleName: String) {}

This process is designed to ensure that EnQualifyNFC operates reliably. Possible errors are communicated to the client or user through the relevant delegates, facilitating necessary actions.

4. Starting the NFC Operation¶

In this section, we explain step by step how to start and manage NFC operations.

4.1. User Information¶

Before starting the NFC operation, it is recommended to provide information to the user. For this purpose, an NFCInfo page can be created.
This page provides information about the NFC operation to the user and ensures a better experience.

4.2. NFC Operations¶

You can find detailed information regarding NFC functions and delegates in the EnQualifyNFC User Guide.

• nfcStart(serialNumber: String, dateOfBirth: String, dateOfExpire: String)
• sessionClose(finished: Bool)

4.2.1. Performing the Chip Reading Operation¶

To start the chip reading process, use the nfcStart static function. nfcStart is not a delegate method included in EnQualifyNFCDelegate. This process is managed by the EnQualifyNFC API and is called as follows.

EnQualifyNFC.nfcStart(serialNumber: String, dateOfBirth: String, dateOfExpire: String)

Delegate Mechanism

When the chip reading operation is successfully completed, the read data is sent to the backoffice, and the nfcCompleted() delegate is triggered.

func nfcCompleted() {}

4.2.2. Stopping the Chip Reading Operation¶

Stops an ongoing NFC session securely in specific transition scenarios.

EnQualifyNFC.nfcStopForBacktoVideoCall()

Usage Scenario

This function should be used in the following situation:

1. During a VideoCall, the Agent sends a NFC retry request to the user.
2. The BackToVideoCall operation is triggered while the NFC operation is still ongoing.

3. A check is performed via the agentRequest(event:lastEvent:) delegate

4. event == .backToVideoCall

5. lastEvent == .nfcRetry
6. NFC is still active

In this case, to exit the NFC operation, the following should be called:

EnQualifyNFC.nfcStopForBacktoVideoCall()

4.2.3. Closing the SDK Session¶

Closing the Session Operation

To close the session used by the SDKs for communication with backend services, the sessionClose function is used. This operation is managed by the EnQualifyCore API, but each SDK's API calls it as follows.

EnQualifyNFC.sessionClose(finished: false)

Delegate Mechanism

When the session closing operation is successfully completed, the sessionCloseCompleted delegate is triggered. This delegate can handle other operations that need to be performed after the operation.

func sessionCloseCompleted(status: String) {}

If the session closing operation fails, the sessionCloseFailed delegate is triggered. This delegate can handle other operations that need to be performed after the operation.

func sessionCloseFailed() {}

Note:¶

To display the read data on the result page, refer to the CustomerChip section. This section ensures that the read data is presented to the user in a clear and understandable manner.

EnQualifyNFC User Guide¶

Functions¶

initialize(...) : EnQualifyNFC

func initialize(_ sender: Any?,
                sessionModel: SessionModelNFC? = nil,
                baseModel: BaseModelNFC? = nil) {

EnQualifyNFC must be initialized to manage identity recognition processes. This API, when initialized;

• sender: Any : Determines which class will handle the application's delegate methods.
• sessionModel: SessionModelNFC : Contains session information to be used during the NFC process.
• baseModel: BaseModelNFC : The model carrying the basic data during the verification process.

can be provided.

Since the API works in a singleton structure, operations are performed through the same instance throughout the application session. This saves resources and increases operational consistency.
The initialization process automatically performs the following actions:

• Token creation
• Settings configuration
• Session initiation
  If there is an existing session, a new session is not created, and the existing session continues to be used.

Delegates¶

Token / Session / Settings Delegates¶

tokenCreateCompleted()

• Triggered when the token creation process is completed.
• If there is an existing token, it is not recreated, and the existing token is used.

tokenCreateFailed()

• Triggered when an error occurs during token creation.

settingsGetFailed()

• Triggered when an error occurs while fetching settings information.

sessionAddFailed()

• Triggered when an error occurs while creating a new session.

sessionCloseCompleted(status: String)

• Triggered when a session is closed.

• Parameter:

• status : The status information of the session when it is closed.

sessionCloseFailed()

• Triggered when an error occurs while closing the session.

integrationAddCompleted()

• Triggered when the request made to the IntegrationAdd service is completed.

integrationAddFailed()

• Triggered when an error occurs while making a request to the IntegrationAdd service.

nfcFailed(error: EnQualifyNFCError)

public enum EnQualifyNFCError: String {
    case sessionTimeout = "The chip could not be read within the specified time."
    case idChipSaveError = "The ID information could not be saved"
    case userCancelled = "The user cancel"
    case failedToConnectToTag = "Failed connect to tag"
    case bacFailure = "Incorrect basic access data informaiton"
    case bundleFailure = "Failed to load NFCModule bundle"
    case masterListFailure = "Failed to locate masterList in bundle"
    case tagNotValid
    case invalidMRZKey
    case moreThanOneTagFound
    case unknownTagType
    case responseError
    case unknown
    case notSupported

    public var errorMessage: String {
        return self.rawValue
    }
}

• Triggered when an error occurs or fails during chip reading operations.

• Parameters:

• errorMessage: Error message.

nfcCompleted()

• Triggered when the chip is successfully read after calling the nfcStart function to start chip reading.

NFC Retry Mechanism¶

The retry mechanism for NFC is not only available in OCR and Face modules; it is also present in the NFC module.

The NFC re-reading flow is managed through the following components:

• EnQualifyVideoCall.nfcRetry(): Initiates a re-read request for the NFC process.
• nfcRetryRequested(): Ensures the relevant flow management when an NFC retry request is received.
• AgentRequestEvent.nfcRetry: Represents the NFC re-read request sent by the Agent.

Therefore, the NFC retry flow should be considered a supported mechanism separately for NFC in the documentation, in addition to OCR and Face flows.

Models¶

BaseModelNFC¶

BaseModelNFC is a data model that contains the certificate information and server connection address used in verification processes. Signaling and MAPI (Mobile-Application Programming Interface) certificates can be stored in both list (.der) format and Base64 string format.

Model¶

class BaseModelNFC(
    var signallingCertificateList: [String]? = nil
    var mapiCertificateList: [String]? = nil
    var signallingCertificateBase64List: [String]? = nil
    var mapiCertificateBase64List: [String]? = nil
    var signallingCertificatePublicKeyList: [String]? = nil
    var mapiCertificatePublicKeyList: [String]? = nil
    var baseURL: String? = nil
    var locale: String? = nil
    var mobileUser: String? = nil
    var countryCode: String? = nil
)

Properties¶

Usage Example¶

In the following example, a BaseModelNFC object is created to define the certificate information and server address:

var baseModelNFC = BaseModelNFC(
    signallingCertificateList: ["AI_CERT_1", "AI_CERT_2"],
    mapiCertificateList: ["MAPI_CERT_1", "MAPI_CERT_2"],
    signallingCertificateBase64List: ["QUlDRVJU...", "Q0VSVF8y..."],
    mapiCertificateBase64List: ["TU9SRSB...", "Q0VSVF8z..."],
    signallingCertificatePublicKeyList: ["SIGNALLING_PUBLIC_KEY_1", "SIGNALLING_PUBLIC_KEY_2"],
    mapiCertificatePublicKeyList: ["MAPI_PUBLIC_KEY_1", "MAPI_PUBLIC_KEY_2"],
    baseURL: "API_SERVER_URL",
    locale: "tr",
    mobileUser: "mobile",
    countryCode: "TUR"
)

Explanations¶

• Certificates (signallingCertificateList, mapiCertificateList): The names of the certificate files added to the application are provided.
• Base64 Certificates (signallingCertificateBase64List, mapiCertificateBase64List): The Base64 format versions of the certificates.
• Public Key Certificates (signallingCertificatePublicKeyList, mapiCertificatePublicKeyList): Public key values corresponding to the certificates used for Signaling and MAPI services are provided.
• Server Connection (baseURL): The server URL where verification or certification processes will be performed. It is of type String? and can be empty.

SessionModelNFC¶

SessionModelNFC is a data model that contains user and identity information during a call session. It includes call type, user details, identity information, and additional parameters related to the session.

Model Definition¶

class SessionModelNFC(
    var callType: String? = nil,
    var name: String? = nil,
    var surname: String? = nil,
    var phone: String? = nil,
    var email: String? = nil,
    var identityType: String? = nil,
    var identityNo: String? = nil,
    var reference: String? = nil,
    var canAutoClose: NSNumber?,
    var _continue: NSNumber?,
    var category: String? = nil,
    var taxNumber: String? = nil,
    var businessReference: String? = nil,
    var handicapped: NSNumber?
)

Features¶

Usage Example¶

In the following example, a SessionModelNFC object is created to define session information:

var sessionModelNFC = SessionModelNFC(
    callType: "NewCustomer",
    name: "Enqura",
    surname: "Information",
    phone: "+905551234567",
    email: "enqualifyplus@enqura.com",
    identityType: "National ID Card",
    identityNo: "12345678901",
    reference: "REF123456",
    canAutoClose: 1,
    _continue: 0,
    category: "category",
    taxNumber: "9876543210",
    businessReference: "COMPANY",
    handicapped: 1
)

Explanations¶

• Fields: The baseURL, callType, and reference parameters are of type String? and may be empty.
• User Information: Fields like name, surname, phone, email are optional.
• Identity Information: identityType and identityNo can be used in NFC verification or identity identification processes.
• Disability Status: The handicapped parameter indicates whether the user has special needs.
• Auto Close: canAutoClose may allow the session to close automatically when a certain condition occurs.
• Continue Status: _continue checks if the session is an ongoing process.

CustomerChip¶

This class represents the data model for storing data read from the user's NFC chip on their identity or passport. Relevant verification information obtained during the NFC reading process is also stored within this model.

Model¶

@objc public class CustomerChip: NSObject {
    @objc public static let shared = CustomerChip()

    @objc public func getName() -> String? {}

    @objc public func getSurname() -> String? {}

    @objc public func getIdentityNo() -> String? {}

    @objc public func getDocumentNo() -> String? {}

    @objc public func getBirthDate() -> String? {}

    @objc public func getNationality() -> String? {}

    @objc public func getExpireDate() -> String? {}

    @objc public func getGender() -> String? {}

    @objc public func getActiveAuth() -> AnyObject? {}

    @objc public func getPassiveAuth() -> AnyObject? {}

    @objc public func getImage() -> UIImage? {}

    @objc public func getDocumentType() -> String? {}
}