Use ZEGO Call with your business server

---

The ZEGO Call implements the backend business logic with the real-time database and cloud functions of Firebase, while you can also build your own business server instead of using the Firebase. This document describes the logic of ZEGO Call's business server for you to refer to and build your own business server.

---

Introduction to different business logic

Method call logic

We encapsulate the method calls into different commands. Different commands receive different parameters and then execute the request through the unified execute method. The following describes the execution process:

1. The client calls the method of the SDK.
2. The SDK creates the corresponding command object and sets corresponding parameters.
3. The SDK calls the execute method of the command object.
4. The SDK calls the execute method of the class CommandManager.
5. The SDK calls the request method of FirebaseManager.

All method calls are ultimately executed through FirebaseManager's request method. The request takes three parameters:

• path: the request path.
• parameter: the request parameter.
• callback: the callback of request execution result.

Different methods have different path and parameter, and different logic is executed within the request based on different parameters.

Event callback logic

There are two ways for clients to know about data changes on the server. One is the client actively sends a request to the server for the latest data, which is the method call described above. The other is that the server keeps a long connection with the client, and the server actively sends data to the client.

The following describes the process:

1. The SDK calls ZegoListener's addListener method to set up and listen for an event callback.

2. ZegoListenerManager saves the callback that has been set up and listened for.

3. FirebaseManager receives data changes from the business server.

4. FirebaseManager calls the receiveUpdate method of ZegoListenerUpdater.

5. ZegoListenerManager gets the callback based on path.

6. The SDK receives the callback and processes the business logic.

Through the above-mentioned description, you can know that all active requests are implemented by the FirebaseManager, and all passive data modifications are also been listened for by the FirebaseManager. So you only need to replace the FirebaseManager with your own business logic if you want to use the ZEGO Call with your own business server.

Request protocol

The request protocol refers to the protocol by which the client calls the method of the server. It can be implemented using HTTP or by establishing a long-lived connection.

Make a call

path: /call/start_call

Sample request:

{
    "call_id" : "123",
    "caller": {
        "id": "xxx",
        "name": "name1"
    }
    "callees" : [
        {
            "id": "123",
            "name": "name"
        },
        {
            "id": "123",
            "name": "name"
        }
    ],
    "type" : 1
}

Request parameters:

Sample response:

{
    "code" : 0,
    "message" : ""
}

Response parameters:

Client logic:

Users need to call this method when making a call.

Server logic:

1. Add a call record based on the call_id and save user information about both parties.
2. Send a notification callback to the called user according to the information carried in the callees. For more details about the callback, see Callback notification: receive an incoming call.

Cancel a call

path: /call/cancel_call

Sample request:

{
    "id" : "123",
    "call_id" : "123",
    "callee_id": "123"
}

Request parameters:

Sample response:

{
    "code" : 0
    "message" : ""
}

Response parameters:

Client logic:

The client can call this method to cancel a call after making an outbound call.

Server logic:

The server sends a callback notification to the callee based on the callee_id indicating the call has been canceled. For more details about the callback, see Callback notification: the call has been canceled .

Accept a call

path: /call/accept_call

Sample request:

{
    "id" : "123",
    "call_id" : "123"
}

Request parameters:

Sample response:

{
    "code" : 0
    "message" : ""
}

Response parameters:

Client logic:

The client can call this method to accept a call when receiving an incoming call.

Server logic:

The server sends a callback notification to the caller based on the call_id indicating the call has been accepted. For more details about the callback, see Callback notification: the call has been accepted.

Decline a call

path: /call/decline_call

Sample request:

{
    "id" : "123",
    "caller_id" : "xxx",
    "call_id" : "123",
    "type" : 1
}

Request parameters:

Sample response:

{
    "code" : 0
    "message" : ""
}

Response parameters:

Client logic:

The client can call this method to decline a call when receiving an incoming call.

Server logic:

The server sends a callback notification to the caller based on the call_id indicating the call has been declined. For more details about the callback, see Callback notification: the call has been declined.

End a call

path: /call/end_call

Sample request:

{
    "id" : "123",
    "call_id" : "123"
}

Request parameters:

Sample response:

{
    "code" : 0
    "message" : ""
}

Response parameters:

Client logic:

Both the callee and caller can call this method to end a call.

Server logic:

The server sends a callback notification to the peer end based on the call_id indicating the call has ended. For more details about the callback, see Callback notification: the call has ended.

Heartbeat during a call

path: /call/heartbeat

Sample request:

{
    "id" : "123",
    "call_id" : "123"
}

Request parameters:

Sample response:

{
    "code" : 0
    "message" : ""
}

Response parameters:

Client logic:

After a call starts, both parties need to send a heartbeat message to the server at intervals. The default heartbeat interval is 20 seconds, and the default heartbeat timeout duration is 60 seconds.

Server logic:

1. The server needs to maintain the heartbeat of both parties.
2. The server periodically checks the heartbeat duration of both parties. If the heartbeat duration of either party exceeds 60 seconds, the call is terminated and the party whose heartbeat duration does not exceed 60 seconds is notified. For more details about the callback, see Callback notification: the call has timed out.

Callback protocol

Notification protocol refers to the protocol by which the server proactively sends notifications to the callback method of the client. The notification protocol requires a long-live connection between the client and the server.

Callback notification: receive an incoming call

Only the callee can receive this callback notification, which indicates the callee receives an incoming call.

path: /call/notify_call_invited

body:

{
    "call_id" : "123",
    "caller" : {
        "id": "123",
        "name": "name"
    },
    "callees" : [
        {
            "id": "123",
            "name": "name"
        },
        {
            "id": "123",
            "name": "name"
        }
    ],
    "type" : 1
}

Parameters:

Callback notification: the call has been canceled

Only the callee can receive this callback notification, which indicates the call has been canceled by the caller.

path: /call/notify_call_canceled

body:

{
    "call_id" : "123",
    "caller_id" : "123"
}

Parameters:

Callback notification: the call has been accepted

Only the caller can receive this callback notification, which indicates the call has been accepted by the callee.

path: /call/notify_call_accept

body:

{
    "callee_id" : "123",
    "call_id" : "123",
}

Parameters:

Callback notification: the call has been declined

Only the caller can receive this callback notification, which indicates the call has been declined by the callee.

path: /call/notify_call_decline

body:

{
    "callee_id" : "123",
    "call_id" : "123",
    "type" : 1
}

Parameters:

Callback notification: the call has ended

Both the callee and caller can receive this callback notification, which indicates the call has ended.

path: /call/notify_call_end

body:

{
    "id" : "123",
    "call_id" : "123"
}

Parameters:

Callback notification: the call has timed out

Receiving this callback notification means that the heartbeat of the peer side has timed out. In this case, you need to end the current call.

path:/call/notify_timeout

body:

{
    "call_id" : "123",
    "id" : "123"
}

Parameters:

Modify the client logic

The following describes how to modify the client logic to match the server methods.

1. Create a class RequestManager that conforms to the RequestProtocol protocol and implement the request method.
2. In the class CommandManager, replace the service property with the RequestManager.

class CommandManager {
    static let shared = CommandManager()

      // Replace the [service] with the [RequestManager].
    private var service: RequestProtocol = RequestManager()

    func execute(_ command: Command, callback: RequestCallback?) {
        service.request(command.path, parameter: command.parameter, callback: callback)
    }
}

3. RequestManager requires an instance object that conforms to the ListenerUpdater protocol for notifying the upper layer of data changes from the backend.

class RequestManager: NSObject {

    weak var listener: ListenerUpdater? = ListenerManager.shared

}

extension RequestManager: RequestProtocol {

    func request(_ path: String,
                 parameter: [String : AnyObject],
                 callback: RequestCallback?) {

    }
}

4. The following is a sample code of the sample request:

func request(_ path: String,
             parameter: [String : AnyObject],
             callback: RequestCallback?) {

    if !urlPaths.contains(path) {
        callback!(.failure(.paramInvalid))
        return
    }

    let urlPath = "/xxxx/" + path
    let url = URL(string: urlPath)
    var request = URLRequest(url: url!)
    request.httpBody = try! JSONSerialization.data(withJSONObject: parameter, options: .prettyPrinted)
    request.httpMethod = "POST"

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        if data != nil && error == nil {
            // to do


        } else {
            callback!(.failure(.networkError))
        }
    }
    task.resume()
}

5. The following is a sample code of the sample callback notification:

   // simulate receiving a call invitation from the server.
   func onReceiveCallInvited(_ jsonStr: String) {
   
    let jsonData = jsonStr.data(using: .utf8)
    let parameter = try! JSONSerialization.jsonObject(with: jsonData!, options: .mutableContainers) as! [String: Any]
   
    listener?.receiveUpdate("/call/notify_call_invited", parameter: parameter)
   }