iOS - NFC Module¶

Introduction¶

The NFC Module has been developed for reading immutable information contained within identity cards and passports that comply with the ICAO 9303 standard. The process of reading information from the chip is initiated with 3 parameters that are necessary to ensure chip authentication. These parameters are provided in the appropriate format that will be specified later: the serial number of the identity, the expiration date of the identity, and the date of birth of the identity owner.

NFC Module: Identity Card and Passport Reading¶

The NFC module is used to read chip data located 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 start the operation. Based on the result of this function, a callback is triggered regarding the operation status.

Required Data:

To successfully read the chip data, the following information must be provided:

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

If these details are not provided, the NFC reading operation fails, and the data cannot be retrieved. A bacFailure code is returned via EnQualifyNFCDelegate.nfcFailed.

atlassian-warning#FFEBE6

When the NFC module is to be used, the Core Module must be added to the project. This is necessary to ensure the basic functionality of the modules.

EnQualifyNfc SDK Integration Steps to Project¶

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

What is the Core Module¶

Before adding the NFC module, the Core Module must be included in the project. You can visit the Core Module documentation to learn how to add the Core Module.

Quick Implementation¶

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

Adding the NFC Module to the Project¶

EnQualify iOS SDK can be integrated directly into the project:

• Method: Add the SDK by embedding the xcframework directly into the project and loading the required 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 Post-Installation Build Settings¶

BUILD_LIBRARY_FOR_DISTRIBUTION = YES:

Allows the framework to be 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; this ensures that no specific certificate is used during the build process.

CODE_SIGNING_REQUIRED = NO:

Disables code signing requirements during the build process. This is useful for testing or when signing is not required.

CODE_SIGNING_ALLOWED = NO:

Ensures that code signing is completely disabled.

EXCLUDED_ARCHS[sdk=iphonesimulator*] = "":

Removes all excluded architectures for the iPhone simulator. This setting ensures 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 supported iOS version for the application or framework. This ensures compatibility with devices running iOS 14.0 and above.

ONLY_ACTIVE_ARCH = YES:

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

XCFrameworks

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

iOS - VideoCall Module

How to Implement the NFC Module?¶

This guide offers the necessary steps to include the EnQualifyNFC SDK in the project and easily integrate NFC operations. By following the instructions below, you can quickly implement the integration.

1. Adding Modules¶

1.1 Implementing the Core Module

The Core Module must be included in the project before utilizing the EnQualifyNFC Module. If you have not added it yet, you can refer to the Core Module documentation for details.

1.2 Implementing the NFC Module

You can find the necessary instructions for adding the NFC Module under the Adding the NFC Module to the Project heading. Follow these steps to include the NFC module in your project.

2. Permissions¶

2.1 Adding NFC Usage Permission to Info.plist File¶

First, you need to add NFC permission to the Info.plist file. This allows your application to access the camera hardware.

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

2.2 Adding the ISO 7816 Standard to the Info.plist File¶

To read the contactless NFC chip, it is 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¶

The EnQualifyNFCDelegate includes the necessary delegate methods to manage NFC operations. By implementing this interface, you can listen for and manage NFC-related events. For detailed information, check the EnQualifyNFC User Guide.

3.1 Adding EnQualifyNFCDelegate to the Class¶

class ViewController: EnQualifyNFCDelegate {

3.2 Overriding Delegate Functions

class ViewController: EnQualifyNFCDelegate {
    func nfcStart(serialNumber: String, dateOfBirth: String, dateOfExpire: String) {}

    func nfcFailed(error: NFCModule.EnQualifyNFCError) {}

    func nfcCompleted() {}

    func initializeCompleted(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() {}

    func signingSetCompleted() {}

    func signingCompleted() {}

    func signingSetFailed(error: String) {}
}

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

Before initializing, core;

• EnQualifyNFCDelegate methods must be added to the delegate area of the UIViewController where it will be used.
• SessionModelNFC is the model containing the parameters to be used to start NFC, and this model must be added to the relevant field during the initialization process. For detailed information, check the SessionModelNFC section.
• BaseModelNFC is the model containing the certificate and basic URL information necessary for NFC, and this model must also be added to the relevant field during the initialization process. For detailed information, check the BaseModelNFC section.

Before starting the NFC operations, the EnQualifyNFC class must be initialized. This process initiates the required token, settings, and session operations. Furthermore, it is essential to inform the user that preparations for the NFC operation have been completed and then start the operation process.

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

Parameters¶

After initializing EnQualifyNFC, an EnQualifyNFC instance is created, and then necessary processes 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 sequentially:

1. Token Creation

2. EnQualifyNFC starts 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 moves to the session process.

• Starting the Session Process

• After the token has been successfully obtained, the session initiation process is initiated.

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

func sessionAddFailed() {}

• When the session process is successfully completed, the SDK connects with the back office and is ready to start the operation.

• Retrieving Settings

• After the session is successfully created, the process to retrieve the settings defined by the back office begins.

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

func settingGetFailed() {}

• When the settings are successfully retrieved, the SDK makes the relevant configurations and initiates the session process.

• Operation Completion

• When all steps are completed without any 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 smoothly. Any potential errors are communicated to the client or user via 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 Notification¶

It is suggested to inform the user before starting the NFC operation. For this, an NFCInfo page can be created.
This page provides information to the user about the NFC operation and ensures a better experience.

4.2. NFC Operations¶

For detailed information on NFC functions and delegates, you can check the EnQualifyNFC User Guide.

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

4.2.1. Reading Chip¶

To start the chip reading process, the nfcStart function is used. 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 process is successfully completed, the data read is sent to the back office, and the nfcCompleted() delegate is triggered.

func nfcCompleted() {}

4.2.2. Stopping Chip Reading¶

This allows for safely terminating a launched NFC session in certain transition scenarios.

EnQualifyNFC.nfcStopForBacktoVideoCall()

Usage Scenario

This function should be used when the following situation occurs:

1. During VideoCall, the Agent sends a NFC re-read (retry) request to the user.
2. The NFC operation is still ongoing while the BackToVideoCall process is triggered.

3. Control is performed through the agentRequest(event:lastEvent:) delegate

4. event == .BackToVideoCall

5. lastEvent == .NFC
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

The sessionClose function is used to close the session that SDKs use for communication with backend services. This process is managed by the EnQualifyCore API, but it is called as follows on the API side of each SDK.

atlassian-warning#FFEBE6

After a session is closed by an SDK, if it is to be reused, the SDK must be initialized again.

EnQualifyNFC.sessionClose(finished: false)

Delegate Mechanism

When the session closing process is successfully completed, the sessionCloseCompleted delegate is triggered. In this delegate, other operations to be executed after the process can be discussed.

func sessionCloseCompleted(status: String) {}

If the session closing process fails, the sessionCloseFailed delegate is triggered. This delegate can also handle other operations to be executed after the process.

func sessionCloseFailed() {}

Note:¶

To display the retrieved data on the results page, you can check the CustomerChip section. This section ensures that the data read is presented to the user in a clear and understandable way.

EnQualifyNFC User Guide¶

Functions¶

initialize(...) : EnQualifyNFC

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

To manage identity verification operations, EnQualifyNFC should be initialized. When initializing this API;

• sender: Any : Determines which class will handle the application’s delegate methods.
• sessionModel: SessionModelNFC : Contains session information to be used during NFC operations.
• baseModel: BaseModelNFC : Model carrying basic data needed during the validation process.

can be provided.

Since the API operates as a singleton, operations are performed through the same instance throughout the application session. This saves resources and increases operation consistency.
The initialization process automatically performs the following operations:

• 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 re-created, and the existing token is used.

tokenCreateFailed()

• Triggered if an error occurs while creating the token.

settingsGetFailed()

• Triggered if an error occurs while retrieving settings information.

sessionAddFailed()

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

sessionCloseCompleted(status: String)

• Triggered when the session is closed.

• Parameter:

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

sessionCloseFailed()

• Triggered if an error occurs while closing the session.

integrationAddCompleted()

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

integrationAddFailed()

• Triggered if an error occurs when a request is made 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"

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

• Triggered when an error occurs or a failure is encountered during chip reading operations.

• Parameters:

• errorMessage: Error message.

nfcCompleted()

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

Models¶

BaseModelNFC¶

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

Model¶

class BaseModelNFC(
    var signallingCertificateList: [String]? = nil
    var mapiCertificateList: [String]? = nil
    var signallingCertificateBase64List: [String]? = nil
    var mapiCertificateBase64List: [String]? = nil
    var baseURL: String //Mandatory field
    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..."],
    baseURL: "API_SERVER_URL",
    locale: "TR",
    mobileUser: "mobile",
    countryCode: "TUR"
)

Explanations¶

• Certificates (signallingCertificateList, mapiCertificateList): The names of the certificate files included within the application.
• Base64 Certificates (signallingCertificateBase64List, mapiCertificateBase64List): The forms of certificates converted to Base64 format.
• Server Connection (baseURL): The server URL where verification or certificate operations will be performed.

SessionModelNFC¶

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

Model Definition¶

class SessionModelNFC(
    var callType: String, // Mandatory field
    var userName: 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, // Mandatory field
    var canAutoClose: Bool = false, // Default: false
    var isContinue: Bool = false, // Default: false
    var category: String? = nil,
    var taxNumber: String? = nil,
    var businessReference: String? = nil,
    var handicapped: Bool? = false
)

Properties¶

Usage Example¶

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

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

Explanations¶

• Mandatory Fields: The callType and reference parameters must be specified.
• User Information: Fields such as userName, surname, phone, and 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 requirements.
• Automatic Closure: canAutoClose can allow the session to close automatically under certain conditions.
• Continue Status: isContinue checks if the session is an ongoing process.

CustomerChip¶

This class represents the data model in which the information read from the NFC chip on the user's identity or passport is stored. The relevant verification information obtained during the NFC reading process is also held 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? {}
}