iOS - VideoCall Module¶

The VideoCall Module initiates real-time video calls between the end user and the authentication representative. Representative matching, waiting queue, retry flows, and Picture in Picture (PiP) mode are managed by this module.

Introduction¶

The VideoCall module enables instantaneous video communication between the customer and the customer representative using the front or back camera.

During the video call, if deemed necessary, the Customer Representative can repeat the analysis processes performed by the NFC, OCR, or Face modules under the name "Process Repetition."

The quality and speed of the video call can vary depending on the quality of the internet connection, the device's performance, and the camera quality.

Steps to Integrate EnQualifyVideoCall SDK into Project¶

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

What is the Core Module¶

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

What is EnQualifyVideoCall¶

EnQualifyVideoCall is used for conducting and managing video calls between the customer and the customer representative.

Quick Implementation¶

For a quick integration in your project, you can refer to the section How to Implement VideoCall Module?.

Adding the VideoCall 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 load the required dependencies via Cocoapods.

// target 'MySampleProject' do
  use_frameworks!
  pod 'GoogleWebRTC' # Video Call
  pod 'Socket.IO-Client-Swift' # Video Call
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 (binary) or shared framework in other projects. This is especially useful when creating XCFrameworks.

EXPANDED_CODE_SIGN_IDENTITY = "":¶

Clears the Code Signing Identity; thus, it ensures 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 architectures excluded 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 iOS version supported by the application or framework. This ensures compatibility with devices running iOS 14.0 and later.

ONLY_ACTIVE_ARCH = YES:¶

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

XCFrameworks¶

• To integrate the EnQualify SDK directly into your project, you can add the basic 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 and select the Embed and Sign option to add these frameworks to your project.
• For the dependencies of the EnQualify SDK added this way, you need to include the version numbers specified in the "podspec" file of the relevant version or as determined by the provider.

How to Implement the VideoCall Module?¶

1. Adding Modules¶

1.1 Implementing the Core Module¶

The Core Module must be included in the project before using the EnQualifyVideoCall Module. If you haven't added it yet, you can check the Core Module documentation for details.

1.2 Adding the VideoCall Module to the Project¶

You can find the necessary instructions for integrating the VideoCall Module under the title Adding the VideoCall Module to the Project. Follow these steps to include the VideoCall module in your project.

2. Permissions¶

For detailed information, you can check the section Configuration settings for EnQualify SDK.

3. Adding the EnQualifyVideoCallDelegate Interface¶

The EnQualifyVideoCallDelegate contains the necessary delegate methods to manage VideoCall operations. By implementing this interface, you can listen and manage events related to VideoCall.

3.1 Adding EnQualifyVideoCallDelegate to a Class **¶

class ViewController: EnQualifyVideoCallDelegate {

3.2 Overriding Delegate Functions¶

class ViewController: EnQualifyVideoCallDelegate {    
    func agentRequest(event: AgentRequestEvent, lastEvent: AgentRequestEvent) {}

    func ocrRetryRequested() {} 

    func faceRetryRequested() {} 

    func callStarted() {}

    func hangupConfirmation() {}

    func videoCallFailed(_ error: CallTimeoutTypes) {}

    func initializeCompleted(moduleName: String) {}

    func deinitializeCompleted() {}

    func sessionCloseCompleted(status: String) {}

    func sessionCloseFailed() {}

    func sessionAddFailed() {}

    func settingGetFailed() {}

    func tokenCreateCompleted() {}

    func tokenCreateFailed() {}

    func integrationAddCompleted() {}

    func integrationAddFailed() {}

    func initializeFailed(with key: String) {}

    func socketInitializeFailed() {}

    func cameraSetupFailed() {}

    func sessionRoomFailed() {}

    func sessionRoomComleted() {}

    func agentMessageRequest() {}

    func nfcRetryRequested() {}

    func callResultCompleted(result: String, description: String, reference: String) {}

    func callResultFailed() {}
}

4. Initializing EnQualifyVideoCall and Token, Settings, and Session Operations¶

Before starting VideoCall operations, the EnQualifyVideoCall class must be initialized. This action allows the necessary token, settings, and session operations to be initiated. Additionally, it is important to inform the user that preparations for the VideoCall operation are complete and then start the operation process.

func initialize(_ delegate: Any?,
                sessionModel: SessionModelVideoCall? = nil,
                baseModel: BaseModelVideoCall? = nil) {

Parameters¶

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

After the EnQualifyVideoCall instance is created, the following steps are performed in order:

1. Token Creation

2. EnQualifyVideoCall initiates the token creation process.

3. If an error occurs during the token creation process, the tokenCreateFailed delegate is triggered, and the error received is communicated to the client side.

func tokenCreateFailed() {}

• When the token is successfully created, the process moves to the next step which is the session operation.

• Starting the Session Operation

• After the token is successfully obtained, the session initiation process begins.

• If an error occurs during the session initiation, the sessionAddFailed delegate is triggered, and the error message is communicated to the user.

func sessionAddFailed() {}

• Once the session operation is successfully completed, the SDK establishes a connection with the back office and becomes ready to start the operation.

• Retrieving Settings

• After the session is successfully created, the process of obtaining the settings defined in the back office 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 makes the relevant configurations and starts the session operation.

• Completing the Operation

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

func initializeCompleted(moduleName: String) {}

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

1. Process of Assigning Agents Suitable for Disabled Individuals

2. During the video call process, the goal is to assign the related agent to customers or provide priority for users for whom allowances should be made, using the setHandicappedStatus(hearing: Bool, visually: Bool) function created for specifying their special conditions. The hearing parameter represents individuals with hearing disabilities, and the visually parameter represents individuals with visual disabilities, and when either of these parameters is marked as true, a session update process occurs. If this update fails, the sessionUpdateFailed() delegate method will be triggered on your side.

5. Starting the VideoCall Process¶

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

5.1 User Notification¶

Before starting the VideoCall process, it is recommended to inform the user. For this, a VideoCallInfo page can be created.
This page provides information about the VideoCall process to the user and enhances their experience.

5.2 VideoCall Operations¶

The basic functions and delegates of VideoCall are shared below.

• startVideoCall(in viewController: UIViewController)
• backToVideoCall()
• endVideoCall()
• sessionClose()
• deinitialize(deinitializeCore: Bool)

5.3 OCR and Face Retry Flow Within VideoCall¶

When the Agent requests to repeat OCR or Face verification steps during the video call process, the relevant retry flows are initiated by the SDK.

Retry Scenario¶

• If the process falls into a Fail state during the OCR or Face retry operations initiated by the Agent,
• The user is offered the opportunity to restart the verification process at their own request.

In this context, the following two new functions have been added to the SDK:

EnQualifyVideoCall.ocrRetry()

EnQualifyVideoCall.faceRetry()

Usage Rules¶

• These functions can only be called while having an active VideoCall session.
• They are not supported to be called outside of a VideoCall.

Delegate Flow¶

After the relevant retry function is called, the following delegate methods are triggered by the SDK:

ocrRetryRequested()
faceRetryRequested()

These delegates must be handled on the implementation side.

Starting Retry Operations¶

After the delegates are received, the relevant verification steps are restarted as follows:

OCR & Face Retry:

EnQualifyOCR.idDocTypeCheckStart(in: vc, isFront: true)
EnQualifyFace.faceDetect(in: vc)

With this structure, OCR and Face verification steps can be safely restarted in a user-controlled manner without interrupting the VideoCall process.

5.4 PiP Mode Within VideoCall¶

The video call module supports the PiP (Picture-in-Picture) feature.

What is PiP?¶

PiP is an iOS feature that allows the video call to continue on the screen as a small window when the application is sent to the background.

How to Use¶

• PiP mode is activated at the user's own request.
• The call video can be followed through the PiP window; the user can return to full screen whenever they wish.

How to Set Up PiP?¶

If the necessary permissions in the application are not granted when switching to PiP mode, the PiP window may appear as a gray/blank screen, and the user cannot view the agent's image.

This situation usually arises from not activating the required system permission for the PiP feature in the application.

Solution¶

The relevant PiP feature must be activated under the application's Signing & Capabilities settings.

Steps to be followed:

1. Select Xcode → Target
2. Enter the Signing & Capabilities tab
3. Click the + Capability button
4. Add Multitasking Camera Access.
5. Add Background Modes and;
6. Check Audio, AirPlay and Picture in Picture from the opened options.

If this setting is not activated, no image can be captured in the PiP window, and only a gray screen will be shown.

5.5 Flash Control Within VideoCall¶

During the video call, the Agent may request the user to turn the device flash on or off. This request is communicated to the application through the agentRequest delegate method by the SDK. The flash on/off operation is not performed directly; it is completed after obtaining user approval by calling the relevant function.

Flow¶

1. The Agent sends a flash on or off request through the back office.
2. The SDK triggers the agentRequest delegate method and communicates the type of flash request through the event parameter.
3. A confirmation screen or notification is displayed to the user on the application side.
4. When the user gives approval, the relevant flash function is called to complete the operation.

Receiving Request via Delegate¶

The flash request is captured through the existing agentRequest delegate method:

func agentRequest(event: AgentRequestEvent, lastEvent: AgentRequestEvent) {
    switch event {
    case .flashOpen:
        // Show flash on approval to the user
    case .flashClose:
        // Show flash off approval to the user
    default:
        break
    }
}

Flash Functions¶

After the user gives approval, the following functions are called:

Turn Flash On:

EnQualifyVideoCall.openTorch(isApproved: Bool)

Turn Flash Off:

EnQualifyVideoCall.closeTorch(isApproved: Bool)

Models¶

BaseModelVideoCall¶

BaseModelVideoCall is the data model that contains certificate information and server connection address used in verification processes. Signaling and MAPI (Mobile-Application Programming Interface) certificates are stored both in file (.der) format and in Base64 text format.

Model¶

class BaseModelVideoCall(
    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?
    var locale: String? = nil
    var mobileUser: String? = nil
    var countryCode: String? = nil
)

Properties¶

Usage Example¶

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

var baseModelVideoCall = BaseModelVideoCall(
    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): Certificate information is stored in the file (.der) format.
• Base64 Certificates (signallingCertificateList, mapiCertificateBase64List): The Base64 text formats of the certificates.
• Server Connection (baseURL): The server URL where authentication or certificate processes will be executed.

SessionModelVideoCall¶

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

Model Definition¶

class SessionModelVideoCall(
    var callType: String?,
    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?,
    var canAutoClose: NSNumber?,
    var _continue: NSNumber?,
    var category: String? = nil,
    var taxNumber: String? = nil,
    var businessReference: String? = nil,
    var handicapped: NSNumber?
)

Properties¶

Usage Example¶

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

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

Explanations¶

• Required Fields: The parameters callType and reference must be specified.
• User Information: Fields like name, surname, phone, email are optional.
• Identity Information: identityType and identityNo may be used in NFC verification or identity recognition processes.
• Disability Status: The handicapped parameter indicates whether the user has special needs.
• Auto Close: canAutoClose can enable the session to automatically close when a certain condition occurs.
• Continuation Status: _continue checks whether the session is an ongoing process.