【官方】腾讯云音视频通话插件TencentCloud-TUICallKit

更新记录

2.3.0（2024-04-23）

新增

Android&iOS：新增视频通话背景虚化功能。
Android&iOS：新增 TUIChat 群组顶部显示通话状态，并允许群成员主动加入通话功能。

优化

Android&iOS：优化来电弹出逻辑，默认展示横幅接听框。

修复

Android：修复通话记录编辑界面中，点击删除按钮无响应的问题。
iOS：修复在群通话中点击成员视图时，切换过程中出现重影的问题。
iOS：修复音视频界面特定场景下不显示的问题。
Android&iOS：修复在呼叫忙线中的用户时，通话结束后缺少提示的问题。

2.2.1（2024-03-05）

Android ：修复因为 kotlin 版本不一致导致的 uni-app 云打包编译问题。
iOS：修复因为 Swift 编译导致的 uni-app 云打包编译问题。

2.2.0（2024-02-28）

优化

Android&iOS：全新的 UI 视效，功能更清晰，体验更好。

平台兼容性

Android	Android CPU类型	iOS
适用版本区间：4.4 - 14.0	armeabi-v7a：未测试，arm64-v8a：未测试，x86：未测试	适用版本区间：12 - 17

原生插件通用使用流程：

购买插件，选择该插件绑定的项目。
在HBuilderX里找到项目，在manifest的app原生插件配置中勾选模块，如需要填写参数则参考插件作者的文档添加。
根据插件作者的提供的文档开发代码，在代码中引用插件，调用插件功能。
打包自定义基座，选择插件，得到自定义基座，然后运行时选择自定义基座，进行log输出测试。
开发完毕后正式云打包

付费原生插件目前不支持离线打包。
Android 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/android
iOS 离线打包原生插件另见文档 https://nativesupport.dcloud.net.cn/NativePlugin/offline_package/ios

注意事项：使用HBuilderX2.7.14以下版本，如果同一插件且同一appid下购买并绑定了多个包名，提交云打包界面提示包名绑定不一致时，需要在HBuilderX项目中manifest.json->“App原生插件配置”->”云端插件“列表中删除该插件重新选择

本文将介绍如何用最短的时间完成 TUICallKit 组件的接入，跟随本文档，您将在一个小时的时间内完成如下几个关键步骤，并最终得到一个包含完备 UI 界面的视频通话功能。

环境准备

建议使用最新的 HBuilderX 编辑器。
iOS 9.0 或以上版本且支持音视频的 iOS 设备，暂不支持模拟器。
Android 版本不低于 4.1 且支持音视频的 Android 设备，暂不支持模拟器。如果为真机，请开启允许调试选项。最低兼容 Android 4.1（SDK API Level 16），建议使用 Android 5.0 （SDK API Level 21）及以上版本。
iOS/Android 设备已经连接到 Internet。

步骤一：开通服务

TUICallKit 是基于腾讯云即时通信 IM 和实时音视频 TRTC 两项付费 PaaS 服务构建出的音视频通信组件。您可以按照如下步骤开通相关的服务并体验 7 天的免费试用服务。

登录到即时通信 IM 控制台，单击创建新应用，在弹出的对话框中输入您的应用名称，并单击确定。
单击刚刚创建出的应用，进入基本配置页面，并在页面的右下角找到开通腾讯实时音视频服务功能区，单击免费体验即可开通 TUICallKit 的 7 天免费试用服务。如果需要正式应用上线，可以单击 前往加购 即可进入购买页面。

? IM 音视频通话能力针对不同的业务需求提供了差异化的付费版本供您选择，您可以在 IM 购买页了解包含功能并选购您适合的版本。

在同一页面找到 SDKAppID 和密钥并记录下来，它们会在后续的步骤四：登录 TUI 组件中被用到。

单击免费体验以后，部分之前使用过实时音视频 TRTC 服务的用户会提示：

[-100013]:TRTC service is  suspended. Please check if the package balance is 0 or the Tencent Cloud accountis in arrears

因为新的 IM 音视频通话能力是整合了腾讯云实时音视频 TRTC 和即时通信 IM 两个基础的 PaaS 服务，所以当实时音视频 TRTC 的免费额度（10000分钟）已经过期或者耗尽，就会导致开通此项服务失败，这里您可以单击 TRTC 控制台，找到对应 SDKAppID 的应用管理页，示例如图，开通后付费功能后，再次启用应用即可正常体验音视频通话能力。

步骤二：导入插件

购买 uni-app 原生插件 登录 uni 原生插件市场，并访问 TencentCloud-TUICallKit 插件，在插件详情页中购买（免费插件也可以在插件市场0元购）。购买后才能够云端打包使用插件。购买插件时请选择正确的 appid，以及绑定正确包名。
使用自定义基座打包 uni 原生插件（请使用真机运行自定义基座）使用 uni 原生插件必须先提交云端打包才能生效，购买插件后在应用的 manifest.json 页面的 App原生插件配置 项下单击选择云端插件，选择腾讯云原生音视频插件。直接云端打包后无法打 log，无法排查问题，需要自定义基座调试原生插件。

注意：

自定义基座不是正式版，真正发布时，需要再打正式包。使用自定义基座是无法正常升级替换 APK 的。

请尽量不要使用本地插件，插件包超过自定义基座的限制，可能导致调试收费。

步骤三：在 vue 页面中引入原生插件

使用 uni.requireNativePlugin 的 API 在 vue 页面中引入原生插件，参数为插件的 ID。

const TUICallKit = uni.requireNativePlugin('TencentCloud-TUICallKit');

步骤四：登录 TUI 组件

在您的项目中添加如下代码，完成 TUICallKit 组件的登录。这个步骤异常关键，因为只有在登录成功后才能正常使用 TUICallKit 的各项功能，故请您耐心检查相关参数是否配置正确。

const options = {
  SDKAppID: 1400000001,   // 请替换为步骤一取到的 SDKAppID
  userID: 'denny',        // 请替换为您的 UserID
  userSig: 'xxxxxxxxxxx', // 您可以在控制台中计算一个 UserSig 并填在这个位置
};
TUICallKit.login(options, (res) => {
  if (res.code === 0) {
    console.log('login success');
  } else {
    console.log(`login failed, error message = ${res.msg}`);
  }
});

参数说明 这里详细介绍一下 login 函数中所需要用到的几个关键参数：

SDKAppID：在步骤一中的最后一步中您已经获取到，这里不再赘述。
userID：当前用户的 ID，字符串类型，只允许包含英文字母（a-z 和 A-Z）、数字（0-9）、连词符（-）和下划线（_）。
userSig：使用步骤一中获取的 SecretKey 对 SDKAppID、userID 等信息进行加密，就可以得到 userSig，它是一个鉴权用的票据，用于腾讯云识别当前用户是否能够使用 TRTC 的服务。您可以通过控制台中的 辅助工具 生成一个临时可用的 userSig。
更多信息请参见如何计算及使用 userSig。

注意：这个步骤也是目前我们收到的开发者反馈最多的步骤，常见问题如下：

SDKAppID 设置错误，国内站的 SDKAppID 一般是以140开头的10位整数。
userSig 被错配成了加密密钥（Secretkey），userSig 是用 SecretKey 把 SDKAppID、userID 以及过期时间等信息加密得来的，而不是直接把 Secretkey 配置成 userSig。
userID 被设置成“1”、“123”、“111”等简单字符串，由于 TRTC 不支持同一个 UserID 多端登录，所以在多人协作开发时，形如 “1”、“123”、“111” 这样的 userID 很容易被您的同事占用，导致登录失败，因此我们建议您在调试的时候设置一些辨识度高的 userID。
Github 中的示例代码使用了 genTestUserSig 函数在本地计算 userSig 是为了更快地让您跑通当前的接入流程，但该方案会将您的 SecretKey 暴露在 App 的代码当中，这并不利于您后续升级和保护您的 SecretKey，所以我们强烈建议您将 userSig 的计算逻辑放在服务端进行，并由 App 在每次使用 TUICallKit 组件时向您的服务器请求实时计算出的 userSig。

步骤五：拨打通话

1对1视频通话

通过调用 TUICallKit 的 call 函数并指定通话类型和被叫方的 userID，就可以发起语音或者视频通话。

const options = {
  userID: 'mike',
  callMediaType: 1, // 语音通话(callMediaType = 1)、视频通话(callMediaType = 2)
};
TUICallKit.call(options, (res) => {
  if (res.code === 0) {
    console.log('call success');
  } else {
    console.log(`call failed, error message = ${res.msg}`);
  }
});

群内视频通话

通过调用 TUICallKit 的 groupCall 函数并指定通话类型和被叫方的 userID，就可以发起群内的视频或语音通话。

const options = {
  groupID: 'myGroup',
  userIDList: ['mike', 'tom'],
  callMediaType: 1, // 语音通话(callMediaType = 1)、视频通话(callMediaType = 2)
};
TUICallKit.groupCall(options, (res) => {
  if (res.code === 0) {
    console.log('groupCall success');
  } else {
    console.log(`groupCall failed, error message = ${res.msg}`);
  }
});

步骤六：接听通话

收到来电请求后，TUICallKit 组件会自动唤起来电提醒的接听界面。

步骤七：更多特性

一、设置昵称&头像

如果您需要自定义昵称或头像，可以使用如下接口进行更新。

const options = {
  nickName: 'jack',
  avatar: 'https:/****/user_avatar.png'
}
TUICallKit.setSelfInfo(options, (res) => {
  if (res.code === 0) {
    console.log('setSelfInfo success');
  } else {
    console.log(`setSelfInfo failed, error message = ${res.msg}`);
  }
});

注意：因为用户隐私限制，非好友之间的通话，被叫的昵称和头像更新可能会有延迟，一次通话成功后就会顺利更新。

二、悬浮窗功能

如果您的业务需要开启悬浮窗功能，您可以在 TUICallKit 组件初始化时调用以下接口开启该功能。

TUICallKit.enableFloatWindow(true);

三、通话状态监听

如果您的业务需要 监听通话的状态，例如：异常、通话开始、结束等，可以监听以下事件：

const TUICallKitEvent = uni.requireNativePlugin('globalEvent');
function handleError (res) {}
TUICallKitEvent.addEventListener('onError', handleError);
TUICallKitEvent.addEventListener('onCallReceived', (res) => {
  console.log('onCallReceived', JSON.stringify(res));
});
TUICallKitEvent.addEventListener('onCallCancelled', (res) => {
  console.log('onCallCancelled', res);
});
TUICallKitEvent.addEventListener('onCallBegin', (res) => {
  console.log('onCallBegin', JSON.stringify(res));
});
TUICallKitEvent.addEventListener('onCallEnd', (res) => {
  console.log('onCallEnd', JSON.stringify(res));
});

// 监听的事件要在页面退出时，要及时移除事件监听，移除方法 removeEventListener
TUICallKitEvent.removeEventListener('onError', handleError);

四、自定义铃音

如果您需要自定义来电铃音，可以通过如下接口进行设置。

const TUICallKit = uni.requireNativePlugin('TencentCloud-TUICallKit');

// 【1】通过 uni.saveFile 保存音频文件到本地，具体参考 saveFile 接口: https://zh.uniapp.dcloud.io/api/file/file.html#savefile
const tempFilePath = './static/rain.mp3'; // 本地存放的音频文件
let musicFilePath = '';
uni.saveFile({
  tempFilePath: tempFilePath,
  success: (res) => {
    console.warn('保存文件成功 = ', JSON.stringify(res)); // 获取的是相对路径
    musicFilePath =  res.savedFilePath;

    // 【2】相对路径转绝对路径，否则访问不到
    musicFilePath = plus.io.convertLocalFileSystemURL(musicFilePath); // 转绝对路径

    // 【3】设置铃声
    TUICallKit.setCallingBell(musicFilePath, (res) => {
      if (res.code === 0) {
        console.log('setCallingBell success');
      } else {
        console.log(`setCallingBell failed, error message = ${res.msg}`);
      }
    });
  },
  fail: (err) => {
    console.error('保存文件失败');
  },
});

实现案例

chat-uikit-uniapp 是基于腾讯云 IM SDK 的一款 uni-app UI 组件库，它提供了一些通用的 UI 组件，包含会话、聊天、群组等功能。基于 UI 组件您可以像搭积木一样快速搭建起自己的业务逻辑。

chat-uikit-uniapp 界面效果如下图所示：

常见问题

使用 TUICallKit 后，当应用切至后台后如何被唤醒？

建议：可以结合 TUIOfflinePush插件实现离线唤醒。

技术咨询

了解更多详情您可 QQ 咨询：309869925 (技术交流群)