WEB_RTC SDK 开发指南

1 WEB SDK 开发指南

对应SDK版本号：master-3.23

文档版本号	Release Note	日期
master-3.21.1	1、获取授权码 2、开启直播 3、关闭直播 4、检测是否支持直播 5、获取控制权	2021年7月2日

1.1 1 文档概述

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

1.2 2 名词解释

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

1.3 3 接入步骤

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

说明：

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

1.3.1 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插件

1.4 4 API接口

1.4.1 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	~	~
alfn	异步加载js文件结束	object	result	1：成功 0：失败
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	失败提示语

说明：’~’ 意思为同上

MessageHandler回调函数说明

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

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

1.4.2 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

1.4.3 4.3 停止游戏

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

代码示例

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

1.4.4 4.4 停止所有游戏

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

代码示例

Cloudplay.stopAll()

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

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

代码示例

Cloudplay.showKeyboardSet()

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

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

代码示例

Cloudplay.webPageFullScreenFn()

1.4.7 4.7 全屏/退出全屏

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

代码示例

Cloudplay.fullScreenFn()

1.4.8 4.8 隐藏/显示丢包率

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

代码示例

Cloudplay.showDelayData()

1.4.9 4.9 切换分辨率

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

代码示例

Cloudplay.switchResolution(id)

参数说明

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

1.4.10 4.10 发送消息到服务器

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

Cloudplay.sendMessage(payload)

参数说明

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

1.4.11 4.11 获取cid

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

代码示例

Cloudplay.getCid()

1.4.12 4.12 获取推流地址域名

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

代码示例

Cloudplay.getStreamingDomain()

1.4.13 4.13 上传图片到游戏

上传图片到游戏实例相册中。大小限制 1~5120KB

代码示例

调用方法

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

1.4.14 4.14 开启直播

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

代码示例

Cloudplay.startLiving(roomId,streamerUrl)

参数说明

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

1.4.15 4.15 关闭直播

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

代码示例

Cloudplay.startLiving(roomId)

参数说明

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

1.4.16 4.16 获取授权码

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

代码示例

Cloudplay.getPinCode()

1.5 5 场景说明

1.5.1 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");
}

1.5.2 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;
    }
}

1.5.3 5.3 免登

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

1.6 6 数据结构定义

1.6.1 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

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

更多建议

联系方式

您尚未登录

您尚未登录

推荐您使用PC浏览器访问

WEB_RTC SDK 开发指南

1 WEB SDK 开发指南

1.1 1 文档概述

1.2 2 名词解释

1.3 3 接入步骤

1.3.1 3.1 导入SDK

1.4 4 API接口

1.4.1 4.1 初始化

1.4.2 4.2 启动游戏

1.4.3 4.3 停止游戏

1.4.4 4.4 停止所有游戏

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

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

1.4.7 4.7 全屏/退出全屏

1.4.8 4.8 隐藏/显示丢包率

1.4.9 4.9 切换分辨率

1.4.10 4.10 发送消息到服务器

1.4.11 4.11 获取cid

1.4.12 4.12 获取推流地址域名

1.4.13 4.13 上传图片到游戏

1.4.14 4.14 开启直播

1.4.15 4.15 关闭直播

1.4.16 4.16 获取授权码

1.5 5 场景说明

1.5.1 5.1 将游戏切换成前台

1.5.2 5.2 QQ登录接入过程说明

1.5.3 5.3 免登

1.6 6 数据结构定义

1.6.1 6.1 cToken生成算法