文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>实时音视频>视频通话 SDK>快速接入>HarmonyOS

HarmonyOS

最近更新时间：2026-06-10 09:04:19

我的收藏

本页目录：

本文将介绍如何快速接入 TUICallKit 组件。您可以在 10 分钟内完成以下关键步骤，最终获得一个功能完备的音视频通话界面。
1v1 视频通话
群组通话







准备工作

环境要求

集成开发环境：6.0.0.858 或以上。
手机操作系统：HarmonyOS 5.0.5 或以上。
API Version：17 或以上。

开通服务

在使用腾讯云提供的音视频服务前，您需要前往控制台，为应用开通音视频服务。具体步骤参见 开通服务。开通服务后，请记录 SDKAppID 和 SDKSecretKey在后续的步骤（登录）中会用到。

快速接入

步骤1：导入组件

1. 在 GitHub 中克隆或下载代码，然后将 TUIKit_Harmony 目录下的 call 目录复制到您当前工程的 app 目录中，如下图所示。

2. 在您的工程 entry 的 oh-package.json5 文件中，添加以下插件依赖。
"dependencies": {
    "@tencentcloud/atomicxcore": "^4.2.0",
    "@tencentcloud/tuicallkit": "file:../../../call",
}
说明：
call 目录可以放在任何位置，只要在 oh-package.json5 中正确设置相对路径即可。
3. oh-package.json5 修改完毕后，执行以下命令，安装本地 TUIKit 组件。示例：
ohpm install
ohpm install 会自动安装所需的依赖库。
注意：
使用本地集成方案时，如需升级时需要从 GitHub 获取最新的组件代码，覆盖您本地项目的 call 目录。
当私有化修改和远端有冲突时，需要手动合并，处理冲突。

步骤2：工程配置

1. 权限配置：您需要在您工程 entry 的 module.json5 的 module 模块中，声明以下所需要的权限：
"requestPermissions":[
  {
    "name" : "ohos.permission.INTERNET"
  },
  {
    "name" : "ohos.permission.USE_BLUETOOTH"
  },
  {
    "name" : "ohos.permission.GET_BUNDLE_INFO"
  },
  {
    "name" : "ohos.permission.GET_NETWORK_INFO"
  },
  {
    "name" : "ohos.permission.GET_WIFI_INFO"
  },
  {
    "name" : "ohos.permission.MODIFY_AUDIO_SETTINGS"
  },
  {
    "name" : "ohos.permission.MICROPHONE",
    "reason": "$string:module_desc",
    "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
  },
  {
    "name" : "ohos.permission.CAMERA",
    "reason": "$string:module_desc",
    "usedScene": { "abilities": [ "EntryAbility" ], "when":"always" }
  },
]
2. 模块声明：已有项目集成源码后，需在 build-profile.json5 文件声明模块：
 "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    },
    {
      "name": "tuicallkit",
      "srcPath": "../call",  // 根据实际目录调整
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    }
  ]
3. 将 TUICallKit 与应用主窗口（WindowStage）绑定，使整个 App 在启动后即具备全局接听来电与发起通话的能力，无需在业务页面中重复初始化。
// 您工程的 EntryAbility.ets
import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { TUICallKit } from '@tencentcloud/tuicallkit';

export default class EntryAbility extends UIAbility {
  async onWindowStageCreate(windowStage: window.WindowStage): Promise<void> {
    windowStage.loadContent('pages/Index');
    // 把通话 UI 的承载窗口交给 TUICallKit 管理，建立来电监听
    TUICallKit.createInstance(this.context).attach(windowStage);
  }

  onWindowStageDestroy(): void {
    // 解除窗口绑定，释放资源
    TUICallKit.createInstance(this.context).detach();
  }
}

步骤3：登录

代码集成完成后，需要完成登录操作，这是使用 TUICallKit 的关键步骤。只有在登录成功后，才能正常使用 TUICallKit 的各项功能，因此请仔细检查相关参数配置是否正确：
说明：
在示例代码中，直接进行了登录接口的调用。但在实际项目场景下，强烈推荐您在完成自己的用户身份验证等相关登录操作后，再调用 TUICallKit 的登录服务。这样可以避免因过早调用登录服务，导致业务逻辑混乱或数据不一致的问题，同时也能更好地适配您项目中现有的用户管理和权限控制体系。
ArkTS
import { LoginStore } from '@tencentcloud/atomicxcore'

try {
  await LoginStore.shared().login(
    1400000000,     // 替换为您的 SDKAPPID
    'userID',       // 替换为您的 UserID
    'userSig',      // 替换为您的 UserSig
  );
  // login success
} catch (error) {
  // login error
}
登录接口参数说明：
参数
类型
说明
sdkAppID
number
从 控制台 获取，通常是以 140 或 160 开头的 10 位整数。
userID
string
当前用户的唯一 ID，仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突，请勿使用 1、123 等简单 ID。
userSig
string
用于腾讯云鉴权的票据。更多信息请参见 如何计算及使用 UserSig。
注意：
开发环境：可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 userSig。
生产环境：为了防止密钥泄露，请务必采用服务端生成 userSig 的方式。详细信息请参考 服务端生成 UserSig。

步骤4：设置昵称和头像[可选]

首次登录的用户没有头像和昵称信息，需要通过 LoginStore 的 setSelfInfo 接口设置个人信息：
import { LoginStore, UserProfile, ErrorInfo } from '@tencentcloud/atomicxcore';

try {
  await LoginStore.shared().setSelfInfo(new UserProfile('userID', 'userName', 'avatarURL'));
  console.info("setSelfInfo success");
} catch (error) {
  const err = error as ErrorInfo;
  console.error(`setSelfInfo failed [code: ${err.code}] ${err.message}`);
}
setSelfInfo 接口参数/返回值说明：
参数/返回值
类型
说明
userProfile
UserProfile
个人用户信息核心模型，包含：
userID：要设置用户信息的用户 ID。
nickname：昵称信息。
avatarURL：头像链接。

步骤5：发起通话

拨打方可以通过调用 calls 函数，并指定通话类型和被叫方的 userID，来发起语音或视频通话。calls 接口同时支持一对一通话和多人通话。当 userIDList 中包含一个 userID 时，为一对一通话；当 userIDList 包含多个 userID 时，则为多人通话。
import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
import { ErrorInfo } from '@tencentcloud/atomicxcore';

try {
  await TUICallKit.createInstance(getContext(this)).calls(['mike'], CallMediaType.audio);
  // 成功处理
} catch (error) {
  const err = error as ErrorInfo;
  // 失败处理
}
参数
类型
说明
userIdList
string[]
目标用户的 userID 列表。
mediaType
CallMediaType
通话的媒体类型，例如：视频通话、语音通话。
params?
CallParams
通话扩展参数，例如：房间号、通话邀请超时时间等。

步骤6：接听通话

接听端完成登录后，拨打端发起通话，接收端就可以收到通话邀请，同时伴随铃声和振动。

更多功能

开启来电横幅

您可以通过调用 enableIncomingBanner 接口来开启/关闭来电横幅显示，该功能默认为关闭状态（false）。当被叫端收到来电时，默认展示全屏通话等待界面。启用此功能后，将首先显示一个横幅通知，然后根据需要切换到全屏通话界面。

import { TUICallKit } from '@tencentcloud/tuicallkit';

TUICallKit.createInstance(context).enableIncomingBanner(true);
详情：默认为 false，被叫端收到邀请后默认弹出全屏通话等待界面。开启后先展示一个横幅，然后根据需要拉起全屏通话界面。

多人通话

主叫方使用 calls 方法发起通话时，若被叫用户列表超过一人，则自动视为群组通话。其他成员可通过 join 方法加入该多人通话。
发起多人通话：使用 calls 方法发起通话时，若被叫用户列表（userIdList）超过一人，则自动视为群组通话。
import { TUICallKit, CallMediaType } from '@tencentcloud/tuicallkit';
import { ErrorInfo } from '@tencentcloud/atomicxcore';

try {
  await TUICallKit.createInstance(getContext(this)).calls(['mike','tate'], CallMediaType.audio);
  // 成功处理
} catch (error) {
  const err = error as ErrorInfo;
  // 失败处理
}
加入多人通话：可使用 join 方法加入指定的群组通话。
import { TUICallKit } from '@tencentcloud/tuicallkit';

await TUICallKit.createInstance(context).join('your_call_id');
参数
类型
说明
callId
string
此次通话的唯一标识。

铃声设置

您可通过以下方式设置默认铃声、来电静音模式、离线推送铃声：
设置默认铃声（方式1）：如果您通过源码依赖 TUICallKit 组件，您可以替换铃声资源文件（发起呼叫时的铃音、接到呼叫时的铃音）设置默认铃声。
设置默认铃声（方式2）：通过 setCallingBell 接口设置被叫端收到的来电铃声。
import { TUICallKit } from '@tencentcloud/tuicallkit';

TUICallKit.createInstance(context).setCallingBell('***/callingBell.mp3');
详情：这里仅限传入本地文件地址，需要确保该文件目录是应用可以访问的。铃声设置后与设备绑定，更换用户，铃声依旧会生效。如需恢复默认铃声，filePath 传空即可。
参数
类型
说明
filePath
string
铃声文件的路径。
来电静音模式：您可以通过 enableMuteMode 接口设置静音模式。
import { TUICallKit } from '@tencentcloud/tuicallkit';


TUICallKit.createInstance(context).enableMuteMode(true);
详情：开启后，收到通话请求，不会播放来电铃声。

自定义您的 UI

替换图标按钮

您可以直接替换 src/main/resources/base/media 文件夹下的图标，以确保整个 App 中的图标色调风格保持一致。以下列出了基本的功能按钮，您可以替换对应的图标以适配自己的业务场景。

常见问题

oh-package.json5 文件有没有示例配置可以参考？

您可以参考 GitHub TUIKit_Harmony application_call 工程中的 oh-package.json5 示例文件。

交流与反馈

如果您在使用过程中，有任何意见或建议，请 联系我们。
中国站