融云 CallKit SDK

融云 CallKit 是面向 HarmonyOS 的音视频通话 UI SDK，基于 CallLib 提供单人、多人音视频通话界面，包含呼叫、来电、接听和挂断等交互。

CallKit 依赖 IMKit、IMLib 和 CallLib，通话信令通过融云 IM 服务传输。开始通话前，需要完成 SDK 初始化并成功连接 IM 服务。

1. 环境要求

1.1. 开发环境

• DevEco Studio 5.0.3.906 及以上。
• HarmonyOS SDK API 12 及以上，兼容系统版本为 HarmonyOS 5.0.0(12)。
• 使用 HarmonyOS 真机验证音视频通话。真机运行前需配置签名证书，参考应用签名指南。

1.2. 准备工作

1. 在融云控制台创建应用，获取 App Key，并开通音视频通话服务。
2. 通过应用服务端为用户获取融云 Token。通话双方应使用同一应用、同一环境的 App Key，以及各自用户 ID 对应的 Token；开发环境与生产环境的数据相互隔离。

2. SDK 接入流程

2.1. 安装 SDK

由于 CallKit 依赖了 CallLib、IMLib 和 IMKit 的接口，请按导入 CallKit SDK中的说明，在模块的 oh-package.json5 中声明对应依赖，并执行 Sync Now 同步工程。

各 SDK 的版本号可能不同，请根据 OHPM 三方库中心或融云 SDK 下载页面选择兼容版本。

2.2. 配置权限

按官方接入文档在应用模块的 src/main/module.json5 中配置 requestPermissions：

权限名称	使用目的
ohos.permission.INTERNET	连接 IM 服务、传输通话信令与音视频数据
ohos.permission.GET_NETWORK_INFO	获取网络状态，处理网络变化和重连
ohos.permission.STORE_PERSISTENT_DATA	存储 IM 消息数据库
ohos.permission.MICROPHONE	采集音频
ohos.permission.CAMERA	采集视频
ohos.permission.KEEP_BACKGROUND_RUNNING	通话期间运行后台任务
ohos.permission.VIBRATE	来电振动提醒
ohos.permission.RUNNING_LOCK	音频通话时支持附耳熄屏

麦克风、摄像头权限需配置 reason 和 usedScene，其中 reason 引用的文案应在 src/main/resources/base/element/string.json 中定义，usedScene.abilities 应填写实际使用通话功能的 UIAbility 名称。配置示例及参数含义见声明权限。

权限声明不等于用户授权。CallKit 会在发起或接听通话时检查并申请所需权限；音频通话需要麦克风权限，视频通话还需要摄像头权限。

为支持通话期间的后台音频任务，还需在对应 UIAbility 的 backgroundModes 中配置 audioPlayback 和 audioRecording。

2.3. 加载并初始化 SDK

从 1.9.0 起，必须先调用 RCCall.install()，再初始化 IM。 同一 App Key 在应用生命周期中初始化一次即可。

初始化应在用户同意应用隐私政策后执行。以下示例假定已完成授权，将其合并到应用的 UIAbility 中；EntryAbility 和 pages/Index 应替换为实际的 Ability 名称与页面路径：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { IMEngine, InitOption } from '@rongcloud/imlib';
import { RCCall } from '@rongcloud/callkit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    RCCall.install();
    IMEngine.getInstance().init(this.context, '你的 App Key', new InitOption());
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    AppStorage.setOrCreate('windowStage', windowStage);
    windowStage.loadContent('pages/Index');
  }
}

2.4. 配置通话监听与页面导航

在发起或接收通话前设置 RCCall.getInstance().callListener，提供通话页面所需的窗口和导航信息：

必需回调	返回内容
didWindowStage	当前通话所属 UIAbility 的 WindowStage
didMultiCallNavPathStack	当前页面 Navigation 实际绑定的 NavPathStack，用于打开群成员选择页
didCallKitNavAbilityName	点击通话横幅或胶囊后返回的 Ability 名称，须与 module.json5 的 module.abilities[].name 一致

以下为 pages/Index.ets 的最小导航示例。使用已有页面时，将监听注册逻辑和导航栈合并到该页面：

import { window } from '@kit.ArkUI';
import { RCCall } from '@rongcloud/callkit';

@Entry
@Component
struct Index {
  private navStack: NavPathStack = new NavPathStack();

  aboutToAppear(): void {
    RCCall.getInstance().callListener = {
      didWindowStage: () => AppStorage.get('windowStage') as window.WindowStage,
      didMultiCallNavPathStack: () => this.navStack,
      didCallKitNavAbilityName: () => 'EntryAbility'
    };
  }

  build() {
    Navigation(this.navStack) {
      // 放置应用的登录、会话或通话入口。
    }
  }
}

不要在 didMultiCallNavPathStack 中临时创建新的导航栈。采用沉浸式布局时，可通过 didMultiCallNavMarginTop、didMultiCallNavMarginBottom 设置群成员选择页的上下边距。更多可选回调见 CallKit API 文档。

2.5. 连接 IM 服务

完成初始化、设置监听回调配置后，使用当前用户的 Token 连接 IM 服务。只有连接成功后，才能发起和接收在线呼叫。

import { EngineError, IMEngine } from '@rongcloud/imlib';

const token = '当前用户的融云 Token';
IMEngine.getInstance().connect(token, 20).then((result) => {
  if (result.code === EngineError.Success) {
    // 连接成功，此时可启用通话入口。
    return;
  }
  if (result.code === EngineError.ConnectTokenExpired) {
    // 从应用服务端获取新 Token，再重新连接。
  } else if (result.code === EngineError.ConnectionTimeout) {
    // 提示用户检查网络，并在网络恢复后重试。
  } else {
    console.error(`连接 IM 失败，错误码：${result.code}`);
  }
});

更多连接状态和错误处理方式见连接 IM 服务。

2.6. 发起通话

在用户点击通话入口时调用以下接口。RCCallMediaType.AUDIO 表示音频通话，RCCallMediaType.VIDEO 表示视频通话。

import { RCCall } from '@rongcloud/callkit';
import { RCCallMediaType } from '@rongcloud/calllib';

// 单人音频通话：传入对方的用户 ID，不能使用当前用户自己的 ID。
RCCall.getInstance().startSingleCall('对方用户 ID', RCCallMediaType.AUDIO);

多人通话需传入 IM 群组 ID。在群成员选择页选择成员并确认后，CallKit 才会发起呼叫：

import { RCCall } from '@rongcloud/callkit';
import { RCCallMediaType } from '@rongcloud/calllib';

RCCall.getInstance().startMultiCall('群组 ID', RCCallMediaType.VIDEO);

2.7. 接听通话与离线推送

CallKit 已实现 CallLib 的来电监听。被叫端完成上述接入并连接 IM 后，收到呼叫会自动展示来电界面，用户点击接听按钮即可进入通话。

应用在后台或未启动时的来电通知，还需要完成华为及融云后台的推送配置、申请通知授权，并将鸿蒙推送 Token 通过 IMEngine.getInstance().setPushToken(pushToken) 设置给 IMLib。推送 Token 与连接 IM 使用的用户 Token 不同，完整流程见推送管理。

3. 更多文档

• CallKit 官方文档
• 实现音视频通话
• CallKit API 文档
• 状态码
• 版本更新说明
• 本模块更新日志