CallKit 使用指南

为方便 Flutter 开发者在 iOS 设备上实现 VoIP 功能，ZEGO 将 iOS CallKit 、PushKit 库的部分功能封装为了 zego_callkit。本插件接口的接口风格、功能基本与 Apple CallKit、PushKit 保持一致，开发者可参考 Apple 开发者文档 CallKit 和 PushKit 相关介绍。

前提条件

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。

• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

• 已集成 ZPNs SDK 2.6.0 或以上版本 并实现离线推送，详情请参考 实现离线推送。

• 已向用户申请通知权限，并且用户同意 App 发送推送通知。

• Xcode 工程已在 +Capability 中添加 Push Notifications。

  

添加依赖

您可以在 flutter 项目根目录中的 “pubspec.yaml” 文件添加依赖。

dependencies:
    # 请填写具体的 SDK 版本号
    # 请从 https://pub.dev/packages/zego_callkit 查询插件的最新版本，并将 x.y.z 修改为具体的版本号
    zego_callkit: ^x.y.z

初始化

开发者需要在使用 VoIP 前，请先调用 setInitConfiguration 设置 VoIP 配置项。

CallKit.setInitConfiguration(CXProviderConfiguration(localizedName: 'Your App Name or others'));   

接收 VOIP 通知

当收到 VoIP 通知时，App 会拉起通话界面并触发 didReceiveIncomingPush。

CallKitEventHandler.didReceiveIncomingPush = (Map extras ,UUID uuid){
    // 取出发送时携带的透传字段
    Map payload = extras['payload'];
};

主动拉起 iOS CallKit 来电界面

当 iOS 端用户在线但 App 处于后台时，如果有别的用户发起呼叫，请先调用 setInitConfiguration 接口初始化 CallKit，然后即可调用 reportIncomingCall 接口，拉起来电界面，如下图所示。

// 主动拉起 CallKit 前请先至少调用一次 setInitConfiguration
CallKit.setInitConfiguration(CXProviderConfiguration(localizedName: 'ZEGO'));

CallKit.getInstance().reportIncomingCall(CXCallUpdate(), UUID.getUUID()).catchError((onError){
// 主动拉起失败，请关注此处的报错
}).then((value) => {
// 拉起成功
});

拉起通话界面后，如需接受邀请，实现真正的通话，请集成 Express SDK，详情请参考 实时音视频。

挂断 CallKit 通话界面

如需拒绝来电，请调用 reportCallEnded 接口。

// CXCallEndedReason 填入挂断的原因，示例代码此处的枚举代表对端挂断了电话
// uuid 填入 didReceiveIncomingPush 获得的 uuid 或者 reportIncomingCall 传入的 uuid 对象。
CallKit.getInstance().reportCallEnded(CXCallEndedReason.CXCallEndedReasonRemoteEnded, uuid);

接收 Callkit 的事件回调

如果需要监听 CallKit 的事件回调，请在调用 ZPNs 的 registerPush 接口之前，传入各个回调函数的实现。

// VoIP 通知到达的回调。
// uuid 为这次通话的唯一标识符。
CallKitEventHandler.didReceiveIncomingPush = (Map extras, UUID uuid){
    // payload 与 ZIMPushConfig 携带的 extended data 内容一致。
    Map payload = extras['payload'];
};

// 用户点击接听按钮事件
CallKitEventHandler.performAnswerCallAction = (CXAnswerCallAction action){

};
// 用户点击挂断按钮事件
CallKitEventHandler.performEndCallAction = (CXEndCallAction action){

};
// 用户点击静音按钮事件
CallKitEventHandler.performSetMutedCallAction = (CXSetMutedCallAction action){
    // 静音按钮为打开时 muted 为 true
    action.muted;
};

设置 CallKit 为视频/音频模式

CallKit 默认为音频模式。此模式设置仅影响 UI 展示，实际的通话效果需要由您自行实现。

视频模式与音频模式的 UI 对比：

	视频模式	音频模式
来电通知
通话界面

开发者主动拉起 CallKit 时

调用 setInitConfiguration 接口初始化时，设置 supportsVideo_ 为 true。

调用 reportIncomingCall 接口拉起来电界面时，设置 hasVideo 为 true。如果您希望用户在接听来电后，点击用户界面上的“视频”按钮跳转到 App 上，还需要设置 remoteHandle。

// 初始化时 supportsVideo_ 需要为 true
var config = CXProviderConfiguration(localizedName: 'localizedName');
config.supportsVideo_ = true;
CallKit.setInitConfiguration(config);

// CXCallUpdate hasVideo 需要为 true
CXCallUpdate update = CXCallUpdate();
update.hasVideo = true;
// 如果希望通话界面的“视频”按钮点击可以跳转到您的 App，需要设置 remoteHandle
update.remoteHandle = CXHandle(type: CXHandleType.CXHandleTypeGeneric, value: '呼叫方的联系人信息');
//生成本次通话的唯一 id
UUID uuid = UUID.getUUID();
CallKit.getInstance().reportIncomingCall(update, uuid);

SDK 主动拉起 CallKit 时

在发起 VoIP 时，发起端需要设置 ZIMPushConfig > iOSVoIPHasVideo 为 true，接收端 SDK 将根据此参数自动将 CallKit 设置为视频模式。

pushConfig.title = "系统通话标题";
pushConfig.payload = "业务需要的透传字段";
pushConfig.resourcesID = "联系 ZEGO 技术支持配置的 resourcesID";

ZIMVoIPConfig voIPConfig = ZIMVoIPConfig();
voIPConfig.iOSVoIPHandleType = ZIMCXHandleType.generic;
//发送方联系人信息
voIPConfig.iOSVoIPHandleValue = "Li hua";
//是否为视频通话
voIPConfig.iOSVoIPHasVideo = true;
pushConfig.voIPConfig = voIPConfig;

处理用户点击 "视频" 按钮的事件回调

CallKit 为视频模式的通话界面如图所示。当用户点击视频按钮时，将会触发 - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler 回调。您可以在原生工程监听该方法，并处理该事件回调。

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler{
    INInteraction *interaction = userActivity.interaction;
    INIntent *intent = interaction.intent;
    // 用户点击视频按钮时，会满足以下判断条件，需要注意的是该条件不仅点击事件按钮时会被触发，在通讯录点击通话记录时也会触发。
    if([userActivity.activityType isEqual:@"INStartVideoCallIntent"]){
        INPerson *person = [(INStartAudioCallIntent *)intent contacts][0];
        // 在这里可以拿到 ZIMVoIPConfig 填入的 CXHandle，您可以根据这些信息来实现您的业务逻辑。
        CXHandle *handle = [[CXHandle alloc] initWithType:(CXHandleType)person.personHandle.type value:person.personHandle.value];
        // 以下为演示用的 UI，弹框展示了这些信息。
        UIAlertController *alertView = [UIAlertController alertControllerWithTitle:@"tips" message:[NSString stringWithFormat:@"用户活动类型为 INStartVideoCallIntent，切到视频,用户的用户信息为:%@",handle.value] preferredStyle:UIAlertControllerStyleAlert];
        UIAlertAction *action = [UIAlertAction actionWithTitle:@"OK" style:UIAlertActionStyleDefault handler:^(UIAlertAction * _Nonnull action) {
        }];
        [alertView addAction:action];
        [[UIViewControllerCJHelper findCurrentShowingViewController] presentViewController:alertView animated:YES completion:nil];
        return true;
    }
    return false;
}