tim_ui_kit_calling_plugin 0.3.0

Tencent Cloud IM Voive/Video Calling plug-in #

Tencent Cloud IM Voive/Video Calling plug-in (TUICalling) integrate Tencent Real-Time communication(TRTC) to Tencent Cloud IM Chat, used for both single and multi-person calling.

TRTC SDK: Used as the calling module for voice/video calling.
IM SDK: Used for sending chat messages and signal messages.

TUICalling API Preview #

Basic functions

init: init TUICalling
sharedInstance: Singleton of this plug-in instance
call: start calling for one-to-one
groupCall: start calling for multi-person
destroy: destroy TUICalling
setCallingListener: set calling listener
removeCallingListener: remove calling listencer
enableCustomViewRoute: enable/disable custom view route
enableFloatingWindow: enable/disable floating window

Widgets

CallMessageItem Custom message for calling.
isCallingData check if is calling data.

Get started #

What needs to be done before we start

Create a Flutter application
add tim_ui_kit_calling_plugin to dependencies in pubspec.yaml file. Or by executing following commansd.

/// step 1:
flutter pub add tim_ui_kit_calling_plugin

/// step 2:
flutter pub get

Step 1: Add `navigatorKey`

Add navigatorKey to MateriaApp. Aimed of navigate to calling page when receiving calling invitation.

import 'package:tim_ui_kit_calling_plugin/tim_ui_kit_calling_plugin.dart';


MaterialApp(
    navigatorKey: TUICalling.navigatorKey,
    ...
)

Step 2: Initialize `TUICalling`

We recommend you to do this step after login, if you tend to add calling function to current Flutter Chat application.

Use init(sdkAppID: sdkAppId, userID: userID, userSig: userSig) to initialize plug-in, it will deal with receiving calling invitation automatically, and help you to intialize and login IM, to send invitation.

    class  HomePageState extends State<HomePage> {
        final TUICalling _calling = TUICalling();
            
        @override
        initState() {
            super.initState();  
            final userID = '1234756';
            final userSig = '';
            final sdkAppId = 0; /// sdkAppID from Tencent Cloud IM control
            _calling.init(sdkAppID: sdkAppId, userID: userID, userSig: userSig);
        }
    }

The correct way to issue UserSig is to integrate the calculation code of UserSig into your server, and provide an App-oriented interface. When UserSig is needed, your App initiates a request to the business server to obtain the dynamic UserSig `. For more details, please refer to Server Generates UserSig.

Basic function define #

init

initialize plug-in

 Future<void> init({required int sdkAppID, required String userID,required String userSig});

call

start single calling

 Future<void> call(String userId,CallingScenes type,)

groupCall

start calling for multi-person

 Future<void> call(List<String> userIdList, CallingScenes type, String? groupId)

destroy

 void destroy()

enableCustomViewRoute

enable/disable custom view route

 void enableCustomViewRoute(bool isEnable)

enableFloatingWindow

enable/disable floating window

 void enableFloatingWindow(bool isEnable)

setCallingListener

 void setCallingListener(TUICallingListener listener);

removeCallingListener

 void removeCallingListener(TUICallingListener listener);

sharedInstance

    Future<TRTCCalling> sharedInstance();

TUICallingListener

  /// Error callback, indicating an unrecoverable error from the SDK. Need to monitor and give the user appropriate interface prompts according to the situation.
  ///
  /// Parameter:
  ///
  /// errCode	error code
  ///
  /// errMsg	error message
  ///
  /// extraInfo	error extended information fields, some error codes may bring additional information to help locate the problem
  onError,

  /// Warning message callback, used to inform you of some non-serious problems, such as freezing or recoverable decoding failure.
  ///
  /// Parameter:
  ///
  /// errCode	error code
  ///
  /// errMsg	error message
  ///
  /// extraInfo	error extended information fields, some error codes may bring additional information to help locate the problem
  onWarning,

  /// Callback when entering room on local
  ///
  /// If the join is successful, `result` will be a positive number (`result` > 0), represents the time of joining the room, in milliseconds (ms).
  ///
  /// If the join fails, `result` will be a negative number (`result` < 0), representing the error code of the room entry failure.
  ///
  /// Parameter:
  ///
  /// When `result` > 0, it is the time taken to enter the room (ms), and when `result` < 0, it is the error code of entering the room
  onEnterRoom,

  /// Callback when other users entering the room
  ///
  /// Parameter:
  ///
  /// userId
  onUserEnter,

  /// Callback when other users leaving the room
  ///
  /// Parameter:
  ///
  /// userId
  ///
  /// reason	The reason for leaving, 0 means the user exits the room actively, 1 means the user exits after timeout, 2 means being kicked out of the room.
  onUserLeave,

    /*
   * During an multi-person calling, if other participants invite others, they will receive this callback
   * For example, A-B-C is in the multi-person calling, A invites [D, E] into the call, B and C will receive the callback of [D, E]
   * If A invites F to enter the group chat at this time, then B and C will receive the callback of [D, E, F]
   * @Parameter userIdList invite group
   */
  onGroupCallInviteeListUpdate,

    /*
   * Invite to a calling callback
   * @param sponsor inviter
   * @param userIdList who is also invited
   * @param isFromGroup whether multi-person calling
   * @param callType Invitation type: 1-Voice call, 2-Video call
   */
  onInvited,

    /*
    * 1. In a single calling, only the initiator will receive a rejection callback
    * For example, A invites B and C to enter the call, and B rejects it, A can receive the callback, but C cannot
    *
    * 2. In an multi-person callilng, all invitees can receive this callback
    * For example, A invites B and C to enter the call, and B rejects it, both A and C can receive the callback
    * @param userId the user who rejected the call
    */
  onReject,

    /*
     * 1. In a single calling, only the initiator will receive an unanswered callback
     * For example, A invites B and C to enter the call, and B does not answer, A can receive the callback, but C cannot
     *
     * 2. In an multi-person callilng, all invitees can receive this callback
     * For example, A invites B and C to enter the call, but B does not answer, both A and C can receive the callback
     * @param userId
     */
  onNoResp,

    /*
    * The invitor is busy
    * @param userId busy user
    */
  onLineBusy,

    /*
    * As the invitee, it will be received. Receiving this callback means that the call has been cancelled.
    */
  onCallingCancel,

    /*
    * As the invitee, it will be received. Receiving this callback means that the call has been timeouted.
    */
  onCallingTimeout,

    /*
   * Receiving this callback indicates that the call is over
   */
  onCallEnd,

    /// Whether the remote user has a playable main road image (usually used for the camera)
   ///
   /// When you receive the `onUserVideoAvailable`(userId, true) notification, it means that there are available video data frames for this picture. At this point, you need to call the `startRemoteView`(userid) interface to load the user's remote screen. You will then receive a first frame rendering callback called `onFirstVideoFrame`(userid) .
   ///
   /// When you receive the `onUserVideoAvailable`(userId, false) notification, it means that the remote video has been closed, probably because the user called `muteLocalVideo`() or `stopLocalPreview`().
   ///
   /// Parameter:
   ///
   /// userId User ID
   ///
   /// Whether the available screen is open
  onUserVideoAvailable,

    /// Whether the remote user has a playable main road image (usually used for the camera)
   ///
   /// When you receive the `onUserVideoAvailable`(userId, true) notification, it means that there are available video data frames for this picture. At this point, you need to call the `startRemoteView`(userid) interface to load the user's remote screen. You will then receive a first frame rendering callback called `onFirstVideoFrame`(userid) .
   ///
   /// When you receive the `onUserVideoAvailable`(userId, false) notification, it means that the remote video has been closed, probably because the user called `muteLocalVideo`() or `stopLocalPreview`().
   ///
   /// Parameter param:
   ///
   /// userId User ID
   ///
   /// Whether the available screen is open
  onUserAudioAvailable,

    /// The callback used to indicates the volume level, including the volume of each userId and the total volume of the remote end.
   ///
   /// You can switch this callback or set its firing interval by calling the `enableAudioVolumeEvaluation` interface in TRTCCloud. It should be noted that after calling `enableAudioVolumeEvaluation` to turn on the volume callback, this callback will be called at the set time interval regardless of whether someone is speaking in the channel; if no one is speaking, `userVolumes` will be empty and `totalVolume` will be 0.
   ///
   /// Note: When userId is the local user ID, it means its own volume, and userVolumes only contains the volume information of the user who is talking (the volume is not 0).
   ///
   /// Parameter param:
   ///
   /// userVolumes The volume of all talking room members, ranging from 0 - 100.
   ///
   /// totalVolume The total volume of all remote members, ranging from 0 to 100.
  onUserVoiceVolume,

    //Other users log in to the same account and are kicked off the line
  onKickedOffline

Problems #

1: How to customize the call interface?。

TUICalling provides single and multi-person calls by default. If you need to customize the call interface, please use the enableCustomViewRoute method to open the custom view. After enabling, after receiving the audio and video call invitation, the audio and video call pages will not be automatically opened. You can use the setCallingListener method to set message monitoring and monitoring of user entry and other information to achieve invitation sending and receiving and audio and video calling services. Also use sharedInstance to get a TRTCCalling instance. This instance provides TRTC related capabilities, such as switch camera, switch microphone, hang up, answer, etc.

TUICalling #

TUICalling 是基于腾讯云实时音视频（TRTC）和即时通信 IM 服务组合而成的，支持1v1和多人视频通话。

TRTC SDK：使用 TRTC SDK 作为低延时音视频通话组件。
IM SDK：使用 IM SDK 发送和处理信令消息。

TUICalling API 概览 #

基础函数

init: 初始化TUICalling
sharedInstance: 组件单例
call: C2C 邀请通话
groupCall: Group 邀请通话
destroy: 销毁TUICalling
setCallingListener: 设置监听器
removeCallingListener: 移除监听器
enableCustomViewRoute: 开启/关闭自定义视图
enableFloatingWindow: 开启/关闭悬浮窗

基础组件

CallMessageItem 音视频通话自定义消息。
isCallingData 检测是否为音视频通话消息。

快速使用 #

如下会介绍如何在Flutter应用中快速使用TUICalling。

前置条件

创建一个Flutter应用
在 pubspec.yaml 文件中的 dependencies 下添加 tim_ui_kit_calling_plugin。或者执行如下命令：

/// step 1:
flutter pub add tim_ui_kit_calling_plugin

/// step 2:
flutter pub get

步骤1: 引入`navigatorKey`

在你的MateriaApp中添加navigatorKey。主要目的是用于，在接受到语音通话邀请时可以打开通话窗口。

import 'package:tim_ui_kit_calling_plugin/tim_ui_kit_calling_plugin.dart';


MaterialApp(
    navigatorKey: TUICalling.navigatorKey,
    ...
)

步骤2: 初始化`TUICalling`

如果您是在现有IM Flutter 应用中集成音视频通话的功能，建议您在登录之后初始化。 TUICalling初始化，会收到音视频通话的邀请后，自动弹出通话窗口。同时会自动初始化和登录IM, 以用于音视频通话邀请的信令发送。

    class  HomePageState extends State<HomePage> {
        final TUICalling _calling = TUICalling();
            
        @override
        initState() {
            super.initState();  
            final userID = '1234756';
            final userSig = '';
            final sdkAppId = 0; /// 控制台申请的sdkAppID
            _calling.init(sdkAppID: sdkAppId, userID: userID, userSig: userSig);
        }
    }

正确的 UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端，并提供面向 App 的接口，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig。更多详情请参见服务端生成 UserSig。

基础函数定义 #

init

初始化

 Future<void> init({required int sdkAppID, required String userID,required String userSig});

call

c2c 邀请通话

 Future<void> call(String userId,CallingScenes type,)

groupCall

group 邀请通话

 Future<void> call(List<String> userIdList, CallingScenes type, String? groupId)

destroy

销毁

 void destroy()

enableCustomViewRoute

开启自定义视图

 void enableCustomViewRoute(bool isEnable)

enableFloatingWindow

开启App内悬浮窗

 void enableFloatingWindow(bool isEnable)

setCallingListener

设置监听器

 void setCallingListener(TUICallingListener listener);

removeCallingListener

移除监听器

 void removeCallingListener(TUICallingListener listener);

sharedInstance

    Future<TRTCCalling> sharedInstance();

TUICallingListener

  /// 错误回调，表示 SDK 不可恢复的错误，一定要监听并分情况给用户适当的界面提示
  ///
  /// 参数param：
  ///
  /// errCode	错误码
  ///
  /// errMsg	错误信息
  ///
  /// extraInfo	扩展信息字段，个别错误码可能会带额外的信息帮助定位问题
  onError,

  /// 警告回调，用于告知您一些非严重性问题，例如出现卡顿或者可恢复的解码失败。
  ///
  /// 参数param：
  ///
  /// warningCode	错误码
  ///
  /// warningMsg	警告信息
  ///
  /// extraInfo	扩展信息字段，个别警告码可能会带额外的信息帮助定位问题
  onWarning,

  ///本地进房
  ///
  /// 如果加入成功，result 会是一个正数（result > 0），代表加入房间的时间消耗，单位是毫秒（ms）。
  ///
  /// 如果加入失败，result 会是一个负数（result < 0），代表进房失败的错误码。
  ///
  /// 参数param：
  ///
  /// result > 0 时为进房耗时（ms），result < 0 时为进房错误码
  onEnterRoom,

  /// 有用户加入当前房间。
  ///
  /// 参数param：
  ///
  /// userId	用户标识
  onUserEnter,

  /// 有用户离开当前房间。
  ///
  /// 参数param：
  ///
  /// userId	用户标识
  ///
  /// reason	离开原因，0表示用户主动退出房间，1表示用户超时退出，2表示被踢出房间。
  onUserLeave,

  /*
  * 正在IM群组通话时，如果其他与会者邀请他人，会收到此回调
  * 例如 A-B-C 正在IM群组中，A邀请[D、E]进入通话，B、C会收到[D、E]的回调
  * 如果此时 A 再邀请 F 进入群聊，那么B、C会收到[D、E、F]的回调
  * @param userIdList 邀请群组
  */
  onGroupCallInviteeListUpdate,

  /*
  * 被邀请通话回调
  * @param sponsor 邀请者
  * @param userIdList 同时还被邀请的人
  * @param isFromGroup 是否IM群组邀请
  * @param callType 邀请类型 1-语音通话，2-视频通话
  */
  onInvited,

  /*
   * 1. 在C2C通话中，只有发起方会收到拒绝回调
   * 例如 A 邀请 B、C 进入通话，B拒绝，A可以收到该回调，但C不行
   *
   * 2. 在IM群组通话中，所有被邀请人均能收到该回调
   * 例如 A 邀请 B、C 进入通话，B拒绝，A、C均能收到该回调
   * @param userId 拒绝通话的用户
   */
  onReject,

  /*
    * 1. 在C2C通话中，只有发起方会收到无人应答的回调
    * 例如 A 邀请 B、C 进入通话，B不应答，A可以收到该回调，但C不行
    *
    * 2. 在IM群组通话中，所有被邀请人均能收到该回调
    * 例如 A 邀请 B、C 进入通话，B不应答，A、C均能收到该回调
    * @param userId
    */
  onNoResp,

  /*
   * 邀请方忙线
   * @param userId 忙线用户
   */
  onLineBusy,

  /*
   * 作为被邀请方会收到，收到该回调说明本次通话被取消了
   */
  onCallingCancel,

  /*
  * 作为被邀请方会收到，收到该回调说明本次通话超时未应答
  */
  onCallingTimeout,

  /*
  * 收到该回调说明本次通话结束了
  */
  onCallEnd,

  /// 远端用户是否存在可播放的主路画面（一般用于摄像头）
  ///
  /// 当您收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可用的视频数据帧到达。 此时，您需要调用 startRemoteView(userid) 接口加载该用户的远程画面。 然后，您会收到名为 onFirstVideoFrame(userid) 的首帧画面渲染回调。
  ///
  /// 当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，可能由于该用户调用了 muteLocalVideo() 或 stopLocalPreview()。
  ///
  /// 参数param：
  ///
  /// userId	用户标识
  ///
  /// available	画面是否开启
  onUserVideoAvailable,

  /// 远端用户是否存在可播放的主路画面（一般用于摄像头）
  ///
  /// 当您收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可用的视频数据帧到达。 此时，您需要调用 startRemoteView(userid) 接口加载该用户的远程画面。 然后，您会收到名为 onFirstVideoFrame(userid) 的首帧画面渲染回调。
  ///
  /// 当您收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已经被关闭，可能由于该用户调用了 muteLocalVideo() 或 stopLocalPreview()。
  ///
  /// 参数param：
  ///
  /// userId	用户标识
  ///
  /// available	画面是否开启
  onUserAudioAvailable,

  /// 用于提示音量大小的回调，包括每个 userId 的音量和远端总音量。
  ///
  /// 您可以通过调用 TRTCCloud 中的 enableAudioVolumeEvaluation 接口来开关这个回调或者设置它的触发间隔。 需要注意的是，调用 enableAudioVolumeEvaluation 开启音量回调后，无论频道内是否有人说话，都会按设置的时间间隔调用这个回调; 如果没有人说话，则 userVolumes 为空，totalVolume 为0。
  ///
  /// 注意：userId 为本地用户 ID 时表示自己的音量，userVolumes 内仅包含正在说话（音量不为0）的用户音量信息。
  ///
  /// 参数param：
  ///
  /// userVolumes	所有正在说话的房间成员的音量，取值范围0 - 100。
  ///
  /// totalVolume	所有远端成员的总音量, 取值范围0 - 100。
  onUserVoiceVolume,

  //其他用户登录了同一账号，被踢下线
  onKickedOffline

常见问题 #

1: 如何自定义通话界面?。

TUICalling 默认提供了单人和群组通话，如果需要自定义通话界面，请掉用enableCustomViewRoute方法开启自定义视图，开启后，收到音视频通话邀请后，不会自动打开音视频通话窗口。可通过掉用setCallingListener 方法设置消息监听及用户进房等信息的监听来实现邀请收发及音视频通话业务。同时掉用sharedInstance 获取TRTCCalling 实例。该实例提供了，TRTC相关的能力，例如开关摄像头、开关麦克风、挂断、接听等.

tim_ui_kit_calling_plugin 0.3.0 tim_ui_kit_calling_plugin: ^0.3.0 copied to clipboard

Metadata

Tencent Cloud IM Voive/Video Calling plug-in #

TUICalling API Preview #

Basic functions

Widgets

Get started #

What needs to be done before we start

Step 1: Add navigatorKey

Step 2: Initialize TUICalling

Basic function define #

init

call

groupCall

destroy

enableCustomViewRoute

enableFloatingWindow

setCallingListener

removeCallingListener

sharedInstance

TUICallingListener

Problems #

1: How to customize the call interface?。

TUICalling #

TUICalling API 概览 #

基础函数

基础组件

快速使用 #

前置条件

步骤1: 引入navigatorKey

步骤2: 初始化TUICalling

基础函数定义 #

init

call

groupCall

destroy

enableCustomViewRoute

enableFloatingWindow

setCallingListener

removeCallingListener

sharedInstance

TUICallingListener

常见问题 #

1: 如何自定义通话界面?。

← Metadata

Publisher

Metadata

License

Dependencies

More

tim_ui_kit_calling_plugin 0.3.0
tim_ui_kit_calling_plugin: ^0.3.0 copied to clipboard

Step 1: Add `navigatorKey`

Step 2: Initialize `TUICalling`

步骤1: 引入`navigatorKey`

步骤2: 初始化`TUICalling`