接口概览
顶层接口
通过
TcrSdk 对象调用的接口。方法 | 描述 |
初始化 SDK,初始化成功后才能使用其他接口。 | |
创建会话对象 TcrSession,用于和云游戏进行交互。 | |
创建渲染视图 TcrRenderView,用于显示云游戏画面和视图交互。 |
会话接口
通过
TcrSession 对象调用的接口。生命周期相关接口
方法 | 描述 |
释放会话,客户端释放本地会话资源。云端会在自动检测到心跳消失后释放云端资源。 | |
获取会话请求 ID。 |
音视频流控制接口
方法 | 描述 |
开关音频播放。 | |
开关音频上行。 | |
开关视频上行。 | |
暂停音视频流下行。 | |
恢复音视频流下行。 | |
设置下行音频的参数。 | |
设置上行视频的参数。 | |
设置下行视频的接收器。 | |
设置下行音频的接收器。 |
云端应用交互接口
方法 | 描述 |
重启云端应用进程。 | |
向云端应用输入框粘贴文本(需输入框已聚焦)。 | |
禁用云端软键盘(仅支持移动端应用)。 |
云端外设交互接口
方法 | 描述 |
获取云端触摸屏交互对象 TouchScreen。 | |
获取云端手柄交互对象 Gamepad。 | |
获取云端按键交互对象 Keyboard。 | |
获取云端鼠标交互对象 Mouse。 |
触摸屏交互接口
通过
TouchScreen 对象调用的接口。方法 | 描述 |
触发云端触屏触摸事件。 |
接口详细说明
初始化 SDK
初始化(init)云游戏 SDK,初始化成功后才能使用 SDK 的其他接口。
输入参数
TcrConfig
参数名称 | 必选 | 类型 | 描述 |
type | 是 | SdkType | SDK 类型,云游戏请设置为 CloudGame。 |
ctx | 是 | Context | 当前应用的 Android Context。 |
logger | 是 | TcrLogger | 用于接收 SDK 日志的对象,App 需要将收到的 SDK 日志存储到文件和上报,以便分析定位 SDK 运行时的问题。 如果 App 没有显示设置 logger,SDK 会将日志打印到系统 logcat 以及写入日志文件(/storage/emulated/0/Android/data/app package name/files/tcrlogs 目录下)。 注意,当您反馈 SDK 问题时,您需要提供相应的日志。 |
callback | 是 | AsyncCallback | 初始化的异步回调对象。必须在回调成功后才能使用 SDK 的其他接口。 |
示例
TcrSdk.TcrConfig config = new TcrSdk.TcrConfig();config.type = SdkType.CloudPhone;config.ctx = this;config.logger = new TcrLogger() {// 实现日志记录逻辑};config.callback = new AsyncCallback<Void>() {……};TcrSdk.getInstance().init(config);
创建会话
创建会话(createTcrSession)对象,用于和云游戏进行交互。
会话对象创建后,SDK 内部会异步执行会话的本地初始化逻辑,初始化结果会通知给 builder 传入的参数 TcrSession#Observer 对象的 onEvent() 方法 。
输入参数
返回值
创建的会话对象。如果为 null 则代表对象创建失败(通常是因 SDK 状态异常,例如未初始化成功)。
注意:
只有成功创建了会话对象,内部才会执行会话的本地初始化逻辑,才可能进一步收到 observer 的回调事件。
示例
// Tcr会话的观察者,处理各类事件通知的消息和数据private final Observer mSessionObserver = new Observer() {@Overridepublic void onEvent(TcrSession.Event event, Object eventData) {switch (event) {case STATE_INITED:// 本地会话对象初始化完成, eventData对应的数据就是 ClientSession。// 通过请求云API可以拿到 ServerSession。break;case STATE_CONNECTED:// 成功和云机建立连接break;case STATE_CLOSED:showToast("会话关闭", Toast.LENGTH_SHORT);finish();break;}}};// 创建Tcr会话对象private void initTcrSession() {TcrSessionConfig tcrSessionConfig = TcrSessionConfig.builder().observer(mSessionObserver).build();mTcrSession = TcrSdk.getInstance().createTcrSession(tcrSessionConfig);if (mTcrSession == null) {Log.e(TAG, "mTcrSession = null");showToast("创建会话失败,请检查TcrSdk是否初始化成功", Toast.LENGTH_SHORT);}}
创建渲染视图
创建渲染视图(createTcrRenderView)对象,用于 UI 上显示云游戏画面和视图交互。
输入参数
参数名称 | 必选 | 类型 | 描述 |
context | 是 | Context | 视图的 Android Context。 |
session | 是 | TcrSession | 视图关联的会话对象。 |
type | 是 | TcrRenderViewType | 视图类型。 |
示例
// 创建渲染视图mRenderView = TcrSdk.getInstance().createTcrRenderView(PlayActivity.this, mTcrSession, TcrRenderViewType.SURFACE);if (mRenderView == null) {Log.e(TAG, "createTcrRenderView 失败");return;}// 将渲染视图添加到界面上((FrameLayout) findViewById(R.id.render_view_parent)).addView(mRenderView);
释放会话
释放会话(release),客户端释放本地会话资源。云端会在自动检测到心跳消失后释放云端资源。
示例
mTcrSession.release();
获取会话请求 ID
获取当前会话的请求 ID(getRequestId),用于和 SDK 后台排查问题。
示例
mTcrSession.getRequestId();
开关音频播放
setEnableAudioPlaying
输入参数
enable:true 为启用音频播放,false 为禁用。
返回值
无
调用示例
开关音频上行
启用或禁用从麦克风捕获的本地音轨。启用后,本地捕获的音频会上行至云端。
输入参数
enableLocalAudio:true 为启用,false 为禁用。
返回值
无
调用示例
开关视频上行
setEnableLocalAudio
启用或禁用从摄像头捕获的本地视频。启用后,本地捕获的视频画面会上行至云端。
输入参数
enableLocalVideo:true 为启用,false 为禁用。
返回值
无
调用示例
暂停音视频流下行
pauseStreaming
调用示例
恢复音视频流下行
resumeStreaming
调用示例
设置上行的视频的参数
setLocalVideoProfile
配置本地上行的视频的参数(分辨率、帧率、码率、摄像头方向)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
width | 是 | int | 视频宽度。 |
height | 是 | int | 视频高度。 |
fps | 是 | int | 帧率。 |
minBitrate | 是 | int | 最小比特率。 |
maxBitrate | 是 | int | 最大比特率。 |
isFrontCamera | 是 | BOOL | 是否为前置摄像头。 |
返回值
无
调用示例
设置下行的音频的参数
设置远端下行的音频的音量参数(setRemoteAudioPlayProfile)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
volume | 是 | float | 音量系数,取值 [0,10]。 |
返回值
无
调用示例
设置下行视频的接收器
setVideoSink
设置视频渲染目标。SDK 将解码后的视频帧回调到 videoSink,用于后处理或渲染。
输入参数
videoSink:视频接收器,传 null 可移除现有目标。
返回值
无
调用示例
设置下行音频的接收器
setAudioSink
为本次会话设置一个音频接收器。设置完成后,SDK 会将音频数据回调到该音频接收器。
输入参数
audioSink:音频接收器,传 null 可移除现有目标。
返回值
无
调用示例
重启云端应用
restartCloudApp
重启云端应用进程。
输入参数
无
返回值
无
调用示例
向云应用粘贴文本
pasteText
向云端应用输入框粘贴文本(需输入框已聚焦)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
text | 是 | String | 要粘贴的文本内容。 |
返回值
无
调用示例
禁用云端软键盘
setDisableCloudInput
禁用云端软键盘(仅支持移动端应用)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
disableCloudInput | 是 | boolean | 是否禁用云端输入。 |
返回值
无
调用示例
获取云端触摸屏交互对象
getTouchScreen
获取当前会话的云端触摸屏交互对象,用于和云端触摸屏进行交互。该方法将本地触摸视图的事件转换为云端触摸的事件,实现远程触控交互。
输入参数
无
返回值
可以和云端触摸屏进行交互的 TouchScreen 对象。
调用示例
触发云端触屏触摸事件
touch
向云端触摸屏发送触摸事件,模拟用户对云端设备的触控操作(如点击、滑动等)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
x | 是 | float | 触摸点在渲染视图中的水平坐标。 |
y | 是 | float | 触摸点在渲染视图中的垂直坐标。 |
eventType | 是 | int | 触摸事件类型,0代表按下,1代表移动,2代表抬起。 |
fingerID | 是 | int | 触摸点唯一标识符。同一手势中,同一手指的多次事件(如按下→移动→抬起)共享相同 fingerID,用于跟踪多点触控轨迹。 来源:通常从 android.view.MotionEvent.getPointerId(int) 获取。 |
width | 是 | int | 渲染视图的宽度(像素单位)。用于坐标归一化计算,确保 x 值在 [0, width] 范围内有效。 |
height | 是 | int | 渲染视图的高度(像素单位)。用于坐标归一化计算,确保 y 值在 [0, height] 范围内有效。 |
timestamp | 是 | long | 含义:事件发生的时间戳(单位:毫秒),基于系统启动时间(SystemClock.uptimeMillis())。 用途:保证事件顺序一致性,云端可据此处理时序逻辑(如手势识别)。 来源:从 MotionEvent.getEventTime() 获取。 |
返回值
无
调用示例
获取云端手柄交互对象
getGamepad
获取当前会话的云端手柄交互对象,用于和云端虚拟手柄进行交互。该方法将本地手柄事件转换为云端手柄事件,实现远程手柄操作。
输入参数
无
返回值
可以和云端手柄进行交互的 Gamepad 对象。
调用示例
连接云端虚拟手柄
connectGamepad
触发云端设备插入虚拟手柄,使云端应用识别到手柄设备。
输入参数
无
返回值
无
调用示例
断开云端虚拟手柄
disconnectGamepad
触发云端设备拔出虚拟手柄,使云端应用失去手柄设备。
输入参数
无
返回值
无
调用示例
触发云端手柄按键事件
onGamepadKey
向云端手柄发送按键事件,模拟用户对云端设备的手柄按键操作。
输入参数
参数名称 | 必选 | 类型 | 描述 |
keycode | 是 | int | 按键码,请参考 com.tencent.tcr.sdk.api.view.WindowsKeyEvent 中的按键码定义。 |
down | 是 | boolean | 按键状态,true表示按键被按下,false表示按键被释放。 |
返回值
无
调用示例
触发云端手柄摇杆事件
onGamepadStick
向云端手柄发送摇杆事件,模拟用户对云端设备的手柄摇杆操作。
输入参数
参数名称 | 必选 | 类型 | 描述 |
type | 是 | KeyType | 摇杆类型。可选值:LS(左摇杆)、RS(右摇杆)。 |
x | 是 | int | 摇杆的X坐标值。 |
y | 是 | int | 摇杆的Y坐标值。 |
返回值
无
调用示例
触发云端手柄扳机事件
onGamepadTrigger
向云端手柄发送扳机事件,模拟用户对云端设备的手柄扳机操作。
输入参数
参数名称 | 必选 | 类型 | 描述 |
type | 是 | KeyType | 扳机类型。可选值:LT(左扳机)、RT(右扳机)。 |
value | 是 | int | 扳机控制的绝对位置值,范围从0(释放)到255(完全按下)。 |
down | 是 | boolean | 扳机状态,true表示扳机被按下,false表示扳机被释放。 |
返回值
无
调用示例
获取云端键盘交互对象
getKeyboard
获取当前会话的云端键盘交互对象,用于和云端虚拟键盘进行交互。该方法将本地键盘事件转换为云端键盘事件,实现远程键盘输入。
输入参数
无
返回值
可以和云端键盘进行交互的 Keyboard 对象。
调用示例
触发云端键盘按键事件
onKeyboard
向云端键盘发送按键事件,模拟用户对云端设备的键盘操作(如按键按下、释放等)。
输入参数
参数名称 | 必选 | 类型 | 描述 |
keycode | 是 | int | 按键码,定义要触发的具体按键。 |
down | 是 | boolean | 按键状态,true表示按下,false表示释放。 |
返回值
无
调用示例
获取云端鼠标交互对象
getMouse
获取当前会话的云端鼠标交互对象,用于和云端虚拟鼠标进行交互。该方法将本地鼠标事件转换为云端鼠标事件,实现远程鼠标操作。
输入参数
无
返回值
可以和云端鼠标进行交互的 Mouse 对象。
调用示例
设置鼠标光标样式
setMouseCursorStyle
设置云端鼠标光标的显示样式,新的光标样式将立即生效并通过数据通道分发。
输入参数
参数名称 | 必选 | 类型 | 描述 |
cursorStyle | 是 | CursorStyle | 新的光标样式,将覆盖原有样式值。可选值:NORMAL(默认样式)、HUGE(大光标样式)。 |
返回值
无
调用示例
触发云端鼠标按键事件
onMouseKey
向云端鼠标发送按键事件,模拟用户对云端设备的鼠标按键操作。
输入参数
参数名称 | 必选 | 类型 | 描述 |
key | 是 | KeyType | 鼠标按键类型。可选值:LEFT(左键)、RIGHT(右键)、MIDDLE(滚轮)、FORWARD(前进侧键)、BACKWARD(后退侧键)。 |
down | 是 | boolean | 按键状态,true表示按下,false表示释放。 |
返回值
无
调用示例
触发云端鼠标滚轮事件
onMouseScroll
向云端鼠标发送滚轮滚动事件,模拟用户滚动鼠标滚轮的操作。
输入参数
参数名称 | 必选 | 类型 | 描述 |
delta | 是 | float | 滚轮滚动量,取值范围:-1.0~1.0。正值表示向上滚动,负值表示向下滚动。 |
返回值
无