您尚未登录

登录

推荐您使用PC浏览器访问

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

WEB_RTC SDK 开发指南

WEB SDK 开发指南

版本号:master-3.3

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>
    <script src="cp_ui.js"></script>
</head>
<body>
    <div id="example"></div>
</body>
</html>
文件名 说明
saas-sdk.css 云游戏WebSDK依赖的css样式
saas-sdk.js 云游戏WebSDK依赖的js插件(注意:saas-sdk.js在cp_ui.js之前引用)
cp_ui.js 云游戏WebSDK依赖的js插件

4 API接口

4.1 初始化

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

代码示例

Cloudplay.initSDK({
    accessKeyID: '',
    channelId: '',
    pkg_name: '',
    isHideToolBar: '',
    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:内部错误
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 当前丢包率,单位:百分比

说明:’~’ 意思为同上

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 支付相关参数,默认为空字符串

4.3 停止游戏

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

代码示例

Cloudplay.stopSDK();

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 发送的数据信息

5 场景说明

5.1 将游戏切换成前台

场景描述

  1. 用户点击“与QQ好友玩”按钮后,QQ应用会被调起并在前台显示;
  2. QQ登录可能失败或用户不想继续登录,这时候系统不会把游戏切换到前台,需要接入方提供一个按钮,通过调用Cloudplay.bringUpApp()方法,把游戏切换到前台,并控制按钮的状态;
  3. 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生成算法

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

cToken 算法示例:

accessKey:32ff95eb0880face7c7be338608fdfe4(注:海马云分配)
userId:cpd301548
userToken:tokend2d23cc6522a50760fa027d1f9
pkg_name: com.hm.apk
accessKeyID:bid999889(注:海马云分配)
channelId:haimayun
合并字符串为:cpd301548tokend2d23cc6522a50760fa027d1f9com.hm.apkbid999889haimayun
cToken为:899453e46440ba04df6acb8c19261855bacf6547