@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/callkit/preset/flutter/api.md

@@ -0,0 +1,401 @@
+## TUICallKit API 简介
+
+TUICallKit API 是音视频通话组件的**含 UI 接口**，使用TUICallKit API，您可以通过简单接口快速实现一个类微信的音视频通话场景，更详细的接入步骤，详情请参见 快速接入（TUICallKit）。
+
+## API 概览
+| API | 描述 |
+| --- | --- |
+| login | 登录 |
+| logout | 登出 |
+| setSelfInfo | 设置用户的昵称、头像 |
+| calls | 发起通话。 |
+| join | 主动加入通话。 |
+| enableMuteMode | 开启/关闭静音模式 |
+| enableFloatWindow | 开启/关闭悬浮窗功能 |
+| setCallingBell | 设置自定义来电铃音 |
+| enableVirtualBackground | 开启/关闭虚拟背景功能 |
+
+## API 详情
+
+### login
+
+登录。
+``` cpp
+Future<TUIResult> login(int sdkAppId, String userId, String userSig)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| sdkAppId | int | 用户 SDKAppID |
+| userId | String | 用户 ID |
+| userSig | String | 用户签名 userSig |
+| 返回值 | TUIResult | 包含 code 和 message 信息：code 为空 ("") 表示调用成功；code 不为空 ("") 表示调用失败，失败原因见 message |
+
+### logout
+
+登出。
+``` cpp
+Future<void> logout()
+```
+
+### setSelfInfo
+
+设置用户昵称、头像。用户昵称不能超过500字节，用户头像必须是URL格式。
+``` cpp
+Future<TUIResult> setSelfInfo(String nickname, String avatar)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| nickName | String | 目标用户的昵称，非必填 |
+| avatar | String | 目标用户的头像，非必填 |
+| 返回值 | TUIResult | 包含 code 和 message 信息：code 为空 ("") 表示调用成功；code 不为空 ("") 表示调用失败，失败原因见 message |
+
+### calls
+
+发起通话。**v2.9+ 版本支持。**
+``` java
+Future<TUIResult> calls(List<String> userIdList, TUICallMediaType mediaType, TUICallParams params)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| userIdList | List<String> | 目标用户的userId 列表 |
+| callMediaType | TUICallMediaType | 通话的媒体类型，比如：`TUICallMediaType.video `或  `TUICallMediaType.audio` |
+| params | TUICallParams | **可选**通话扩展参数，例如：房间号、通话邀请超时时间，离线推送自定义内容等 |
+
+### join
+
+主动加入通话。**v2.9+ 版本支持。**
+``` java
+Future<void> join(String callId)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| callId | String | 此次通话的唯一 ID |
+
+### enableMuteMode
+
+开启后，收到通话请求，不会播放来电铃声。
+``` javascript
+Future<void> enableMuteMode(bool enable)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| enable | bool | 开启、关闭静音；true 表示开启静音 |
+
+### enableFloatWindow
+
+开启/关闭悬浮窗功能，设置为false后，通话界面左上角的悬浮窗按钮会隐藏。
+``` javascript
+Future<void> enableFloatWindow(bool enable)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| enable | bool | 开启、关闭悬浮窗功能；true 表示开启浮窗 |
+
+### setCallingBell
+
+自定义来电铃声：将铃声文件添加至主工程的`assets`资源中，传入资源文件名称即可。
+``` javascript
+Future<void> setCallingBell(String assetName)
+```
+
+### enableVirtualBackground
+
+开启/关闭虚拟背景功能，开启虚拟背景功能后，您可以在 UI 上显示模糊背景的功能按钮，点击按钮可直接启用模糊背景功能。
+``` javascript
+Future<void> enableVirtualBackground(bool enable)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| enable | bool | 开启、关闭静音；true 表示开启静音 |
+
+## 废弃接口
+
+### call
+
+拨打电话（1v1通话）。
+
+> **注意：**
+>
+
+> 该接口已在 v2.9+ 版本废弃，建议使用 calls 接口替代。
+>
+
+``` cpp
+Future<void> call(String userId, TUICallMediaType callMediaType, [TUICallParams? params])
+
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| userId | String | 目标用户的 userID |
+| callMediaType | TUICallMediaType | 通话的媒体类型，比如：`TUICallMediaType.video `或 `TUICallMediaType.audio` |
+
+### groupCall
+
+发起群组通话，注意：使用群组通话前需要创建 IM 群组，如果已经创建，请忽略。
+
+> **注意：**
+>
+
+> 该接口已在 v2.9+ 版本废弃，建议使用 calls 接口替代。
+>
+
+``` javascript
+Future<void> groupCall(String groupId, List<String> userIdList, TUICallMediaType callMediaType,[TUICallParams? params])
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| groupId | String | 此次群组通话的群 ID |
+| userIdList | List<String> | 目标用户的 userId 列表 |
+| callMediaType | TUICallMediaType | 通话的媒体类型，比如：`TUICallMediaType.video `或  `TUICallMediaType.audio` |
+
+### joinInGroupCall
+
+加入群组中已有的音视频通话。
+
+> **注意：**
+>
+
+> 该接口已在 v2.9+ 版本废弃，建议使用 join 接口替代。
+>
+
+``` javascript
+Future<void> joinInGroupCall(TUIRoomId roomId, String groupId, TUICallMediaType callMediaType)
+```
+| 参数 | 类型 | 含义 |
+| --- | --- | --- |
+| roomId | TUIRoomID | 此次通话的音视频房间 ID |
+| groupId | String | 此次群组通话的群 ID |
+| callMediaType | TUICallMediaType | 通话的媒体类型，比如：`TUICallMediaType.video `或 `TUICallMediaType.audio` |
+## **常用结构**
+
+### TUIResult
+
+调用 API 的返回值
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| code | String | code 为空 "" 表示调用成功，code 不为空 "" 表示调用失败 |
+| message | String | 失败原因 |
+
+### TUIRoomId
+
+房间 ID
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| intRoomId | int | 数字房间号 |
+| strRoomId | String | 字符串房间号 |
+
+### VideoRenderParams
+
+视频画面的渲染参数
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| fillMode | FillMode | 视频画面填充模式 |
+| rotation | Rotation | 视频画面旋转方向 |
+
+### VideoEncoderParams
+
+视频编码参数
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| resolution | Resolution | 视频分辨率 |
+| resolutionMode | ResolutionMode | 视频宽高比模式 |
+
+### TUICallParams
+
+通话参数
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| roomId | TUIRoomId | 房间 ID |
+| offlinePushInfo | TUIOfflinePushInfo | 厂商离线推送配置信息 |
+| timeout | String | 超时时常 |
+| userData | String | 用户自定义数据 |
+| chatGroupId | String | 群组 ID |
+
+### TUIOfflinePushInfo
+
+厂商离线推送配置信息，详情配置步骤请参考：离线唤醒。
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| title | String | 离线推送展示通知栏标题 |
+| desc | String | 离线推送展示通知栏内容 |
+| ignoreIOSBadge | bool | 离线推送忽略 badge 计数（仅对 iOS 生效）， 如果设置为 true，在 iOS 接收端，这条消息不会使 APP 的应用图标未读计数增加 |
+| iOSSound | String | 离线推送声音设置（仅对 iOS 生效）。 当 sound = IOS_OFFLINE_PUSH_NO_SOUND，表示接收时不会播放声音。 当 sound = IOS_OFFLINE_PUSH_DEFAULT_SOUND，表示接收时播放系统声音。 如果要自定义 iOSSound，需要先把语音文件链接进 Xcode 工程，然后把语音文件名（带后缀）设置给 iOSSound |
+| androidSound | String | 离线推送声音设置（仅对 Android 生效, IMSDK 6.1 及以上版本支持）。 只有华为和谷歌手机支持设置声音提示，小米手机设置声音提示，请您参照：[小米自定义铃声](https://dev.mi.com/console/doc/detail?pId=1278%23_3_0#_3_0)。 另外，谷歌手机 FCM 推送在 Android 8.0 及以上系统设置声音提示，必须调用 setAndroidFCMChannelID 设置好 channelID，才能生效 |
+| androidOPPOChannelID | String | 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID |
+| androidVIVOClassification | int | VIVO 推送消息分类 (待废弃接口，VIVO 推送服务于 2023 年 4 月 3 日优化消息分类规则，推荐使用 setAndroidVIVOCategory 设置消息类别)。0：运营消息 1：系统消息，默认取值为 1 |
+| androidXiaoMiChannelID | String | 小米手机 8.0 系统及以上的渠道 ID |
+| androidFCMChannelID | String | FCM 通道手机 8.0 系统及以上的渠道 ID |
+| androidHuaWeiCategory | String | 华为推送消息分类，详见：[华为消息分类标准](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-classification-0000001149358835) |
+| isDisablePush | bool | 是否关闭推送（默认开启推送） |
+| iOSPushType | TUICallIOSOfflinePushType | iOS 离线推送类型，默认：APNs |
+
+### TUICallRecords
+
+通话记录信息
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| callId | String | 通话记录 ID |
+| inviter | String | 邀请者 ID |
+| inviteList | List<String> | 被邀请用户 ID 列表 |
+| scene | TUICallScene | 通话场景 |
+| mediaType | TUICallMediaType | 通话媒体类型 |
+| groupId | String | 群组 ID |
+| role | TUICallRole | 通话角色 |
+| result | TUICallResultType | 通话结果类型 |
+| beginTime | int | 开始时间 |
+| totalTime | int | 总时间 |
+
+### TUICallRecentCallsFilter
+
+通话记录过滤条件
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| begin | double | 开始时间 |
+| end | double | 结束时间 |
+| resultType | TUICallResultType | 通话记录类型 |
+
+### CallObserverExtraInfo
+
+回调扩展信息
+| 类型 | 类型 | 描述 |
+| --- | --- | --- |
+| roomId | TUIRoomId | 房间 ID |
+| role | TUICallRole | 通话角色 |
+| userData | String | 发起通话时自定义扩展字段，详情见 TUICallParams |
+| chatGroupId | String | 群组 ID |
+
+## **枚举定义**
+
+### TUICallMediaType
+
+通话类型
+| 类型 | 描述 |
+| --- | --- |
+| none | 未知类型 |
+| audio | 语音通话 |
+| video | 视频通话 |
+
+### TUICallRole
+
+通话角色
+| 类型 | 描述 |
+| --- | --- |
+| none | 未知类型 |
+| caller | 主叫（邀请方） |
+| called | 被叫（被邀请方） |
+
+### TUICallStatus
+
+通话状态
+| 类型 | 描述 |
+| --- | --- |
+| none | 未知类型 |
+| waiting | 通话等待中 |
+| accept | 通话已接听 |
+
+### TUICallScene
+
+通话场景
+| 类型 | 描述 |
+| --- | --- |
+| singleCall | 单人通话 |
+| groupCall | 群组通话 |
+
+### TUINetworkQuality
+
+网络质量
+| 类型 | 描述 |
+| --- | --- |
+| unknown | 未定义 |
+| excellent | 当前网络非常好 |
+| good | 当前网络比较好 |
+| poor | 当前网络一般 |
+| bad | 当前网络较差 |
+| vBad | 当前网络很差 |
+| down | 当前网络不满足通话的最低要求 |
+
+### FillMode
+
+视频画面填充模式
+| 类型 | 描述 |
+| --- | --- |
+| fill | 填充模式：即将画面内容居中等比缩放以充满整个显示区域，超出显示区域的部分将会被裁剪掉，此模式下画面可能不完整。 |
+| fit | 适应模式：即按画面长边进行缩放以适应显示区域，短边部分会被填充为黑色，此模式下图像完整但可能留有黑边。 |
+
+### Rotation
+
+视频画面旋转方向
+| 类型 | 描述 |
+| --- | --- |
+| rotation_0 | 不旋转 |
+| rotation_90 | 顺时针旋转90度 |
+| rotation_180 | 顺时针旋转180度 |
+| rotation_270 | 顺时针旋转270度 |
+
+### ResolutionMode
+
+视频宽高比模式
+| 类型 | 描述 |
+| --- | --- |
+| landscape | 横屏分辨率，例如：Resolution.Resolution_640_360 + ResolutionMode.Landscape = 640 × 360 |
+| portrait | 竖屏分辨率，例如：Resolution.Resolution_640_360 + ResolutionMode.Portrait = 360 × 640 |
+
+### Resolution
+
+视频分辨率
+| 类型 | 描述 |
+| --- | --- |
+| resolution_640_360 | 宽高比 16:9；分辨率 640x360；建议码率（VideoCall）500kbps |
+| resolution_960_540 | 宽高比 16:9；分辨率 960x540；建议码率（VideoCall）850kbps |
+| resolution_1280_720 | 宽高比 16:9；分辨率 1280x720；建议码率（VideoCall）1200kbps |
+| resolution_1920_1080 | 宽高比 16:9；分辨率 1920x1080；建议码率（VideoCall）2000kbps |
+
+### TUICallIOSOfflinePushType
+
+iOS 离线推送类型
+| 类型 | 描述 |
+| --- | --- |
+| APNs | 普通推送 |
+| VoIP | VoIP 推送 |
+
+### TUICamera
+
+摄像头类型
+| 类型 | 描述 |
+| --- | --- |
+| front | 前置摄像头 |
+| back | 后置摄像头 |
+
+### TUIAudioPlaybackDevice
+
+音频播放路由
+| 类型 | 描述 |
+| --- | --- |
+| speakerphone | 扬声器 |
+| earpiece | 耳麦 |
+
+### TUICallResultType
+
+通话记录类型
+| 类型 | 描述 |
+| --- | --- |
+| unknown | 未知 |
+| missed | 未接 |
+| incoming | 接入 |
+| outgoing | 拨出 |
+
+### CallEndReason
+
+通话结束原因
+| 类型 | 描述 |
+| --- | --- |
+| unknown | 未知 |
+| hangup | 挂断 |
+| reject | 拒绝 |
+| noResponse | 无响应 |
+| offline | 离线 |
+| lineBusy | 忙线 |
+| canceled | 取消通话 |
+| otherDeviceAccepted | 其他设备接听 |
+| otherDeviceReject | 其他设备拒绝 |
+| endByServer | 后台结束 |