VoIP(Voice over IP)Push 是 Apple 提供的用于响应 VoIP calls 的通知机制。结合 Apple 提供的 PushKit.framework 和 CallKit.framework 能够实现系统级的通话效果。
由于 TIMPush 插件目前尚不支持 iOS 的 VoIP 通知,我们为您提供了一个免费的替代方案以帮助您在 iOS 设备上实现 VoIP 推送。
说明:
Apple 要求,VoIP Push 在 iOS 13.0 以后需要搭配 CallKit.framework 使用,否则 App 运行后会 crash。
VoIP Push 无法复用 APNs 普通推送证书,需要单独在苹果开发者网站上 申请 VoIP Push 证书。
集成效果
锁屏时的效果 | 应用在后台的效果 | 应用在后台展开的效果 |
![]() | ![]() | ![]() |
配置 VoIP Push
如果想要接收 VoIP Push,需要遵循如下几个步骤:
1. 申请 VoIP Push 证书。
2. 上传证书到 IM 控制台。
3. 完成工程配置。
4. 接入 TUICallKitVoIPExtension 组件。
步骤1:申请 VoIP Push 证书
在申请 VoIP Push 证书之前,请先登录 苹果开发者中心 网站,开启 App 的远程推送功能。当您的 AppID 具备了 Push Notification 能力后,按照如下步骤申请并配置 VoIP Push 证书:
1. 登录 苹果开发者中心 网站,单击 Certificates, IDs & Profiles 选项卡中的 Certificates,进入 Certificates, Identifiers & Profiles 页面。
![](https://qcloudimg.tencent-cloud.cn/image/document/e0c90991e733b4066c1451310d9840fc.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/e0c90991e733b4066c1451310d9840fc.png)
2. 单击 Certificates 右侧的+。
![](https://qcloudimg.tencent-cloud.cn/image/document/64b13d2f4268a753e3249fe48c0abe4c.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/64b13d2f4268a753e3249fe48c0abe4c.png)
3. 在 Create a New Certificate 选项卡中,选择 VoIP Services Certificate,并点击 Continue。
4. 在 Select an App ID for your VoIP Service Certificate 选项卡中,选择您当前的 App 的 BundleID,并点击 Continue。
5. 紧接着,系统提示我们需要一个 Certificate Signing Request(CSR)。
6. 我们接下来制作 CSR 文件。首先在 Mac 上打开钥匙串访问工具(Keychain Access),在菜单中选择钥匙串访问 > 证书助理 > 从证书颁发机构请求证书 (
Keychain Access - Certificate Assistant - Request a Certificate From a Certificate Authority
)。![](https://qcloudimg.tencent-cloud.cn/image/document/cedcd527de62c2976daa0d1421108d65.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/cedcd527de62c2976daa0d1421108d65.png)
7. 输入用户电子邮件地址(您的邮箱)、常用名称(您的名称或公司名),选择存储到磁盘,单击继续,系统将生成一个
*.certSigningRequest
文件。返回上述步骤5中 Apple Developer 网站刚才的页面,单击 Choose File 上传生成的
*.certSigningRequest
文件。![](https://qcloudimg.tencent-cloud.cn/image/document/7c9bf14d2329f71e75d60a32755df2d9.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/7c9bf14d2329f71e75d60a32755df2d9.png)
8. 单击 Continue 后生成证书,点击 Download 下载对应的证书到本地。
9. 双击打开刚才下载的
voip_services.cer
,系统会将其导入钥匙串中。10. 打开钥匙串应用,在 登录 > 我的证书,右键导出刚创建的 VoIP Services 的
P12
文件。说明:
保存
P12
文件时,请务必要为其设置密码。步骤2:上传证书到 IM 控制台
1. 选择您的 IM 应用,进入应用的基础配置页面,在离线推送证书配置选项卡中,点击立即前往。
![](https://qcloudimg.tencent-cloud.cn/image/document/20f6121ee36f01dfd25cdfaad33d9150.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/20f6121ee36f01dfd25cdfaad33d9150.png)
2. 在厂商配置中,切换到 iOS, 点击添加证书按钮,然后在悬浮页面中选择证书类型,上传 iOS 证书(p.12),设置证书密码,单击确认。
![](https://qcloudimg.tencent-cloud.cn/image/document/277595169cf4efa43e489db931e7c7f4.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/277595169cf4efa43e489db931e7c7f4.png)
说明:
添加证书时,推送类型默认为 APNS,不影响 VoIP 证书的上传和使用。
VoIP Push 证书本身不区分生产环境和测试环境,生产环境和开发环境使用的是同一份 VoIP Push 证书,请分别上传。
上传证书名最好使用全英文(尤其不能使用括号等特殊字符)。
上传证书需要设置密码,无密码收不到推送。
发布 App Store 的证书需要设置为生产环境,否则无法收到推送。
上传的 p12 证书必须是自己申请的真实有效的证书。
3. 上传完成后,记录不同环境下的证书 ID。
![](https://qcloudimg.tencent-cloud.cn/image/document/d8151e3e375c00a2d1fdba55f5de4d00.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/d8151e3e375c00a2d1fdba55f5de4d00.png)
说明:
步骤3:完成工程配置
1. 如下图,确认您工程的 Capability 中是否添加 Push Notification 能力。
![](https://qcloudimg.tencent-cloud.cn/image/document/db40bd6d9ecc93daf9bf85df38e9f85e.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/db40bd6d9ecc93daf9bf85df38e9f85e.png)
2. 如下图,请检查您工程 Capability 的 Backgrounds Modes 中,是否开启了 Voice over IP 选项。
![](https://qcloudimg.tencent-cloud.cn/image/document/45eb29297e52db089824e8a0ee3ad90c.png)
![](https://qcloudimg.tencent-cloud.cn/image/document/45eb29297e52db089824e8a0ee3ad90c.png)
步骤4:接入 TUICallKitVoIPExtension 组件
使用 CocoaPods 导入组件,具体步骤如下:
1. 在您的
Podfile
文件中添加以下依赖。pod 'TUICallKitVoIPExtension/Professional
'
注意:
请在您的
Podfile
文件中确保为TUICallKit_Swift
和TUICallKitVoIPExtension
组件指定相同的Subspec
。2. 执行以下命令,安装组件。
pod install
3. 上报 步骤 2:记录的证书 ID 。
import TUICallKitVoIPExtensionfunc application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {// 上报证书 IDTUICallKitVoIPExtension.setCertificateID(1234)return true}
#import <TUICallKitVoIPExtension/TUICallKitVoIPExtension.h>- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {// 上报证书 ID[TUICallKitVoIPExtension setCertificateID:1234];return YES;}
说明:
如果无法安装 TUICallKit 最新版本,执行以下命令更新本地的 CocoaPods 仓库列表。
pod repo update
拨打 VoIP 通话
如果您需要拨打 VoIP 通话,需要在调用 call 或者 groupCall 时候设置 OfflinePushInfo 中的 iOSPushType 字段为TUICallIOSOfflinePushTypeVoIP,默认为 TUICallIOSOfflinePushTypeAPNs。
import TUICallKit_Swiftimport TUICallEnginelet pushInfo: TUIOfflinePushInfo = TUIOfflinePushInfo()pushInfo.title = ""pushInfo.desc = "您有一个新的通话"pushInfo.iOSPushType = .voippushInfo.ignoreIOSBadge = falsepushInfo.iOSSound = "phone_ringing.mp3"pushInfo.androidSound = "phone_ringing"// OPPO必须设置ChannelID才可以收到推送消息,这个channelID需要和控制台一致// OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.pushInfo.androidOPPOChannelID = "tuikit"// FCM channel ID, you need change PrivateConstants.java and set "fcmPushChannelId"pushInfo.androidFCMChannelID = "fcm_push_channel"// VIVO message type: 0-push message, 1-System message(have a higher delivery rate)pushInfo.androidVIVOClassification = 1// HuaWei message type: https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835pushInfo.androidHuaWeiCategory = "IM"let params = TUICallParams()params.userData = "User Data"params.timeout = 30params.offlinePushInfo = pushInfo// 仅以单人通话举例、群通话类试TUICallKit.createInstance().call(userId: "123456", callMediaType: .audio, params: params) {} fail: { code, message in}
TUICallDefine.OfflinePushInfo offlinePushInfo = new TUICallDefine.OfflinePushInfo();offlinePushInfo.setTitle("");offlinePushInfo.setDesc("You have receive a new call");// OPPO必须设置ChannelID才可以收到推送消息,这个channelID需要和控制台一致// OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.offlinePushInfo.setAndroidOPPOChannelID("tuikit");offlinePushInfo.setIgnoreIOSBadge(false);offlinePushInfo.setIOSSound("phone_ringing.mp3");offlinePushInfo.setAndroidSound("phone_ringing"); //Note:don't add suffix//VIVO message type: 0-push message, 1-System message(have a higher delivery rate)offlinePushInfo.setAndroidVIVOClassification(1);//FCM channel ID, you need change PrivateConstants.java and set "fcmPushChannelId"offlinePushInfo.setAndroidFCMChannelID("fcm_push_channel");//Huawei message typeofflinePushInfo.setAndroidHuaWeiCategory("IM");//IOS push type: if you want user VoIP, please modify type to TUICallDefine.IOSOfflinePushType.VoIPofflinePushInfo.setIOSPushType(TUICallDefine.IOSOfflinePushType.VoIP);TUICallDefine.CallParams params = new TUICallDefine.CallParams();params.offlinePushInfo = offlinePushInfo;// 仅以单人通话举例、群通话类试TUICallKit.createInstance(context).call("mike", TUICallDefine.MediaType.Video, params, null);
TUIOfflinePushInfo offlinePushInfo = TUIOfflinePushInfo();offlinePushInfo.title = "Flutter TUICallKit";offlinePushInfo.desc = "This is an incoming call from Flutter TUICallkit";offlinePushInfo.ignoreIOSBadge = false;offlinePushInfo.iOSSound = "phone_ringing.mp3";offlinePushInfo.androidSound = "phone_ringing";offlinePushInfo.androidOPPOChannelID = "Flutter TUICallKit";offlinePushInfo.androidVIVOClassification = 1;offlinePushInfo.androidFCMChannelID = "fcm_push_channel";offlinePushInfo.androidHuaWeiCategory = "Flutter TUICallKit";offlinePushInfo.iOSPushType = TUICallIOSOfflinePushType.VoIP;TUICallParams params = TUICallParams(offlinePushInfo: offlinePushInfo);// 仅以单人通话举例、群通话类试TUICallKit.instance.call(callUserId, TUICallMediaType.audio, params);
#import <TUICallKit_Swift/TUICallKit_Swift-Swift.h>#import <TUICallEngine/TUICallEngine.h>- (TUICallParams *)getCallParams {TUIOfflinePushInfo *offlinePushInfo = [self createOfflinePushInfo];TUICallParams *callParams = [TUICallParams new];callParams.offlinePushInfo = offlinePushInfo;callParams.timeout = 30;return callParams;}- (TUIOfflinePushInfo *)createOfflinePushInfo {TUIOfflinePushInfo *pushInfo = [TUIOfflinePushInfo new];pushInfo.title = @"";pushInfo.desc = @"您有一个新的通话";pushInfo.iOSPushType = TUICallIOSOfflinePushTypeVoIP;pushInfo.ignoreIOSBadge = NO;pushInfo.iOSSound = @"phone_ringing.mp3";pushInfo.AndroidSound = @"phone_ringing";// OPPO必须设置ChannelID才可以收到推送消息,这个channelID需要和控制台一致// OPPO must set a ChannelID to receive push messages. This channelID needs to be the same as the console.pushInfo.AndroidOPPOChannelID = @"tuikit";// FCM channel ID, you need change PrivateConstants.java and set "fcmPushChannelId"pushInfo.AndroidFCMChannelID = @"fcm_push_channel";// VIVO message type: 0-push message, 1-System message(have a higher delivery rate)pushInfo.AndroidVIVOClassification = 1;// HuaWei message type: https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835pushInfo.AndroidHuaWeiCategory = @"IM";return pushInfo;}// 仅以单人通话举例、群通话类试[[TUICallKit createInstance] callWithUserId:@"123456"callMediaType:TUICallMediaTypeAudioparams:[self getCallParams] succ:^{} fail:^(int code, NSString * _Nullable errMsg) {}];
通过系统通话记录拨打通话
如果需要实现点击系统电话 - 最近通话列表中的通话记录,直接发起单人音视频通话,您需要在 Application 的生命周期回调函数使用 TUICallKitVoIPExtension 组件中的 callWith 接口,具体示例如下:
说明:
仅支持单人音视频通话的直接拨打。
登录账户必须为同一个账户。
1. 在 iOS 13(及以后版本)上,使用了 SceneDelegate,且最低兼容版本到iOS 13以下,需分别在 AppDelegate 和 SceneDelegate 中实现如下方法。
import TUICallKitVoIPExtension/// AppDelegate 中的实现,iOS 13 以前版本的处理func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) -> Void) -> Bool {TUICallKitVoIPExtension.call(with: userActivity)return true}/// SceneDelegate 中的实现func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {for userActivity in connectionOptions.userActivities {TUICallKitVoIPExtension.call(with: userActivity);}}func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {TUICallKitVoIPExtension.call(with: userActivity);}
#import <TUICallKitVoIPExtension/TUICallKitVoIPExtension.h>/// AppDelegate 中的实现,iOS 13 以前版本的处理- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {[TUICallKitVoIPExtension callWith:userActivity];return YES;}/// SceneDelegate 中的实现- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)sessionptions:(UISceneConnectionOptions *)connectionOptions {[connectionOptions.userActivities enumerateObjectsUsingBlock:^(NSUserActivity * _Nonnull userActivity, BOOL * _Nonnull stop) {[TUICallKitVoIPExtension callWith:userActivity];}];}- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {[TUICallKitVoIPExtension callWith:userActivity];}
2. 在 iOS 13(及以后版本)上,未使用SceneDelegate,只需要在 AppDelegate 实现如下方法。
import TUICallKitVoIPExtensionfunc application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([any UIUserActivityRestoring]?) -> Void) -> Bool {TUICallKitVoIPExtension.call(with: userActivity)return true}
#import <TUICallKitVoIPExtension/TUICallKitVoIPExtension.h>- (BOOL)application:(UIApplication *)application continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(nonnull void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {[TUICallKitVoIPExtension callWith:userActivity];return YES;}
常见问题
获取不到 VoIP Push,如何处理?
1. 首先检查下 App 的运行环境和证书的环境是否一致,证书 ID 是否匹配,如果不一致,无法收到推送。
2. 请确认当前您登录的账号是否处于离线状态:按 home 键切后台、登录后主动杀进程退出。VoIP Push 目前只支持离线状态下的推送。
3. 检查 步骤3:完成工程配置 是否正确。
4. 尝试重启测试手机来清除系统缓存和内存(很重要)。