Android SDK 接口

最近更新时间:2025-10-28 10:03:12

我的收藏

接口概览

顶层接口

通过 TcrSdk 对象调用的接口。
方法
描述
init
初始化 SDK,初始化成功后才能使用其他接口。
创建会话对象 TcrSession,用于和云游戏进行交互。
创建渲染视图 TcrRenderView,用于显示云游戏画面和视图交互。

会话接口

通过 TcrSession 对象调用的接口。

生命周期相关接口

方法
描述
release
释放会话,客户端释放本地会话资源。云端会在自动检测到心跳消失后释放云端资源。
获取会话请求 ID。

音视频流控制接口

方法
描述
开关音频播放。
开关音频上行。
开关视频上行。
暂停音视频流下行。
恢复音视频流下行。
设置下行音频的参数。
设置上行视频的参数。
设置下行视频的接收器。
设置下行音频的接收器。

云端应用交互接口

方法
描述
重启云端应用进程。
pasteText
向云端应用输入框粘贴文本(需输入框已聚焦)。
禁用云端软键盘(仅支持移动端应用)。

云端外设交互接口

方法
描述
获取云端触摸屏交互对象 TouchScreen。
获取云端手柄交互对象 Gamepad。
获取云端按键交互对象 Keyboard。
获取云端鼠标交互对象 Mouse。

触摸屏交互接口

通过 TouchScreen 对象调用的接口。
方法
描述
touch
触发云端触屏触摸事件。

接口详细说明

初始化 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() 方法 。

输入参数

参见 TcrSessionConfig

返回值

创建的会话对象。如果为 null 则代表对象创建失败(通常是因 SDK 状态异常,例如未初始化成功)。
注意:
只有成功创建了会话对象,内部才会执行会话的本地初始化逻辑,才可能进一步收到 observer 的回调事件。

示例

// Tcr会话的观察者,处理各类事件通知的消息和数据
private final Observer mSessionObserver = new Observer() {
@Override
public 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 为禁用。

返回值

调用示例

参考 TcrDemo

开关音频上行

启用或禁用从麦克风捕获的本地音轨。启用后,本地捕获的音频会上行至云端。

输入参数

enableLocalAudio:true 为启用,false 为禁用。

返回值

调用示例

参考 TcrDemo

开关视频上行

setEnableLocalAudio
启用或禁用从摄像头捕获的本地视频。启用后,本地捕获的视频画面会上行至云端。

输入参数

enableLocalVideo:true 为启用,false 为禁用。

返回值

调用示例

参考 TcrDemo

暂停音视频流下行

pauseStreaming

调用示例

参考 TcrDemo

恢复音视频流下行

resumeStreaming

调用示例

参考 TcrDemo

设置上行的视频的参数

setLocalVideoProfile
配置本地上行的视频的参数(分辨率、帧率、码率、摄像头方向)。

输入参数

参数名称
必选
类型
描述
width
int
视频宽度。
height
int
视频高度。
fps
int
帧率。
minBitrate
int
最小比特率。
maxBitrate
int
最大比特率。
isFrontCamera
BOOL
是否为前置摄像头。

返回值

调用示例

参考 TcrDemo

设置下行的音频的参数

设置远端下行的音频的音量参数(setRemoteAudioPlayProfile)。

输入参数

参数名称
必选
类型
描述
volume
float
音量系数,取值 [0,10]。

返回值

调用示例

参考 TcrDemo

设置下行视频的接收器

setVideoSink
设置视频渲染目标。SDK 将解码后的视频帧回调到 videoSink,用于后处理或渲染。

输入参数

videoSink:视频接收器,传 null 可移除现有目标。

返回值

调用示例

参考 TcrDemo

设置下行音频的接收器

setAudioSink
为本次会话设置一个音频接收器。设置完成后,SDK 会将音频数据回调到该音频接收器。

输入参数

audioSink:音频接收器,传 null 可移除现有目标。

返回值

调用示例

参考 TcrDemo

重启云端应用

restartCloudApp
重启云端应用进程。

输入参数

返回值

调用示例

参考 TcrDemo

向云应用粘贴文本

pasteText
向云端应用输入框粘贴文本(需输入框已聚焦)。

输入参数

参数名称
必选
类型
描述
text
String
要粘贴的文本内容。

返回值

调用示例

参考 TcrDemo

禁用云端软键盘

setDisableCloudInput
禁用云端软键盘(仅支持移动端应用)。

输入参数

参数名称
必选
类型
描述
disableCloudInput
boolean
是否禁用云端输入。

返回值

调用示例

参考 TcrDemo

获取云端触摸屏交互对象

getTouchScreen
获取当前会话的云端触摸屏交互对象,用于和云端触摸屏进行交互。该方法将本地触摸视图的事件转换为云端触摸的事件,实现远程触控交互。

输入参数

返回值

可以和云端触摸屏进行交互的 TouchScreen 对象。

调用示例

参考 TcrDemo

触发云端触屏触摸事件

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() 获取。

返回值

调用示例

参考 TcrDemo

获取云端手柄交互对象

getGamepad
获取当前会话的云端手柄交互对象,用于和云端虚拟手柄进行交互。该方法将本地手柄事件转换为云端手柄事件,实现远程手柄操作。

输入参数

返回值

可以和云端手柄进行交互的 Gamepad 对象。

调用示例

参考 TcrDemo

连接云端虚拟手柄

connectGamepad
触发云端设备插入虚拟手柄,使云端应用识别到手柄设备。

输入参数

返回值

调用示例

参考 TcrDemo

断开云端虚拟手柄

disconnectGamepad
触发云端设备拔出虚拟手柄,使云端应用失去手柄设备。

输入参数

返回值

调用示例

参考 TcrDemo

触发云端手柄按键事件

onGamepadKey
向云端手柄发送按键事件,模拟用户对云端设备的手柄按键操作。

输入参数

参数名称
必选
类型
描述
keycode
int
按键码,请参考 com.tencent.tcr.sdk.api.view.WindowsKeyEvent 中的按键码定义。
down
boolean
按键状态,true表示按键被按下,false表示按键被释放。

返回值

调用示例

参考 TcrDemo

触发云端手柄摇杆事件

onGamepadStick
向云端手柄发送摇杆事件,模拟用户对云端设备的手柄摇杆操作。

输入参数

参数名称
必选
类型
描述
type
KeyType
摇杆类型。可选值:LS(左摇杆)、RS(右摇杆)。
x
int
摇杆的X坐标值。
y
int
摇杆的Y坐标值。

返回值

调用示例

参考 TcrDemo

触发云端手柄扳机事件

onGamepadTrigger
向云端手柄发送扳机事件,模拟用户对云端设备的手柄扳机操作。

输入参数

参数名称
必选
类型
描述
type
KeyType
扳机类型。可选值:LT(左扳机)、RT(右扳机)。
value
int
扳机控制的绝对位置值,范围从0(释放)到255(完全按下)。
down
boolean
扳机状态,true表示扳机被按下,false表示扳机被释放。

返回值

调用示例

参考 TcrDemo

获取云端键盘交互对象

getKeyboard
获取当前会话的云端键盘交互对象,用于和云端虚拟键盘进行交互。该方法将本地键盘事件转换为云端键盘事件,实现远程键盘输入。

输入参数

返回值

可以和云端键盘进行交互的 Keyboard 对象。

调用示例

参考 TcrDemo

触发云端键盘按键事件

onKeyboard
向云端键盘发送按键事件,模拟用户对云端设备的键盘操作(如按键按下、释放等)。

输入参数

参数名称
必选
类型
描述
keycode
int
按键码,定义要触发的具体按键。
down
boolean
按键状态,true表示按下,false表示释放。

返回值

调用示例

参考 TcrDemo

获取云端鼠标交互对象

getMouse
获取当前会话的云端鼠标交互对象,用于和云端虚拟鼠标进行交互。该方法将本地鼠标事件转换为云端鼠标事件,实现远程鼠标操作。

输入参数

返回值

可以和云端鼠标进行交互的 Mouse 对象。

调用示例

参考 TcrDemo

设置鼠标光标样式

setMouseCursorStyle
设置云端鼠标光标的显示样式,新的光标样式将立即生效并通过数据通道分发。

输入参数

参数名称
必选
类型
描述
cursorStyle
CursorStyle
新的光标样式,将覆盖原有样式值。可选值:NORMAL(默认样式)、HUGE(大光标样式)。

返回值

调用示例

参考 TcrDemo

触发云端鼠标按键事件

onMouseKey
向云端鼠标发送按键事件,模拟用户对云端设备的鼠标按键操作。

输入参数

参数名称
必选
类型
描述
key
KeyType
鼠标按键类型。可选值:LEFT(左键)、RIGHT(右键)、MIDDLE(滚轮)、FORWARD(前进侧键)、BACKWARD(后退侧键)。
down
boolean
按键状态,true表示按下,false表示释放。

返回值

调用示例

参考 TcrDemo

触发云端鼠标滚轮事件

onMouseScroll
向云端鼠标发送滚轮滚动事件,模拟用户滚动鼠标滚轮的操作。

输入参数

参数名称
必选
类型
描述
delta
float
滚轮滚动量,取值范围:-1.0~1.0。正值表示向上滚动,负值表示向下滚动。

返回值

调用示例

参考 TcrDemo