CallKit 使用指南
为方便开发者在 iOS 设备上实现 VoIP 功能，ZEGO 将 iOS CallKit 、PushKit 库的部分功能封装为了 zego-callkit-uts。本插件接口的接口风格、功能基本与 Apple CallKit、PushKit 保持一致，开发者可参考 Apple 开发者文档 CallKit 和 PushKit 相关介绍。
前提条件
- 已集成 ZPNs SDK 2.6.0 或以上版本 并实现离线推送，详情请参考 实现离线推送。
- 已向用户申请通知权限，并且用户同意 App 发送推送通知。
添加依赖
- 集成 SDK
以下两种方式可以任选一种导入。
2.导入 SDK。
import { CallKit } from '@/uni_modules/zego-callkit-uts';初始化
开发者需要在使用 VoIP 前，请先调用 setInitConfiguration 设置 VoIP 配置项。有关 Configuration 的内容，请参考 Apple 官网文档 CXProviderConfiguration。
CallKit.setInitConfiguration({ localizedName: "Your app name or others" });接收 VOIP 通知
当收到 VoIP 通知时，App 会拉起通话界面并触发 didReceiveIncomingPush。接口详情请参考 Apple 官方文档 didReceiveIncomingPushWithPayload。
CallKit.getInstance().onDidReceiveIncomingPush((extras: UTSJSONObjtect) => {
// 获取 UUID
const uuid = extras['uuid'];
});主动拉起 iOS CallKit 来电界面
当 iOS 端用户在线但 App 处于后台时，如果有别的用户发起呼叫，请先调用 setInitConfiguration 接口初始化 CallKit，然后即可调用 reportIncomingCall 接口，拉起来电界面，如下图所示。接口详情请参考 Apple 官方文档 reportNewIncomingCallWithUUID。
// 主动拉起 CallKit 前请先至少调用一次 setInitConfiguration
CallKit.setInitConfiguration({localizedName: 'ZEGO'});
// 创建 CXCallUpdate 对象
const cxCallUpdate = {
remoteHandle: /* 这里设置 CXHandle 对象 */,
localizedCallerName: "Caller Name", // 来电者名称
supportsHolding: true,
supportsGrouping: false,
supportsUngrouping: false,
supportsDTMF: true,
hasVideo: false
};
// 从 didReceiveIncomingPush 获取 UUID
const uuid = "your-unique-uuid-string";
// 调用 reportIncomingCall 方法
CallKit.getInstance().reportIncomingCall(cxCallUpdate, uuid)
.then(() => {
console.log("Incoming call reported successfully");
})
.catch(error => {
console.error("Error reporting incoming call: ", error);
});拉起通话界面后，如需接受邀请，实现真正的通话，请集成 Express SDK，详情请参考 实时音视频。
挂断 CallKit 通话界面
如需拒绝来电，请调用 reportCallEnded 接口。详情请参考 Apple 官网文档 reportCallWithUUID:endedAtDate。
// CXCallEndedReason 填入挂断的原因，示例代码此处的枚举代表对端挂断了电话
const reason = 4; // CXCallEndedReason.AnsweredElsewhere;
// 从 didReceiveIncomingPush 获取 UUID
const uuid = "your-unique-uuid-string";
CallKit.getInstance().reportCallEnded(reason, uuid);接收 Callkit 的事件回调
如果需要监听 CallKit 的事件回调，请在调用 ZPNs 的 registerPush 接口之前，传入各个回调函数的实现。回调详情请参考 Apple 官方文档 didReceiveIncomingPushWithPayload、performAnswerCallAction、performEndCallAction 和 performSetMutedCallAction。
const callkit = CallKit.getInstance();
// VoIP 通知到达的回调
callkit.onDidReceiveIncomingPush((extras: UTSJSONObjtect) => {
// uuid 为这次通话的唯一标识符
const uuid = extras['uuid'];
});
/**
* 如果需要调用 CallKit CXAction 的 fail() 方法 或 fulfill() 方法，需要调用 CallKit.performAction 方法。
*
* 第一个和第二个参数，固定写法：action.callUUID, action.method。
* 第三个参数传 boolean 值，true: 插件内部会调用 fulfill() 方法，false: 插件内部会调用 fail() 方法。
* CallKit.performAction(action.callUUID, action.method, true);
*
* function performAction(uuid: string, method: string, fulfill: boolean) {}
*/
// 用户点击接听按钮事件
callkit.onPerformAnswerCallAction((action: ICXAnswerCallAction) => {
console.log("handlePerformAnswerCallPush 用户点击接受", action);
// 接收成功，调用 action fulfill 函数
CallKit.performAction(action.callUUID, action.method, true); // 等同于 CXAnswerCallAction.fulfill();
});
// 用户点击挂断按钮事件
callkit.onPerformEndCallAction((action: ICXEndCallAction) => {
console.log("handlePerformEndCallAction 用户点击挂断", action);
// 挂断电话，调用 action fulfill 函数
CallKit.performAction(action.callUUID, action.method, true); // 等同于 CXEndCallAction.fulfill();
});
// 用户点击静音按钮事件
callkit.onPerformSetMutedCallAction((action: ICXSetMutedCallAction) => {
console.log("handlePerformSetMutedCallAction 用户点击静音", action);
// 静音按钮为打开时 muted 为 true
const isMuted = action.muted;
// 在这里添加处理静音逻辑
// 调用 action fulfill 函数
CallKit.performAction(action.callUUID, action.method, true); // 等同于 CXSetMutedCallAction.fulfill();
});设置 CallKit 为视频/音频模式
CallKit 默认为音频模式。此模式设置仅影响 UI 展示，实际的通话效果需要由您自行实现。
视频模式与音频模式的 UI 对比：
| 视频模式 | 音频模式 | |
|---|---|---|
| 来电通知 |  |  |
| 通话界面 |  |  |
开发者主动拉起 CallKit 时
调用 setInitConfiguration 接口初始化时，设置 supportsVideo 为 true。详情请参考 Apple 官方文档 supportsVideo。
调用 reportIncomingCall 接口拉起来电界面时，设置 hasVideo 为 true。如果您希望用户在接听来电后，点击用户界面上的“视频”按钮跳转到 App 上，还需要设置 remoteHandle。详情请参考 Apple 官方文档 hasVideo 和 remoteHandle
// 初始化时 supportsVideo 需要为 true
const config = {
localizedName: 'localizedName',
supportsVideo: true // 设置 supportsVideo 为 true
};
CallKit.setInitConfiguration(config);
// CXCallUpdate hasVideo 需要为 true
const update = {
hasVideo: true, // 设置 hasVideo 为 true
// 如果希望通话界面的“视频”按钮点击可以跳转到您的 App，需要设置 remoteHandle
remoteHandle: {
type: 1, // CXHandleType.Generic, 这里根据实际情况设置合适的类型
value: '呼叫方的联系人信息' // 设置呼叫方的联系人信息
}
};
// 生成本次通话的唯一 id,uuid 版本为 v4
const uuid = "",
// 调用 reportIncomingCall 方法
CallKit.getInstance().reportIncomingCall(update, uuid);SDK 主动拉起 CallKit 时
在发起 VoIP 时，发起端需要设置 iOSVoIPHasVideo 为 true，接收端 SDK 将根据此参数自动将 CallKit 设置为视频模式。
// 设置 pushConfig
const pushConfig = {
title: "系统通话标题", // 设置系统通话的标题
payload: "业务需要的透传字段", // 设置业务透传的字段
resourcesID: "联系 ZEGO 技术支持配置的 resourcesID", // 设置 resource ID，需联系 ZEGO 技术支持配置
// 配置 VoIP 设置
voIPConfig: {
iOSVoIPHandleType: 1, // ZIMCXHandleType.generic, 设置 iOS VoIP 的 Handle 类型为通用类型
iOSVoIPHandleValue: "Li hua", // 设置发送方联系人信息
iOSVoIPHasVideo: true, // 设置是否为视频通话
}
};