常见问题

1. 初始化失败

若 CallKit 初始化返回 false，你可进行如下排查：

• 检查是否在主进程中初始化。
• 确保 Context 不为 null。
• 检查环信即时通讯 IM SDK 是否正确初始化。

2. 通话无声音

若通话过程中听不到声音，你可进行如下排查：

• 检查 RECORD_AUDIO 权限是否已授权。
• 检查设备音量设置。
• 确认麦克风未被其他应用占用。

3. 视频无画面

若频通话看不到画面，你可进行如下排查：

• 检查 CAMERA 权限是否已授权。
• 确认摄像头未被其他应用占用。
• 检查网络连接状况。

4. 锁屏无法显示来电

若锁屏状态下收不到来电通知，你可进行如下排查：

• 检查 USE_FULL_SCREEN_INTENT 权限。
• 确认通知权限已开启。
• 检查电池优化设置。

5. 悬浮窗无法显示

若通话时无法显示悬浮窗，你可进行如下排查：

• 检查 SYSTEM_ALERT_WINDOW 权限。
• 在设置中手动开启应用的悬浮窗权限。
• 部分厂商需要在应用管理中单独设置。

6. 群组通话连接失败

若群组通话无法正常连接，你可进行如下排查：

• 确认群组 ID 正确且用户已加入群组。
• 检查群组成员的授权权限，例如，麦克风和摄像头等权限。
• 确认网络连接稳定。

7. 群组通话人数限制

若界面提示 “人数超出最大限制16人”，你可进行如下排查：

• 确认群组通话人数。CallKit 限制群组通话最多 16 人参与（包括通话发起者）。若超过该限制，需要减少邀请的成员数量。
• 可以分批进行多次通话。

8. 权限被拒绝后通话自动结束

用户拒绝权限后通话自动结束，这是正常的业务逻辑，原因是：

• 麦克风权限是通话的基本要求，被拒绝后自动结束。
• 视频通话需要摄像头权限，被拒绝后会自动结束。

这种情况下，主叫方可自动发送取消信令并退出，被叫方可自动发送拒绝信令并退出。

9. 悬浮窗权限申请

悬浮窗权限申请失败或被拒绝，不影响通话功能，而且不会强制结束通话。

可以通过设置手动开启悬浮窗权限，例如，对于某些手机，可以选择 设置 -> 应用管理 -> 权限管理 -> 悬浮窗。

10. 前台服务和后台保活

应用在后台时通话质量下降或断开：

• CallKit 会自动启动前台服务保持通话状态。
• 前台服务会保持摄像头和麦克风权限。
• 建议将应用加入电池优化白名单。
• 检查厂商的后台运行策略设置。

11. 网络切换和断线重连

若 WiFi 和移动网络切换时通话中断，声网 RTC 具备自动重连机制，因此，短暂的网络波动会自动恢复。若长时间断网，会触发通话结束回调。

建议在网络稳定环境下进行通话。

12. 音频路由和蓝牙设备

若蓝牙耳机连接异常或音频路由错误，需检查是否已同意 BLUETOOTH_CONNECT 权限（Android 12+）。

CallKit 会自动处理音频路由切换，支持扬声器、听筒、蓝牙耳机之间的切换。

13. Telecom 系统集成问题

若锁屏状态下无法显示系统来电界面：

• 检查是否已申请 MANAGE_OWN_CALLS 等 Telecom 权限。
• 检查 VoIP 账户是否已注册和启用。
• 路径：以小米手机为例，点击电话拨号图标，点击右上角设置图标，选择 高级设置 > 通话账户设置，启用对应的 VoIP 账户。

14. VoIP 账户未启用

若提示 PhoneAccount 未注册或未启用：

• CallKit 在使用 Telecom 框架时会检查 VoIP 账户状态。
• 参考 DEMO 工程的 MainActivity#checkPhoneAccount函数实现，创建并启用 VoIP 账户。
• 通过 PhoneAccountHelper.getPhoneAccountStatus() 检查 VoIP 账户的状态。

15. 好友检查

默认情况下，环信 CallKit 支持陌生人之间进行通话，即无需添加好友即可通话。若在即时通讯 IM 控制台 开启了好友检查，会导致非好友不能通过 CallKit 进行一对一通话，群组音视频通话信令也会受影响（邀请使用群定向消息，其他信令均为单聊消息）。建议不开启好友检查，后续 SDK 迭代会优化。

16. 锁屏/应用在后台时通话页面显示

若要在设备锁屏或应用在后台时显示通话页面，需要手动申请权限(以小米手机为例)：

1. 锁屏时： 设置 → 应用设置 → 应用管理 → [你的应用] → 权限管理 → 其他权限 → 锁屏显示 → 允许。
2. 应用在后台时：设置 → 应用设置 → 应用管理 → [你的应用] → 权限管理 → 其他权限 → 后台弹出页面 → 允许。