您尚未登录

登录

您尚未登录

登录

推荐您使用PC浏览器访问

确定
  • 开发者中心
  • >
  • 云游戏
  • >
  • SDK开发指南
  • >
  • 云游戏基础SDK
  • >
  • WEB
  • >
  • v6.10.1

文档版本号:20220923-104

对应SDK版本号:master-6.10.1

变更历史:

版本号 日期 更新内容
master-6.10.1 2022/9/23 1、新增更新用户信息和游戏时长方法
2、启动游戏时增加richData字段,供接入方业务控制透传
3、新增国际化
4、新增安卓、微信、QQ、微博分享场景回调agentShare,新增分享事件返回json字段介绍
5、新增 Cloudplay.startHangUp() 开始下载保活
6、新增 Cloudplay.stopHangUp() 结束保活
7、新增 Cloudplay.getBigFileList() 获取文件列表
8、新增 Cloudplay.updateGameUID() 更新用户信息和游戏时长
9、新增 Cloudplay.requestVideoFrameCallback() 注册监听帧变化
10、新增 Cloudplay.removeRequestVideoFrameCallback() 移除监听帧变化
11、新增自定义工具栏参数toolbarDomId
master-3.30 2021/11/23 1、WASD等功能键支持随窗口大小变化而改
master-3.27 2021/9/5 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
master-3.21.1 2021/7/2 1、获取授权码
2、开启直播
3、关闭直播
4、检测是否支持直播
5、获取控制权

1 产品简介

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

2 快速开始

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

🔘说明:

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

2.1 导入SDK

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

代码示例:

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

表2-1 文件名说明

文件名 说明
saas-sdk.css 云游戏WebSDK依赖的css样式
saas-sdk.js 云游戏WebSDK依赖的js插件
saas-sdk-en-US.js 云游戏WebSDK切换多语言使用的语言包,按需引入(调用Cloudplay.initSDK()之前加载完成,调用后修改无效)

2.2 初始化

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

函数原型:

Cloudplay.initSDK({
    accessKeyID: '',
    channelId: '',
    pkg_name: '',
    isHideToolBar: false,
    onSceneChanged: function(sceneId, extraInfo) {
        console.log('sceneId:'+sceneId,extraInfo);
        if(sceneId == 'play') {
            alert('游戏开始了');
        }
        if(sceneId == 'vibf') {
            alert('画面第一帧加载完成');
        }
    },
    MessageHandler: function(message) {
        console.log('got message:',message);
    }
});

表2-2 参数说明

参数 类型 必填项 说明
accessKeyID string 接入方唯一ID
channelId string 接入方自行定义,主要方便接入方推广需要,如一个APK,发布到不同的推广平台时用不同channelId
pkg_name string 游戏包名称
isHideToolBar boolean 是否隐藏toolbar
false:不隐藏(默认值)
true:隐藏
toolbarDomId string 自定义工具栏节点id,(自定义dom需在#example内为子元素,否则窗口缩放时工具栏位置将无法跟随),sdk不处理工具栏位置,需接入方自行调整全屏非全屏工具栏位置
onSceneChanged function 场景切换回调函数。详情请参见场景切换回调
MessageHandler function 支付消息的回调函数。详情请参见消息回调

2.2.1 场景切换回调

游戏过程中的各个场景切换,会通过onSceneChanged回调函数传递,可以在场景回调时进行相应的处理操作。

表2-3 参数说明

sceneId sceneId说明 extraInfo类型 extraInfo属性名 extraInfo属性说明
init 初始化中 null
play 开始游戏 object cid 本次游戏的cid
cur_rate 游戏当前码率
vibf 游戏画面第一帧 object cid 本次游戏的cid
stop 游戏结束 object interval 当次游戏时间,单位为s
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 错误码
errorCodeWithoutCid 错误码
cid 本次游戏的cid
timeout 游戏时间结束,但不结束游戏 object interval 本次游戏时间,单位为s
reason 提示信息
wait 排队 null
evnt 事件id object eventId 事件id
qqup 云上调起了QQ应用 null
flsc Flash加载 object result 1:成功
0:失败
askn 询问是否排队 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 失败原因描述,只在取消失败时触发,成功不触发
videoStreamInfo 视频流信息 object
videoFps 视频帧率,取不到为-1
bitRate 视频码率,取不到为-1
packetsLostRate 丢包率,取不到为-1
currentDelayMs 帧网络耗时,取不到为-1
decodeDelay 帧解码耗时,取不到为-1
renderDelay 帧渲染耗时,取不到为-1
frameSize 帧大小,取不到为-1
jitterBuffer 抖动,取不到为-1
framesReceived 收到的总帧数,取不到为-1
receiveFrameSize 收到帧的总大小,取不到为-1
delay 网络延迟,取不到为-1
codecImplementationName 编解码器名称,取不到为空字符串
codecName 解码器名称,取不到为空字符串
newBigFile 新文件通知 object fileState 文件状态。
0:文件开始创建
1:文件创建完成
name 文件名称
url 文件下载地址
type 文件
duration 文件时长(文件类型为视频格式时该属性生效),单位s
size 文件大小 (单位Byte)

2.2.2 消息回调

游戏过程中的各种消息,都会通过MessageHandler回调函数传递,可以在消息回调时进行相应的处理操作。

表2-4 参数说明

参数 类型 必填项 说明
userId string 目标userId
from string 消息发送方标识
to string 消息接收方标识
mid string 消息ID
type int 消息类型,固定值为1
ack int 应答类型,固定值为0
payload string 消息内容

2.3 开始游戏

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

函数原型:

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

表2-5 参数说明

参数名 类型 必填项 说明
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 用来校验参数的有效性
rotate boolean 游戏的横竖屏属性
true:竖屏游戏
false:横屏游戏
playingtime int 用户可以玩的总游戏时间,单位为ms,可联系营运人员配置
configinfo string 免登录功能所需信息,如不使用,传任意非空字符串
priority int 申请游戏服务的优先级,默认设置为0,值越大优先级越高
isArchive boolean 是否存档
true:存档
false:不存档
默认为true
extraId string 预留字段,传空字符串
protoData string 透传字段,服务器端状态同步接口透传使用
payStr string 支付相关参数,默认为空字符串
archiveFromUserId string 被读取文档用户id
archiveFromBid string 被读取文档bid
noInputTimeout number 用户无操作断开时长,单位为s
cid string 抢夺控制权使用,控制权拥有者cid
pinCode string 抢夺控制权使用,抢夺控制权授权码
viewResolutionWidth number 游戏画面分辨率的宽度
viewResolutionHeight number 游戏画面分辨率的高度
richData object 接入方业务控制透传参数

3 API说明

3.1 停止游戏方法

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

函数原型:

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

3.2 停止所有游戏方法

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

函数原型:

Cloudplay.stopAll();

3.3 显示/隐藏键位设置菜单方法

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

函数原型:

Cloudplay.showKeyboardSet();

3.4 网页内全屏/退出网页内全屏方法(X86不支持)

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

函数原型:

Cloudplay.webPageFullScreenFn();

3.5 全屏/退出全屏方法

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

函数原型:

Cloudplay.fullScreenFn();

3.6 隐藏/显示丢包率方法

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

函数原型:

Cloudplay.showDelayData();

3.7 切换清晰度方法

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

函数原型:

Cloudplay.switchResolution(id);

表3-1 参数说明

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

4 进阶API

4.1 获取cid方法

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

函数原型:

Cloudplay.getCid()

4.2 开始直播方法

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

函数原型:

Cloudplay.startLiving(roomId,streamerUrl);

表4-1 参数说明

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

4.3 停止直播方法

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

函数原型:

Cloudplay.endLiving(roomId);

表4-2 参数说明

参数名 类型 必填项 说明
roomId string 直播房间号

4.4 获取视频流地址域名接口(X86不支持)

游戏中调用该方法返回当前游戏视频流地址域名。

函数原型:

Cloudplay.getStreamingDomain();

4.5 发送消息到服务器方法

用户需要发送消息到服务器时调用这个接口。
该方法会返回一个表示信息是否已发送的布尔值。

函数原型:

Cloudplay.sendMessage(payload);

表4-3 参数说明

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

4.6 上传图片到游戏方法(X86不支持)

上传图片到游戏实例相册中。大小限制 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)
    }
})

表4-4 参数说明

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

*表4-5 onSuccess回调说明 *

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

*表4-6 onError回调说明 *

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

4.7 获取可下载图片列表方法(X86不支持)

获取当前可下载图片列表。

函数原型:

Cloudplay.getFileList(option);

表4-7 参数说明

参数名 类型 必填项 说明
size number 图片列表数量,默认为 19 (最大值为20)
offset number 第一个图片起始位置,默认为0
callback(fileList) function 获取图片列表回调函数,同场景“fileList”返回值

4.8 下载指定图片方法(X86不支持)

调用接口下载指定图片,下载动作结束时会触发场景回调。
该方法会返回一个表示下载请求是否已发送的布尔值。

函数原型:

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

表4-8 参数说明

参数名 类型 必填项 说明
name string 准备下载的图片名称
function(file) function 下载动作结束的回调函数
file object 同场景回调 downLoadFileInfo 返回值

4.9 取消下载图片方法(X86不支持)

调用接口取消下载图片,下载动作结束时会触发场景回调。
该方法会返回一个表示取消下载请求是否已发送的布尔值。

函数原型:

Cloudplay.cancelDownLoadFile(name);

表4-9 参数说明

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

4.10 获取授权码方法

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

函数原型:

Cloudplay.getPinCode();

4.11 重置无操作时长计时器方法

游戏启动后,重置无操作超时计时器时调用此函数。

函数原型:

Cloudplay.resetInputTimer();

4.12 查询sdk版本号

调用此函数,可以查询sdk当前版本号。

函数原型:

Cloudplay.version();

4.13 游戏截图方法(仅X86支持)

示例代码:

Cloudplay.captureGameImage({
    cid: 20153482,
    opType: 1,
    txId: "a71de3de53",
    interval: "",
    format: "png",
    size: "1",
    pixel: "1920x1080",
    uploadType: "http",
    uploadUrl: "https://www.haimacloud.com/",
}, function({code, errorMsg}){
    console.log(code);    // 0:请求成功
    console.log(errorMsg);    // 失败原因
});

表4-10 参数说明

参数名 类型 必填项 说明
cid String|Integer 当前游戏的cid
opType Integer 业务类型,1-截图,2-开始周期性截图,3-停止周期性截图
txId String 事务ID,每次调用传入的值保持唯一性, 消息重发时该字段维持不变
interval String 指令间隔 单位毫秒,默认1000,最小1000毫秒,最大60000毫秒,代表间隔n毫秒执行一次截图。 当opType等于2时该字段有效
format String 图片格式,如:png
size String 单张图片大小,单位MB, 默认1 当opType等于1或2该字段有效
pixel String 分辨率,格式宽x高, 默认1920x1080 当opType等于1或2该字段有效
uploadType String 图片上传协议类型,缺省为:http
uploadUrl String 图片上传地址, 由租户业务侧指定,必须是post请求

4.14 控制权分配方法(仅X86支持)

示例代码:

Cloudplay.controlPowerDistribute({
    cid: 20153482,
    controlInfos: [{cid:"156315615", position: 1},{cid:"841651561", position: 0}]
}, function({code, controlInfos, errorMsg}){
    console.log(code);    // 0:请求成功
    console.log(controlInfos);    // 分配结果
    console.log(errorMsg);    // 失败原因
});

表4-11 参数说明

参数名 类型 必填项 说明
cid String|Integer 当前主控游戏的cid
controlInfos Object[] 分配数据,cid: 主控或从控的cid;position:控制权位置

4.15 控制权查询方法(仅X86支持)

示例代码:

Cloudplay.controlPowerQuery({
    cid: 20153482,
}, function({code, controlInfos, errorMsg}){
    console.log(code);    // 0:请求成功
    console.log(controlInfos);    // 分配结果
    console.log(errorMsg);    // 失败原因
});

表4-12 参数说明

参数名 类型 必填项 说明
cid String|Integer 当前主控游戏的cid

4.16 输入法切换方法(仅X86支持)

示例代码:

Cloudplay.sendInputSwitch();

4.17 设置鼠标移动速度方法(仅X86支持)

示例代码:

Cloudplay.setMouseMoveRatio(ratio);

表4-13 参数说明

参数名 类型 必填项 说明
ratio Float 移动速度值:0.1 — 0.9

4.18 更新用户信息和游戏时长方法

在用户转换身份时,更新云玩用户的相关信息和游戏时长,并能够继续云玩

示例代码:

Cloudplay.updateGameUID(data, callback);

表4-14 参数说明

参数 类型 必填项 说明
data object 需要更新的信息,详见表4-15 data参数说明
callback function 更新用户信息和游戏时长之后回调函数

表4-15 data参数说明

参数 类型 必填项 说明
playingTime number 游戏时长(单位:ms)
userInfo object 用户信息
cToken string 更新的 cToken,用来校验参数的有效性
tip string totalTime 场景回调的提示信息

表4-16 回调函数参数说明

参数 类型 必填项 说明
code number 状态码(0: 成功)
msg string 提示信息

4.19 云游戏中远端实例状态通知(X86不支持)

用户在云游戏中安卓分享、微信分享、QQ分享、微博分享,SDK透传场景值agentShare。

示例代码:

function sceneChanged(sceneId, extraInfo) {
    if (sceneId == 'agentShare') {
        console.log('sceneId: agentShare ', extraInfo);
    }
}

表4-17 分享事件返回json字段说明

key value 说明
cid String 本次云玩cid
bid String 本次云玩bid
mid String 本次云玩mid
action String 分享事件的action
componentName String Intent 指定的组件
pkgName String intent指定包名,如系统分享指定包名进行分享
content String 分享的文本内容
fileList Array [/xxx/xxx/a.png,xxx/xxx/b.png],当分享图片的时候,由fileList返回,包含了每张图片的绝对路径信息,支持多张图片信息
scene String 微信分享的类型。好友分享、朋友圈分享,不是微信分享则为空。
friend:好友分享
moment:为朋友圈分享
android:分享无需传值
type String android_share:安卓系统分享事件
weixin_share:微信分享事件
weibo_share:微博分享事件
qq_shareQQ:分享事件
shareType String SHARE_IMAGE_WITH_TEXT:图文
SHARE_IMAGE_ONLY:纯图片
SHARE_TEXT:纯文本
SHARE_VIDEO:视频
share_link:链接
title String 分享的标题
extraInfo String webUrl:链接分享
mimeType:系统分享
videoUrl:视频分享
share_qq_ext_str:扩展字段

4.20 开始下载保活方法(X86不支持)

当需要下载文件时,调用Cloudplay.startHangUp(),开始下载保活。

示例代码:

Cloudplay.startHangUp({
    downloadList: ["fileName"],
    hangUpTime: 60,
    Cutoff: false
}, function (options) {
    console.log(options);
})

4.21 结束保活方法(X86不支持)

需要结束下载保活状态时,调用Cloudplay.stopHangUp()方法,结束当前下载保活,如果调用开始下载保活时选择的是断流模式,会恢复推流。

示例代码:

Cloudplay.stopHangUp(function (options) {
    console.log("stopHangUp", options)
})

4.22 获取文件列表方法(X86不支持)

调用Cloudplay.getBigFileList()获取文件列表。调用Cloudplay.getBigFileList()方法后会通过回调函数返回当前可以下载的文件列表。

示例代码:

Cloudplay.getBigFileList(function (fileList) {
    console.log(fileList);
});

4.23 注册监听帧变化方法

当需要监听帧变化时,调用Cloudplay.requestVideoFrameCallback(),开始注册监听事件。

示例代码:

Cloudplay.requestVideoFrameCallback(function (options,frameInfo) {
    console.log(options,frameInfo);//frameInfo为帧相关参数,受浏览器版本限制,非固定返回值,会缺失。
})

表4-18 回调函数参数说明

参数 类型 必填项 说明
code number 状态码。
0:正常
1:浏览器不支持
2:当前流类型不支持
number number 自增序号,number类型
timestamp number 当前帧对应的时间戳
isRestart boolean 是否重新开始播放视频

4.24 移除监听帧变化方法

当需要结束帧变化监听事件时,调用Cloudplay.removeRequestVideoFrameCallback(),移除监听。

示例代码:

Cloudplay.removeRequestVideoFrameCallback()

5 场景说明(X86不支持)

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

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

更多建议

请输入您的建议