Starting Video Help

Diyalog Platform offers live assistance to your customers through your mobile application with video calls.

You can download full simple video call ios project from SimpleVideoCall_IOS link.

Main Flow#

First of all, you need to know the flow about video call help in Diyalog platform for anonymous users. Anonymous user means you can connect logged in or not logged in user with your representatives.

The flow is like below :

Your app calls the DiyalogSDK startVideoCallWithAttachedDataInBackground method.
startVideoCallWithAttachedDataInBackground connects Diyalog Server and server will add your video call request to your representative queue then return to sdk about the result.
startVideoCallWithAttachedDataInBackground works asyncronously and result of the method call will return to your app in a callback method.
If inserting queue successfull then DiyalogSDK waits in background without showing any screen in your mobile app until a representative connecting . Therefore, you should show your wait screen thaht showing a representative will connect soon.
If any represenatative connecting, DiyalogSDK will automatically starts video call and come into foreground.
After you retrun succecsfull result from startVideoCallWithAttachedDataInBackground function, You can follow all stages of the video call by subscribing CallState in DiyalogSDK. So, you should subscribe to CallState by calling subscribeToCallStateWithTxCodeEvent in DiyalogSDK.

According to your business needs, a video call can be started at the relevant stage of your application as follows. When the following method is called, the DiyalogSDK in the background will transmit the call request to the call center over the server, and it will be waiting in the background until a representative from the call center initiates the call. During this process, the standby screen should be displayed in your mobile application. Customers who are tired of waiting should be allowed to cancel the transaction by adding a cancellation option to the waiting screen.

@objc open func startVideoCallWithAttachedDataInBackground(
                                            idNumber : Int64,
                                            customerId : String, 
                                            customerName : String = "", 
                                            phoneNumber : Int64 = 0, 
                                            txCode: String = "",  
                                            attachedData: [ACAttachedData], 
                                            result: @escaping (Bool, ACVideoCallError?) -> Void)

Parameters
idNumber (Long) National ID number of the customer.
customerId (String) Customer id number. This can be real of candidate customer id.
customerName (String) Opsiyoneldir. Name of the customer. This paramater is optional. It can be set empty.
customerPhone (Long) Opsiyoneldir. Phone number of the customer. This paramater is optional. It can be set 0.
txCode (String) This field is a parameter used only in the mobile client. The main application can distinguish the callState events of the its video calls in from other call. CallState events related to the conversation status are returned to the main application with this txcode parameter. It is in no way migrated to the server or agent application.
attachedData (ArrayList of AttachedData) Opsiyoneldir. With this parameter, you can send the data you want to the agent application. The Diyalog server transmits the data in the key-value array in this parameter to the Agent application. The data transmitted in this area is not stored on the Diyalog servers, only transmitted.
result (Bool, ACVideoCallError?) startVideoCallWithAttachedDataInBackground method is an asynchronous method and sends the result (information that the call request has been started) to your application with this callback method. If Bool value return true, the method successfull and means waiting in background to connect a repsresentative If Bool value return false, the method failed. And You can check failure reason from ACVideoCallError

You can use startVideoCallWithAttachedDataInBackground method as shown in below code. First of all, you need to create an ArrayList that takes the data you want to pass in AttachedData class.

var attachedData = [ACAttachedData]()
attachedData.append(ACAttachedData.init(nsString: "dataName1", with: "dataValue1"))
attachedData.append(ACAttachedData.init(nsString: "dataName2", with: "dataValue2"))
attachedData.append(ACAttachedData.init(nsString: "dataName3", with: "dataValue3"))
attachedData.append(ACAttachedData.init(nsString: "dataName4", with: "dataValue4"))

Then you need to pass this data in the attachedDataList parameter of the startVideoCallWithAttachedDataInBackground method.

@objc open func startVideoCallWithAttachedDataInBackground(
                                            idNumber : Int64,
                                            customerId : String, 
                                            customerName : String = "", 
                                            phoneNumber : Int64 = 0, 
                                            txCode: String = "",  
                                            attachedData: [ACAttachedData], 
                                            result: @escaping (Bool, ACVideoCallError?) -> Void)

If you get success as a result from the startVideoCallWithAttachedDataInBackground method, you need to subscribe to the event mechanism where you can follow the status of the call.

@objc open func subscribeToCallStateWithTxCodeEvent(listener: @escaping (_ state: String, _ txCode: String) -> Void)

CallStates that can receive from DiyalogSDK after subscribe as follows:

"RINGING" : Phone is calling
"CONNECTING" : Call accepted by both peers and Webrtc session is creating.
"IN_PROGRESS" : Call in progress
"ENDED" : Call ended.
"NO_CALL" : Initial state. No call active.

After call completed and your logic finished for video help, you should unsubscribe from CallState event bu using following method.aşağıdaki metod ile unsubscribe olabilirsiniz.

@objc open func unsubscribeToCallStateWithTxCodeEvent()

You can see complete code sample that you need to implement below. You should show wait screen after getting true from result callback. If you receive false, there is an error in the system and you should show error screen to customer.

var attachedData = [ACAttachedData]()
attachedData.append(ACAttachedData.init(nsString: "dataName1", with: "dataValue1"))
attachedData.append(ACAttachedData.init(nsString: "dataName2", with: "dataValue2"))
attachedData.append(ACAttachedData.init(nsString: "dataName3", with: "dataValue3"))
attachedData.append(ACAttachedData.init(nsString: "dataName4", with: "dataValue4"))

DiyalogEngine.diyalogInstance().startVideoCallWithAttachedDataInBackground(
    idNumber: Int64("<CUSTOMER_NATIONAL_ID_NUMBER") ?? 0, 
    customerId: "<CUSTOMER_NO>", 
    customerName: "<CUSTOMER_NAME>", 
    txCode : "<YOUR_TX_CODE>", 
    attachedData: attachedData, result: {(success, errorMessage) in
        if(success)
        {
            // SHOW YOUR WAIT RECRESENTATIVE SCREEN
            DiyalogEngine.diyalogInstance().subscribeToCallStateWithTxCodeEvent(listener: {(value : String?, txCode: String?) -> Void in
                if value != nil {
                    print("CALL STATE CHANGED TO " + value! + " FOR TxCode : " + txCode!)
                    if (value! == ("ENDED")){
                        // CALL FINISHED
                    }
                    else if (value! == "RINGING" || value! == "CONNECTING" || value! == "IN_PROGRESS"){
                        // CALL IN PROGRESS
                    }
                }
            })
            
        }else{
            print("there is an error. ErrCode : \(String(describing: errorMessage?.getCode())). Error Msg: \(String(describing: errorMessage?.getMsg()))")
        }
})

If startVideoCallWithAttachedDataInBackground method return successfull and you showed wait screen to customer and the customer press cancel button in your wait screen before agent start video call, you should call stopVideoCall method to stop process

@objc open func stopVideoCallForNewCustomer(customerId : String) -> Bool

Sample code

let result = DiyalogEngine.diyalogInstance().stopVideoCall(customerId: "<CUSTOMER_NO>")

After all process completed you can unsubscribe from the CallState event by calling

@objc open func unsubscribeToCallStateWithTxCodeEvent()

Sample code

DiyalogEngine.diyalogInstance().unsubscribeToCallStateWithTxCodeEvent()

Done :)

Picture In Picture Mode#

Diyalog SDK has feature picture in picture mode when video or voice call in progress. It is managed by other peer. It means, Diyalog App which is used by staff (agent) can send a manage call event to the mobile app in background and call view in mobile app automatically minimized over host application as picture in picture mode.

When mobile app call view is mininizing, Diyalog app that used by staff can send data (command) to mobile app in background. In this way, mobile host application can start any flow by checking the data/command for the customer during video/voice call.

The subscribeToManageCallEvent method is used to listen to these events. Each time a new event occurs, the callback function given to this method is called. Possible values are as follows :

"NO_EVENT" : Default and initial value of the event. This event should be ignored.
"CALL_MINIMIZED" : When this event comes, it means that the video call is minimized and the desired flow can be started. There can be additional data/command in the event.
"MESSAGE_RECEIVED" : When this event comes, it means that data has been transmitted from the other application to the mobile application.
"START_OPERATION" : When this event comes, it just means that the display is stopped while the voice call is in progress in the mobile client side and the main application on the mobile device can start any action flow. This event should be used in the mobile application if there will be a process where the camera will be used other than the video call. Because the operating systems of the devices do not allow camera access from different threads at the same time.

After subscription, "CALL_MINIMIZED" event should be waited and getManageCallEventData method should be used to read event data/command when this event comes up. You can redirect to the flow you want with the eventData you designed.

DiyalogEngine.diyalogInstance().subscribeToManageCallEvent(listener: {(manageCallEvent : String?) -> Void in
    if (manageCallEvent != nil && manageCallEvent == "CALL_MINIMIZED") {
        let events = DiyalogEngine.diyalogInstance().getManageCallEventData()
        for (key, value) in events {
            if (key == "command" && value == "getCardPassword"){
                // Do something
            }
        }
    }
})

When the call is ended or you don't want to listen to this event, you should unsubscribe your listener by calling unsubscribeToManageCallEvent method.

DiyalogEngine.diyalogInstance().unsubscribeToManageCallEvent()

Start Another Operation When Call In Progress#

While the video or audio call is in progress, your representative or employee can initiate the desired transaction on the phone of the customer. There may be a camera or hardware function in the process that can be started on customer's mobile device. For example, you can start an OCR process using the camera or facial recognition when call in progres. In this mode, customer camera will be stopped only voice call continue and other process can access the camera. This is the main point that separates this process from Picture In Picture mode.

An operation that uses a camera on the customer's phone can be performed with 3 different methods. You can design your implementaton that supports all or some of them. These methods are as follows:

The client view is stopped and an event is sent to the main application to perform the desired operation. In this method, the customer and the representative only hear each other's voice during the operation.
The call is minimized as picture in picture. During the operation, the customer sees and hears the voice and image of the representative in picInpic mode. The agent hears only the voice of the customer.
Customer phone screen shared with representative by screen casting method and representative can see customer phone's screen and direct customer with voice in real time. This screencast can only done by getting permission from the customer. Permission is getting by operating system automatically.

There will be no change for the mobile application in all 3 methods. As in Picture In picture mode, you should listen ManageCallEvent and when you receive START_OPERATION event, you can start any operation which describes in the details of the event. You can only focus on implementation of the operation, Diyalog SDK will manage camera stopping or screen castion or picInPic mode.

In other words, as in picture in picture mode, you can listen to manageCall events with the subscribeToManageCallEvent method and start any operation according to the type of operation you want with a control like below.

Below is sample code.

DiyalogEngine.diyalogInstance().subscribeToManageCallEvent(listener: {(manageCallEvent : String?) -> Void in
    if (manageCallEvent != nil && (manageCallEvent == "START_OPERATION") ) {
        let events = DiyalogEngine.diyalogInstance().getManageCallEventData()
        for (key, value) in events {
            if (key == "operationName" && value == "START_NFC"){
                print("NFC OPERATION WILL BE STARTED.")
                // Do NFC operation. UdentifyNFC is used to show how it is working in this sample code. You can use different libs
                let storyBoardNFC = UIStoryboard(name: "Udentify", bundle: nil)
                let nfc = storyBoardNFC.instantiateViewController(withIdentifier: "udentifyViewController") as!UdentifyViewController
                self.present(nfc, animated: true, completion: nil)
            }
            else if (key == "operationName" && value == "START_OCR"){
                print("MANAGECALLEVENT OCR OPERATION WILL BE STARTED.")
                // Do OCR operation
            }
            else if (key == "operationName" && value == "START_FACE_RECOGNITION"){
                print("MANAGECALLEVENT FACE RECOGNITION OPERATION WILL BE STARTED.")
                // Do Face Recognition operation
            }
            else if (key == "operationName" && value == "<OPERATION_YOU_DEFINED>"){
                print("MANAGECALLEVENT ANOTHER OPERATION WILL BE STARTED.")
                // Do what you need
            }

        }
    }

})

After your operation completed, you should call below method of the Diyalog SDK in order to turn back to video call. Of course, before calling this method, if the main application is performing an operation on the device's camera, the camera access must be closed and then the method must be called. Otherwise, the application may crash.

DiyalogEngine.diyalogInstance().turnBackToVideoCall()

Representative may also order turn back to call by remotely. SDK will notify the main application with diyalog.camerastartedincall string object. Again, the main application should dismiss views of the operation and close the camera access when this notification received. Therefore this notification should listen via NotificationCenter.

You can see how you can listen and act to it in below sample code.

NotificationCenter.default.addObserver(self,
                                      selector: #selector(cameraStartedInCall),
                                      name: NSNotification.Name ("diyalog.camerastartedincall"), 
                                      object: nil)

@objc func cameraStartedInCall(_ notification: Notification){
  // stop camera access and dismiss your view.
}      

Receiving Data From Remote Party In a Call#

Mobile app can receive any message or data from other party (agent or staff) during video/voice call in background. Staff or agent application can send any data/command/message to the mobile app during call in progress by means of DiyalogSDK.

This messages can be get by subscribing to manage call events.

The subscribeToManageCallEvent method is used to listen to these events. Each time a new event occurs, the callback function given to this method is called. Possible values are as follows :

"NO_EVENT" : Default and initial value of the event. This event should be ignored.
"CALL_MINIMIZED" : When this event comes, it means that the video call is minimized and the desired flow can be started. There can be additional data/command in the event.
"MESSAGE_RECEIVED" : When this event comes, it means that data has been transmitted from the other application to the mobile application.

After subscription, "MESSAGE_RECEIVED" event should be waited and getManageCallEventData method should be used to read event data/command when this event comes up. You can redirect to the flow you want with the eventData you designed.

DiyalogEngine.diyalogInstance().subscribeToManageCallEvent(listener: {(manageCallEvent : String?) -> Void in
    print("MANAGECALLEVENT received. event : \(manageCallEvent)")
    if (manageCallEvent != nil && (manageCallEvent == "MESSAGE_RECEIVED") ) {
        let events = DiyalogEngine.diyalogInstance().getManageCallEventData()
        for (key, value) in events {
            print("MANAGECALLEVENT key : \(key) value : \(value)")
            if (key == "command" && value == "getCardPassword"){
                // Do something
            }
        }
    }
})

Sending Data To Remote Party In a Call#

You can send any data from mobile app to remote staff or agent app by means of DiyalogSDK during call.

For doing this, you can call below method with eventData array.

@objc open func sendMessageToRemote(eventData : [ACEventData], result: @escaping (Bool, String) -> Void)

ACEventData stores keyName and keyValue strings. This data is transfered to remote by calling sendMessageToRemote method.

Sample usage :

var eventData = [ACEventData]()
eventData.append(ACEventData.init(nsString: "processName", with: "CustOnboarding"))
eventData.append(ACEventData.init(nsString: "processState", with: "customer_approve_by_pin"))

DiyalogEngine.diyalogInstance().sendMessageToRemote(
                      eventData: eventData, 
                      result: {(success, resMessage) in
        print("sendMessageToRemote finished. isSuccess: \(success), resMessage: \(resMessage)")
})

In this sample code remote peer (agent / staff app) will receive following json object. Sending a message to the remote peer is only possible during call.

{
      eventType: 'sendMessage',   
      manageCallEventData: [  
          {dataName: 'processName', dataValue: 'CustOnboarding'},  
          {dataName: 'processState', dataValue: 'customer_approve_by_pin'}  
      ]  
}  

Sample IOS project#

You can download full simple video call ios project from SimpleVideoCall_IOS link.