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 allows for instant video communication between the customer and the customer representative using the back or front 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 Retry".

For processing retries to function, the other modules (NFC, Face, and OCR) must be implemented alongside the VideoCall Module.

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

atlassian-warning#FFEBE6

When intending to use the VideoCall module, the Core Module must be added to the project. This is necessary to provide the fundamental functionalities of the modules.

EnQualifyVideoCall SDK Integration Steps¶

This guide explains how to integrate the EnQualifyVideoCall SDK into your project. You can achieve quick and easy integration by following the steps below.

What is the Core Module¶

The Core Module must be included in the project before adding the VideoCall module. For information on how to add the Core module, you can visit the Core Module documentation.

What is EnQualifyVideoCall¶

EnQualifyVideoCall is used to carry out and manage video calls between the customer and the customer representative.

Quick Implementation¶

For rapid integration into your project, you can refer to the section How to Implement VideoCall Module?.

Adding VideoCall Module to the Project¶

EnQualify iOS SDK can be directly integrated into the project:

• Method: Add the SDK directly to the project by embedding xcframework and load the necessary 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, making it usable as a binary or shared framework in other projects. This is especially useful when creating XCFrameworks.

EXPANDED_CODE_SIGN_IDENTITY = "":¶

Clears the Code Signing Identity; ensuring 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 when signing is not needed.

CODE_SIGNING_ALLOWED = NO:¶

Ensures that code signing is completely disabled.

EXCLUDED_ARCHS[sdk=iphonesimulator*] = "":¶

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

VALID_ARCHS = "arm64 x86_64":¶

Specifies the 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 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 directly integrate the EnQualify SDK into your project, you can add the fundamental SDK files such as 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 add these frameworks by navigating to Project Settings > General and selecting Embed and Sign.
• 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 defined by the provider.

How to Implement VideoCall Module?¶

1. Adding the Modules¶

1.1 Implementation of 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 heading Adding VideoCall Module to the Project. Follow these steps to include the VideoCall module in your project.

2. Permissions¶

For detailed information, you can refer to the configuration settings section for the EnQualify SDK.

3. Adding EnQualifyVideoCallDelegate Interface¶

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

3.1 Adding EnQualifyVideoCallDelegate to the 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: String) {}

    func initializeCompleted(moduleName: String) {}

    func sessionCloseCompleted(status: String) {}

    func sessionCloseFailed() {}

    func sessionAddFailed() {}

    func settingGetFailed() {}

    func tokenCreateCompleted() {}

    func tokenCreateFailed() {}

    func integrationAddCompleted() {}

    func integrationAddFailed(errorMessage: String) {}

    func initializeFailed(with key: String) {}

    func sessionRoomFailed() {}

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

    func callResultFailed() {}

    func signingSetCompleted() {}

    func signingCompleted() {}

    func signingSetFailed(error: String) {}
}

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

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

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

Before initializing;

• The EnQualifyVideoCallDelegate methods should be added to the delegate field of the UIViewController where they will be used.
• SessionModelVideoCall is the model that contains the parameters to be used for starting the video call and should be added to the relevant area during initialization. For detailed information, please refer to the SessionModelVideoCall section.
• BaseModelVideoCall is the model that contains the certificate and base URL information necessary for the video call and should also be included in the relevant area during initialization. For detailed information, refer to the BaseModelVideoCall section.

Parameters¶

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

Once the EnQualifyVideoCall instance is created, the following steps are executed in order:

1. Token Creation

2. EnQualifyVideoCall initiates the token creation process.

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

func tokenCreateFailed() {}

• Once the token is successfully created, the process transitions to the next step, which is the session operation.

• Starting the Session Operation

• After successfully obtaining the token, the session initiation process begins.

• If an error occurs during 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 is ready to start the process.

• Retrieving Settings

• After the session is successfully created, the process of retrieving settings defined in the back office begins.

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

func settingGetFailed() {}

• Once the settings are successfully retrieved, the SDK makes the relevant configurations and starts the session operation.

• Completion of the Process

• 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 OCR operations.

func initializeCompleted(moduleName: String) {}

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

1. Process for Assigning Agent for Disabled Individuals

2. During the video call process, a special case created to indicate users who require privileges is aimed at assigning the customer to the relevant agent or prioritizing them, using the function setHandicappedStatus(hearing: Bool, visually: Bool). The hearing parameter represents individuals who are hearing impaired, while visually represents individuals who have visual impairments, and when any of these parameters are marked as true, a session update process occurs. If this update process fails, the sessionUpdateFailed() delegate method will be triggered on your side.

5. Starting the VideoCall Process¶

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

5.1 User Notification¶

Before the VideoCall process begins, it is recommended to notify the user. You can create a VideoCallInfo page for this purpose.
This page provides information about the VideoCall process to the user and enhances the experience.

5.2 VideoCall Operations¶

The basic functions and delegates of VideoCall are shared below.

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

5.3 Retry Flow of OCR and Face within VideoCall¶

When the Agent requests the OCR or Face verification steps to be repeated during the video call, the respective retry flows are initiated by the SDK.

Retry Scenario¶

• During the retry operation initiated by the Agent for OCR or Face, if the process falls into a Fail state,
• The user is offered the opportunity to voluntarily restart the verification process.

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

EnQualifyVideoCall.ocrRetry()

EnQualifyVideoCall.faceRetry()

Usage Rules¶

• These functions can only be called when in an active VideoCall session.
• They are not supported when called outside of 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 in the implementation side.

Starting the 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, the VideoCall process can safely restart the OCR and Face verification steps in a user-controlled manner without interruption.

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 as a small window on the screen when the application is sent to the background.

How to Use¶

• The PiP mode is activated at the user's request.
• The call can be followed through the PiP window; users can switch back to fullscreen at any time.

How to Set Up PiP?¶

If the required authorizations are not granted in the application when transitioning to PiP mode, the PiP window may appear as a gray/blank screen, and the user will not be able to view the agent's (Agent) image.

This situation is generally caused by the lack of necessary 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 follow:

1. Select Xcode → Target
2. Go to the Signing & Capabilities tab
3. Click on 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 obtained in the PiP window, and only a gray screen will be displayed.

Before calling the startVideoCall function, ensure that the initializeCompleted delegate has been triggered and that moduleName is EnQualifyVideoCall; otherwise, the necessary configuration information to provide the required connections will not be obtained, and the video call will not start.

All configuration information required to initiate the Video Call is provided by the back office; in cases where the calls do not reach the back office, the parameters should be checked, and it should be confirmed that the web and mobile addresses are directed to the same paths.

5.5 Flash Control within VideoCall¶

During the video call, the Agent may request the user to turn the device's flash on or off. This request is communicated to the application by the SDK via the agentRequest delegate method. The flash on/off operation is not performed directly; the related function is called only after obtaining the user's approval.

Flow¶

1. The Agent sends the request to turn the flash on or off through the back office.
2. The SDK triggers the agentRequest delegate method, and the type of flash request is communicated via the event parameter.
3. A confirmation screen or notification is shown to the user on the application side.
4. When the user approves, the relevant flash function is called, and the operation is completed.

Receiving the Request via the Delegate¶

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

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

Flash Functions¶

After the user approves, the following functions are called:

Turn On Flash:

EnQualifyVideoCall.openTorch(isApproved: Bool)

Turn Off Flash:

EnQualifyVideoCall.closeTorch(isApproved: Bool)

Models¶

BaseModelVideoCall¶

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

Model¶

class BaseModelVideoCall(
    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¶

Example Usage¶

In the following example, a BaseModelVideoCall object is created, defining the certificate information and 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..."],
    baseURL: "API_SERVER_URL",
    locale: "TR",
    mobileUser: "mobile",
    countryCode: "TUR"
)

Explanations¶

• Certificates (signallingCertificateList, mapiCertificateList): Certificate information is stored in file (.der) format.
• Base64 Certificates (signallingCertificateList, mapiCertificateBase64List): These are the versions of the certificates converted into Base64 text format.
• Server Connection (baseURL): The server URL at which the verification or certificate processes will be performed.

SessionModelVideoCall¶

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

Model Definition¶

class SessionModelVideoCall(
    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¶

Example Usage¶

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

var sessionModelVideoCall = SessionModelVideoCall(
    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 needs.
• Auto-Close: The canAutoClose can allow the session to close automatically when certain conditions are met.
• Continue Status: The isContinue checks whether the session is a continuing process.