iOS VoIP CallKit: A Developer's Guide to Integration

1import CallKit
2
3class CallManager {
4    let provider: CXProvider
5    private var calls: [UUID: YourCallObject] = [:] // Manage your internal call objects
6
7    init() {
8        let configuration = CXProviderConfiguration(localizedName: "Your App Name")
9
10        // Configure the provider (icons, ringtones, capabilities, etc.)
11        configuration.iconTemplateImage = UIImage(named: "AppIconTemplate")
12        configuration.supportsVideo = true // Set to true if your app supports video calls
13        configuration.maximumCallsPerCallGroup = 1 // Set to 1 for 1-on-1 calls, >1 for group calls
14        configuration.supportedHandleTypes = [.phoneNumber, .generic] // Or other relevant types
15
16        self.provider = CXProvider(configuration: configuration)
17        // Assign the delegate, typically a separate object or the call manager itself
18        self.provider.setDelegate(self, queue: nil) // Use main queue for delegate methods
19    }
20
21    // ... methods to manage calls and interact with the provider ...
22}
23
24// Make sure your CallManager (or another object) conforms to CXProviderDelegate
25extension CallManager: CXProviderDelegate {
26    // Delegate methods will be implemented here
27    // ...
28}
29

1// In your CallManager (or PushKit delegate)
2func reportIncomingCall(uuid: UUID, handle: String, callerName: String) {
3    let update = CXCallUpdate()
4    update.remoteHandle = CXHandle(type: .generic, value: handle)
5    update.localizedCallerName = callerName
6    update.hasVideo = false // Set to true if video call
7
8    provider.reportNewIncomingCall(with: uuid, update: update) { error in
9        if let error = error {
10            print("Failed to report incoming call: \(error.localizedDescription)")
11            // Handle error: e.g., inform the caller the call couldn't be presented
12        } else {
13            print("Successfully reported incoming call.")
14            // Store the call details internally, mapping uuid to your call object
15            // self.calls[uuid] = yourInternalCallObject
16        }
17    }
18}
19
20// In your CXProviderDelegate implementation
21func provider(_ provider: CXProvider, performAnswerCallAction action: CXAnswerCallAction) {
22    // Retrieve your internal call object using action.callUUID
23    guard let call = calls[action.callUUID] else {
24        action.fail()
25        return
26    }
27
28    // Perform the action using your VoIP SDK
29    // This involves starting the audio/video session and connecting to the remote peer
30    call.answer() // Your internal method to answer the call
31
32    // Inform CallKit the action was successfully performed
33    action.fulfill()
34}
35

1// In your app's UI code or a call initiation method
2func startOutgoingCall(handle: String, video: Bool) {
3    let handleType: CXHandle.HandleType = // Determine handle type (.generic, .phoneNumber, etc.)
4    let callHandle = CXHandle(type: handleType, value: handle)
5
6    let startCallAction = CXStartCallAction(call: UUID(), handle: callHandle)
7    startCallAction.isVideo = video
8
9    let transaction = CXTransaction(action: startCallAction)
10
11    let callController = CXCallController()
12    callController.request(transaction) { error in
13        if let error = error {
14            print("Failed to request start call action: \(error.localizedDescription)")
15            // Inform user the call failed
16        } else {
17            print("Requested start call action successfully.")
18            // CallKit will now call provider(_:performStartCallAction:) if successful
19        }
20    }
21}
22
23// In your CXProviderDelegate implementation
24func provider(_ provider: CXProvider, performStartCallAction action: CXStartCallAction) {
25    // Create your internal call object using action.callUUID, action.handle, action.isVideo
26    let newCall = YourCallObject(uuid: action.callUUID, handle: action.handle, isVideo: action.isVideo)
27    calls[action.callUUID] = newCall
28
29    // Perform the action using your VoIP SDK
30    // This involves initiating the connection to the remote peer
31    newCall.startConnect() // Your internal method to start connecting
32
33    // Inform CallKit the action was successfully performed (connection starts)
34    action.fulfill()
35
36    // Later, when your SDK reports the call is connecting, update CallKit:
37    // provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: Date())
38
39    // When your SDK reports the call is connected, update CallKit:
40    // provider.reportOutgoingCall(with: action.callUUID, connectedAt: Date())
41}
42

1// In your CXProviderDelegate implementation (example for answering)
2func provider(_ provider: CXProvider, performAnswerCallAction action: CXAnswerCallAction) {
3    guard let call = calls[action.callUUID] else {
4        action.fail()
5        return
6    }
7
8    // Attempt to answer the call with your SDK
9    call.answer { success in // Assuming your SDK's answer method has a completion handler
10        if success {
11            print("SDK successfully answered call: \(action.callUUID)")
12            // Inform CallKit the action was successful
13            action.fulfill()
14        } else {
15            print("SDK failed to answer call: \(action.callUUID)")
16            // Inform CallKit the action failed
17            action.fail()
18            // Optionally, clean up the call internally if it can't be recovered
19            self.calls.removeValue(forKey: action.callUUID)
20        }
21    }
22}
23

1graph TD
2    A[Remote Server] --> B(APNs);;
3    B --> C{User's iOS Device};;
4    C --> D(PushKit);
5    D --> E[Your App (PKPushRegistryDelegate)];;
6    E --> F[VoIP SDK (Receives Signaling)];;
7    E --> G[CallKit (CXProvider)];;
8    F --> G;
9    G --> H[iOS Native Call UI];;
10    H --> I{User Interaction};
11    I --> G;
12    G --> E;
13    E --> F;
14    F --> H;
15
16    %% Descriptions
17    A-.->|Sends VoIP push token| B;
18    B-.->|Delivers VoIP push| C;
19    D-.->|Wakes/Launches app| E;
20    E-.->|Reports incoming call| G;
21    I-.->|Answer/End/Hold actions| G;
22    G-.->|Delegate methods called| E;
23    E-.->|Performs SDK actions| F;
24    F-.->|Updates state| G;
25    G-.->|Updates UI| H;
26