WEB_RTC SDK 开发指南

对应SDK版本号：master-3.30

版本号	Release Note	日期
master-3.30	1、WASD等功能键支持随窗口大小变化而改变	2021年11月23日
master-3.27	1、键位配置说明 2、sdk支持下载功能 3、新增场景回调 newFileAppear、fileList、downLoadFileInfo、cancelDownLoadFail 4、新增接口获取可下载文件列表 Cloudplay.getFileList(option) 5、新增接口文件下载Cloudplay.downLoadFile(name,callback) 6、新增接口取消文件下载 Cloudplay.cancelDownLoadFile(name) 7、新增接口重置无操作时长计时器 Cloudplay.resetInputTimer() 8、新增启动参数 noInputTimeout	2021年9月5日
master-3.21.1	1、获取授权码 2、开启直播 3、关闭直播 4、检测是否支持直播 5、获取控制权	2021年7月2日

1 文档概述

欢迎使用海马云游戏服务，本文档主要介绍云游戏WEB端SDK的接入流程及提供支持的API详情，开发者通过接入海马云游戏SDK，可以实现云游戏的播放、停止、状态回调等各类控制操作和数据交互，在海马云游戏端到端全栈云服务能力基础上，为用户带来顺畅的云游戏体验。在开始接入SDK前，请确认您已经拥有海马云游戏平台接入商ID并创建了渠道号，并已经完成了在海马云游戏平台上传游戏包等相关准备工作。

2 名词解释

saas-sdk：SDK名称，即和海马云SAAS平台交互的SDK。
accessKeyID：接入商唯一ID。
appChannel：渠道号，同一接入商可以创建多个渠道号，用来区别管理游戏包，包名相同的游戏可以在两个渠道分别上架和应用。
channelId：接入方自行定义，主要方便接入方推广需要，如一个APK，发布到不同的推广平台时用不一样channelId，根据channelId区分各个推广平台的推广效果。
cid：海马云游戏单次游戏的唯一标识。
HSN数量：接入商在海马云游戏平台配置的云端实例数量，即能允许用户进行云游戏的最大并发数量。

3 接入步骤

欢迎使用云游戏SDK。为方便Web开发者调试和接入海马云游戏多产品API，这里向您介绍适用于Web开发的接入步骤。

说明：

必须给一个唯一的DOM节点，SDK将在这个节点内加载游戏。

3.1 导入SDK

页面head中引用css及js，请注意文件引用路径是否正确。

代码示例

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="saas-sdk.css">
    <script src="saas-sdk.js"></script>
</head>
<body>
    <div id="example"></div>
</body>
</html>

文件名	说明
saas-sdk.css	云游戏WebSDK依赖的css样式
saas-sdk.js	云游戏WebSDK依赖的js插件

4 API接口

4.1 初始化

SDK初始化依赖accessKeyID等字段，请确认配置了正确的数据。

代码示例

Cloudplay.initSDK({
    accessKeyID: '',
    channelId: '',
    pkg_name: '',
    isHideToolBar: false,
    onSceneChanged: function(sceneId, extraInfo) {
        console.log('sceneId:'+sceneId,extraInfo);
        if(sceneId == 'play') {
            alert('游戏开始了');
        }
    },
    MessageHandler: function(message) {
        console.log('got message:',message);
    }
});

参数说明

参数	类型	必选	说明
accessKeyID	string	是	接入商唯一ID
channelId	string	是	接入方自行定义，主要方便接入方推广需要，如一个APK，发布到不同的推广平台时用不同channelId
pkg_name	string	是	游戏包名称
isHideToolBar	boolean	否	是否隐藏toolbar：false：不隐藏（默认值）；true：隐藏
onSceneChanged	function	是	场景切换回调函数：参考本文档中的“onSceneChanged回调函数说明”
MessageHandler	function	否	支付消息的回调函数：参考本文档中的“MessageHandler回调函数说明”

onSceneChanged回调函数说明

游戏过程中的各个场景切换，会通过onSceneChanged回调函数传递，您可以在场景回调时进行相应的处理操作。以下为参数说明：

sceneId	sceneId说明	extraInfo类型	extraInfo属性名	extraInfo属性说明
init	初始化中	null	~	~
play	开始游戏	object	cid	本次游戏的cid
~	~	~	cur_rate	游戏当前码率
vibf	游戏画面第一帧	null	~	~
stop	游戏结束	object	interval	当次游戏时间，单位：秒
~	~	~	reason	time_limit：本次游戏时间已到 no_operation：无操作超时，默认20分钟，可联系运营人员修改配置 instance_err：云端实例出错 multi_inst：超过实例数的申请上限 queue_limit：排队人数过多，禁止排队 network_off：网络断开 token_expire：token鉴权失败 normal：正常调用stopSDK主动停止游戏 low_bitrate：网速太慢 log_off：注销 request_error：ajax请求报错 load_game_failed：游戏加载失败 verify_failed：验证失败 internal_error：内部错误
~	~	~	stateChangeReason	通过调用服务端接口释放游戏时,透传的reason
~	~	~	errorCode	错误码
mait	服务器维护	object	progress	soon：维护进度即将开始 start：维护开始 done：维护完成
timeout	游戏时间结束，但不结束游戏	object	interval	本次游戏时间，单位：秒
~	~	~	reason	提示信息
wait	排队	null	~	~
aljs	开始异步加载js文件	null	~	~
evnt	事件id	object	eventId	事件id
clst	发送countly日志	object	info	countly日志内容
qqup	云上调起了QQ应用	null	~	~
flsc	Flash加载	object	result	1：成功 0：失败
askn	询问是否排队	null	~	~
spdn	测速	object	speed	0：失败非0数字：测得的网速
alfn	异步加载js文件结束	object	result	1：成功 0：失败
vibf	videoPlayer Frame Ready	null	~	~
crtp	显示自动降低码率tips	object	minimum	当前码率是否最低码率 0：否 1：是
~	~	~	delay_less_minimum	是否低于最低码率 0：否； 1：是
crst	切换码率开始	object	source	当前码率
~	~	~	des	目标码率
cred	切换码率完成	object	result	0：失败； 1：成功
~	~	~	cur_rate	当前码率
~	~	~	method	自动手动模式； 0：手动； 1：自动
resolutionList	清晰度列表	object	list	ist：数组 [{id:,name:}…]
~	~	~	selected	当前选中清晰度id
delay	延迟数据	object	value	当前延迟数据，单位：MS
packetsLost	丢包率	object	value	当前丢包率，单位：百分比
openGallery	打开相册	_	_	_
openCamera	打开摄像头	_	_	_
share	分享	_	_	_
startLiveState	开始直播	object	result	0：失败； 1：成功
~	~	~	msg	失败提示语
applyPinCode	获取授权码	object	result	0：失败； 1：成功
~	~	~	cid	当前cid
~	~	~	pinCode	控制权转移所需授权码
~	~	~	msg	失败提示语
endLiveState	结束直播	object	result	0：失败； 1：成功
~	~	~	msg	失败提示语
seizingControl	获取控制权事件	object	result	0：失败； 1：成功
~	~	~	cid	控制权抢夺者cid
~	~	~	msg	失败提示语
getControl	获取控制权结果	object	result	0：失败； 1：成功
~	~	~	msg	失败提示语
newFileAppear	有新的可下载文件	object	image_name	文件名称
fileList	可下载文件列表	object	list	可下载文件列表 [name1,name2…] 排序为倒序。
downLoadFileInfo	下载文件状态	object	success	下载是否成功成为为true,失败为false
~	~	~	msg	失败时为错误信息描述
~	~	~	fileBold	当前下载文件的二进制流
~	~	~	fileType	当前下载文件的类型
~	~	~	fileSize	当前下载文件的大小
~	~	~	fileName	当前下载文件的名称
cancelDownLoadFail	取消下载失败原因	object	msg	失败原因描述只在取消失败时触发，成功不触发。

说明：’~’ 意思为同上

MessageHandler回调函数说明

游戏过程中的各种消息，都会通过MessageHandler回调函数传递，您可以在消息回调时进行相应的处理操作。以下为参数说明：

属性	类型	必选	说明
userId	string	否	目标userId
from	string	是	消息发送方标识
to	string	是	消息接收方标识
mid	string	是	消息ID
type	int	是	消息类型：固定值为1
ack	int	是	应答类型：固定值为0
payload	string	是	消息内容

4.2 启动游戏

完成初始化设置后即可调用游戏启动接口来启动游戏，请确认游戏包名、渠道号等信息正确，并确保相应游戏已经在海马云平台成功完成游戏包的上架及相关配置信息设定。

代码示例

Cloudplay.startSDK ('#example',{
    userinfo: {
        uId: '',
        utoken: ''
        uType：’’
    },
    pkg_name: '',
    appChannel: '',
    c_token: '',
    rotate: '',
    playingtime: '',
    configinfo: '',
    priority: 0,
    isArchive: '',
    extraId: '',
    protoData: '',
    payStr: ''
});

参数说明

参数名	类型	必选	说明
uId	string	是	自行定义32位以内a-z,0-9字符串
utoken	string	是	自行定义32位以内a-z,0-9字符串
uType	int	是	0:默认值， 5:超级账号
pkg_name	string	是	游戏包名称
appChannel	string	否	游戏渠道号
c_token	string	是	用来校验参数的有效性：生成算法详见本文档中的“cToken生成算法”
rotate	boolean	是	游戏的横竖屏属性：true为竖屏游戏；false为横屏游戏
playingtime	int	是	用户可以玩的总游戏时间，单位：毫秒，可联系营运人员配置
configinfo	string	是	免登录功能所需信息，如不使用，传任意非空字符串
priority	int	是	申请游戏服务的优先级；默认设置为0；值越大优先级越高
isArchive	boolean	否	是否存档：默认为true；true存档；false不存档；
extraId	string	否	预留字段，传空字符串
protoData	string	否	透传字段，服务器端状态同步接口透传使用
payStr	string	否	支付相关参数，默认为空字符串
archiveFromUserId	string	否	被读取文档用户 id
archiveFromBid	string	否	被读取文档 bid
noInputTimeout	number	否	用户无操作断开时长单位：秒
cid	string	否	抢夺控制权使用控制权拥有者cid
pinCode	string	否	抢夺控制权使用抢夺控制权授权码

4.3 停止游戏

需要停止游戏时，请调用该接口。

代码示例

Cloudplay.stopSDK(function(data){
    console.log('stopSDK callback:',data);
});

4.4 停止所有游戏

停止该用户在云端正在运行的所有游戏

代码示例

Cloudplay.stopAll();

4.5 显示/隐藏键位设置菜单

切换进入键位设置；默认为不显示键位设置菜单，调用显示键位设置菜单，再次调用隐藏键位设置菜单；

代码示例

Cloudplay.showKeyboardSet();

4.6 网页内全屏/退出网页内全屏

切换进入网页内全屏状态，或退出网页内全屏；默认为非网页内全屏，切换后为网页内全屏。再次调用为退出网页内全屏。

代码示例

Cloudplay.webPageFullScreenFn();

4.7 全屏/退出全屏

切换进入全屏状态，或退出全屏；默认为非全屏，切换后为全屏。再次调用为退出全屏。

代码示例

Cloudplay.fullScreenFn();

4.8 隐藏/显示丢包率

切换全屏状态下是否显示丢包率；默认为显示，切换后为不显示。再次调用为显示。

代码示例

Cloudplay.showDelayData();

4.9 切换分辨率

切换分辨率；传入清晰度id切换到对应的分辨率下。

代码示例

Cloudplay.switchResolution(id);

参数说明

参数名	类型	必选	说明
id	string	是	需要切换到的清晰度id

4.10 发送消息到服务器

用户需要发送消息到服务器时调用这个接口
代码示例

Cloudplay.sendMessage(payload);

参数说明

参数名	类型	必选	说明
payload	string	是	发送的数据信息

4.11 获取cid

获取当前游戏cid,游戏中调用返回 {cid:”00000000”} 游戏结束后调用返回 {cid:””}。

代码示例

Cloudplay.getCid()

4.12 获取推流地址域名

获取当前游戏推流地址域名,游戏中调用返回 “..***”。

代码示例

Cloudplay.getStreamingDomain();

4.13 上传图片到游戏

上传图片到游戏实例相册中。大小限制 1~5120KB。（备注：如需使用此功能，须引入<script src=”https://cdn.bootcss.com/crypto-js/3.1.9-1/crypto-js.js">\）

代码示例

调用方法

Cloudplay.upload({
    file: files[0],
    opType: 'upload_image',
    onSuccess: function (opType, file) {
        console.log(opType, file)
    },
    onError: function (opType, message) {
        console.log('wxy', opType, message)
    }
})

参数说明

参数名	类型	必选	说明
file	File	是	要上传的⽂件
opType	string	是	⽬前⽀持类型： upload_image
onSuccess	function	是	上传成功回调,
onError	function	是	上传失败回调

onSuccess回调说明

参数名	类型	必选	说明
file	File	是	上传成功的原始⽂件
opType	string	是	⽬前⽀持类型： upload_image

onError回调说明

参数名	类型	必选	说明
message	File	是	上传失败的原始⽂件
opType	string	是	当前上传类型：upload_image

4.14 开启直播

开启直播。传入房间号与直播推流地址开启直播。

代码示例

Cloudplay.startLiving(roomId,streamerUrl);

参数说明

参数名	类型	必选	说明
roomId	string	是	直播房间号
streamerUrl	string	是	直播推流地址

4.15 关闭直播

关闭直播。传入房间号关闭直播。

代码示例

Cloudplay.endLiving(roomId);

参数说明

参数名	类型	必选	说明
roomId	string	是	直播房间号

4.16 获取授权码

获取授权码。夺取控制权时使用。

代码示例

Cloudplay.getPinCode();

4.17 获取可下载文件列表

获取当前可下载文件列表。

代码示例

Cloudplay.getFileList(option);

参数说明

参数名	类型	必选	说明
size	number	否	文件列表数量，默认为 19 （最大值为20）
offset	number	否	第一个文件起始位置，默认为0
callback(fileList)	function	否	获取文件列表回调函数，同场景“fileList”返回值

4.18 下载指定文件

调用接口下载指定文件，下载动作结束是会触发场景回调。（备注：如需使用此功能，须引入<script src=”https://cdn.bootcss.com/crypto-js/3.1.9-1/crypto-js.js">\）

代码示例

Cloudplay.downLoadFile(name,function(file){});

参数说明

参数名	类型	必选	说明
name	string	是	准备下载的文件名称
function(file)	function	否	下载动作结束的回调函数
file	object	否	同场景回调 downLoadFileInfo 返回值

4.19 取消下载文件

调用接口取消下载文件，下载动作结束是会触发场景回调。

代码示例

Cloudplay.cancelDownLoadFile(name);

参数说明

参数名	类型	必选	说明
name	string	是	准备下载的文件名称

4.20 重置无操作时长计时器

重置无操作时长计时器

代码示例

Cloudplay.resetInputTimer();

5 场景说明

5.1 将游戏切换成前台

场景描述

用户点击“与QQ好友玩”按钮后，QQ应用会被调起并在前台显示；
QQ登录可能失败或用户不想继续登录，这时候系统不会把游戏切换到前台，需要接入方提供一个按钮，通过调用Cloudplay.bringUpApp()方法，把游戏切换到前台，并控制按钮的状态；
QQ登录成功后，系统自动把游戏切换到前台，游戏在前台的时候，调用Cloudplay.bringUpApp()，不会有任何其它影响；

函数原型

Cloudplay.bringUpApp()

代码示例

var oBackBtn = document.getElementById('back_btn');
oBackBtn.onclick = function(){
    Cloudplay.bringUpApp();
    oBackBtn.style.display = "none";
    sessionStorage.removeItem("qqupState");
}

5.2 QQ登录接入过程说明

用户在云游戏点击“与QQ好友玩”按钮后，SDK会通过接入方提供的onSceneChanged回调函数，通知接入方用户进入了 QQ 登录界面，此时接入方收到“qqup”消息后，提示用户QQ登录、以及QQ登录异地登录风控等信息。

代码示例

var oBackBtn = document.getElementById('back_btn');
onSceneChanged: function(sceneId, extraInfo) {
    if(sceneId == "qqup" || sessionStorage.getItem("qqupState")){
        sessionStorage.setItem("qqupState", "true");
        oBackBtn.style.display = "block";
        // QQ登录 do something;
    }
}

5.3 免登

该功能需要接入方配合开发，将用户信息传给SaaS-SDK，SaaS-SDK将接收到的信息与接入方提供的校验接口校验，校验通过则读取用户的存档数据开始游戏；校验不通过则通知接入方用户登录状态失效，如果不通知也可以在实例中输入用户名密码登录，此方案可选。

6 数据结构定义

6.1 cToken生成算法

根据userId, userToken, pkg_name, accessKeyID, channelId这几个字段合并成一个新的字符串。
对字符串进行 AES 处理并且配以accessKey(AES mode：ECB,pad：Pkcs7)。
对生成的字节数组进行SHA-1 处理。
再传化为新的字符串，这个字符串就是新生成的cToken

cToken 算法示例：

accessKey：32ff95eb0880face7c7be338608fdfe4（注：海马云分配）
uId：cpd301548
utoken：tokend2d23cc6522a50760fa027d1f9
pkg_name： com.hm.apk
accessKeyID：bid999889（注：海马云分配）
channelId：haimayun
合并字符串为：cpd301548tokend2d23cc6522a50760fa027d1f9com.hm.apkbid999889haimayun
cToken为：899453e46440ba04df6acb8c19261855bacf6547

7 键位配置说明

7.1 说明

1.wasd方向键：配置在游戏内方向轮位置，按下wasd进行游戏内人物上下左右移动操作。

2.自定义按键：配置在游戏内可以点击操作的位置，配置一个自定义按键例如”X”,在操作按下键盘X时，游戏内对应位置也会按下。

3.准星键：配置一个开启准星的按键，当用户按下键盘时游戏进入鼠标移动操作视角功能。再次按下时退出鼠标移动操作视角功能。

4.射击键：配置在游戏内攻击键上，可以实现在游戏内鼠标点击触发游戏攻击。

5.右键行走：配置在游戏内方向轮位置，当用户在画面内右键点击时，会操作人物向对应方向移动，右键长按移动人物也会跟随鼠标的方向进行移动。

6.智能施法：配置在游戏内需要选择方向释放的技能上，按下对应按键时会根据鼠标对应位置调整游戏技能释放方向，抬起按键时释放技能。

7.键位列表：点击可以展开键位列表，可以新建键位方案、删除键位方案、切换键位方案。

8.键位透明度：鼠标滑过显示键位透明度设置条，拖拽可以增加或者降低游戏内键位提示透明度。值越小越透明。

9.操作引导：点击展开游戏内键位配置引导图。

10.关闭键鼠配置：退出键位方案修改。

11.保存键鼠配置：退出并保存当前修改的键位方案。

12.游戏内是否显示键位提示：在游戏内是否显示键位提示，开启则显示，关闭则不显示。可以使用F2快速切换。

13.清除全部：清除正在编辑中键位方案内键位。

14.恢复默认：恢复当前键位方案到未修改前的状态，保存后无法恢复。

15.键鼠配置功能区域可以在游戏画面内自由拖拽，底部会预留键位透明度空间无法到达最底部，竖屏游戏时无法左右拖拽。

本篇文章对你是否有帮助？

更多建议

联系方式

您尚未登录

您尚未登录

推荐您使用PC浏览器访问

WEB_RTC SDK 开发指南

1 文档概述

2 名词解释

3 接入步骤

3.1 导入SDK

4 API接口

4.1 初始化

4.2 启动游戏

4.3 停止游戏

4.4 停止所有游戏

4.5 显示/隐藏键位设置菜单

4.6 网页内全屏/退出网页内全屏

4.7 全屏/退出全屏

4.8 隐藏/显示丢包率

4.9 切换分辨率

4.10 发送消息到服务器

4.11 获取cid

4.12 获取推流地址域名

4.13 上传图片到游戏

4.14 开启直播

4.15 关闭直播

4.16 获取授权码

4.17 获取可下载文件列表

4.18 下载指定文件

4.19 取消下载文件

4.20 重置无操作时长计时器

5 场景说明

5.1 将游戏切换成前台

5.2 QQ登录接入过程说明

5.3 免登

6 数据结构定义

6.1 cToken生成算法

7 键位配置说明

7.1 说明