H5 SDK 开发指南

文档版本号：20221021-110

对应SDK版本号：master-3.52

变更说明：

SDK版本号	日期	更新内容
master-3.52	2022/10/21	1、开始游戏方法中新增resolutionId字段
master-3.49	2022/9/8	1、启动游戏时增加richData字段，供接入方业务控制透传
master-3.35	2022/3/17	1、修复部分场景下无法正常启动游戏 2、修复游戏启动异常时某些时机通过getCloudPlayStatusCode获取到的状态码为空的问题
master-3.27	2021/12/9	1、onSceneChanged回调函数的 stop场景，新增透传值errorCodeWithoutCid
master-3.24	2021/10/31	1、新增接口获取授权码 2、新增功能获取控制权 3、新增场景回调：获取授权码、获取控制权事件、获取控制权结果
master-3.21	2021/8/27	1、清晰度切换函数回调 Cloudplay.switchResolution(id,callback)

1 产品简介

欢迎使用海马云游戏服务，本文档主要介绍云游戏H5端SDK的接入流程及提供支持的API详情，适用于ARM游戏。

开发者通过接入海马云游戏SDK，可以实现云游戏的播放、停止、状态回调等各类控制操作和数据交互，在海马云游戏端到端全栈云服务能力基础上，为用户带来顺畅的云游戏体验。在开始接入SDK前，请确认您已经拥有海马云游戏平台接入方ID并创建了渠道号，并已经完成了在海马云游戏平台上传游戏包等相关准备工作。

2 快速开始

在接入SDK前，需要明确如下事项：

网页必须执行H5标准。
viewport必须设置为禁止缩放。
必须设定唯一的DOM节点，SDK将在这个节点内加载游戏。

2.1 导入SDK

直接导入SDK，saas-sdk将自动识别平台类型是Android还是iOS，并引入对应的播放器。

示例代码：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <link rel="stylesheet" type="text/css" href="./saas-sdk.css">
    <script src="./saas-sdk.js"></script>
</head>
<body>
    <div id="example"></div>
</body>
</html>

表2-1 文件说明

文件名	说明
saas-sdk.css	云游戏SDK的css样式
saas-sdk.js	云游戏SDK的js插件
saas-player-android.js	云游戏SDK的Android平台播放器
saas-player-ios.js	云游戏SDK的iOS平台播放器

2.2 初始化

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

示例代码：

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

表2-2 参数说明

参数	类型	必填项	说明
accessKeyID	string	是	接入方唯一ID（抢夺控制权时为被抢夺者accessKeyID）
channelId	string	是	接入方自行定义，主要方便接入方推广，如一个APK，发布到不同的推广平台时用不同channelId
isIgnoreResizeEvent	boolean	否	是否忽略SDK内部的resize事件。默认：false 忽略：true 不忽略：false
onSceneChanged	function	是	场景切换回调函数，详情请参见场景切换回调
MessageHandler	function	是	支付消息的回调函数，详情请参见消息回调

2.2.1 场景切换回调

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

表2-3 参数说明

sceneId	sceneId说明	extraInfo类型	extraInfo属性名	extraInfo属性说明
init	初始化中	null	-	-
play	开始游戏	null	-	-
stop	游戏结束	object	interval	本次游戏时间，单位为s
			reason	timeLimit：本次游戏时间已到 noOperation：无操作超时，默认20min，可联系运营人员修改配置 instanceError：云端实例出错 tokenExpire：Token过期失效 maintainServer：正在维护服务器 internalError：内部错误 instanceLimit：超过实例数的申请上限 queueLimit：排队人数过多，禁止排队 internal：主动停止游戏 tokenFailed：token鉴权失败 visibilitychangehide：切换到后台 needRefreshPage：需要刷新页面 normal：正常结束游戏 unsupportDevice：设备不支持 unsupportWechat：微信不支持 invalidDeviceId：无效的deviceId
			message	提示信息
			stateChangeReason	通过调用服务端接口释放游戏时,透传的reason
			errorCode	错误码（包含cid）
			errorCodeWithoutCid	错误码
maintain	服务器维护	object	progress	soon：维护进度即将开始 start：开始
			time	时间，单位为s
			message	提示信息
timeout	游戏时间结束，但不结束游戏	object	interval	本次游戏时间，单位为s
timeout	游戏时间结束，但不结束游戏	object	message	提示信息
remainingTime	剩余游戏时间	object	time	剩余可玩的游戏时间，单位为s
remainingTime	剩余游戏时间	object	countDown	true：需要倒计时 false：不需要倒计时
wait	排队	object	reason	showQueueInfo：显示当前的排队信息 applyGame：排队完成，正在进入游戏 whetherToQueue：是否进入排队，如果进入排队调用Cloudplay.enterQueue()，否则调用Cloudplay.outQueue()
			message	提示信息
			waitingPeople	等待人数
			waitingTotalNum	等待总人数
			waitingTime	预计等待时间，单位为s
totalTime	本次可玩游戏时间	object	time	单位为s
totalTime	本次可玩游戏时间	object	message	提示信息
reconnectingStatus	重连状态提示	object	message	提示信息
offline	断网提示	object	message	提示信息
warning	出错提示	object	message	提示信息
loadPlayer	加载播放器	object	result	true：成功 false：失败
qqup	云上调起了QQ应用	null	-	-
delay	画面延迟	object	delay	当前画面的延时，单位为ms。只有使用WebRTC播放器时才有此参数
packetsLost	丢包率	object	packetsLost	当前画面的丢包率，格式：%。只有使用WebRTC播放器时才有此参数
openGallery	打开相册	-	-	-
openCamera	打开摄像头	-	-	-
share	分享	-	-	-
crst	切换码率开始	object	source	当前码率
crst	切换码率开始	object	des	目标码率
cred	切换码率完成	object	result	0：失败 1：成功
			cur_rate	当前码率
			method	自动手动模式。 0：手动 1：自动
resolutionList	清晰度列表	object	list	list：数组 [{id:‘’,name:‘’}...]
resolutionList	清晰度列表	object	selected	当前选中清晰度id
newFileAppear	有新的可下载文件	object	image_name	文件名称
fileList	可下载文件列表	object	list	可下载文件列表 [name1,name2...] 排序为倒序
downLoadFileInfo	下载文件状态	object	success	下载是否成功 true：成功 false：失败
			msg	失败时为错误信息描述
			fileBold	当前下载文件的二进制流
			fileType	当前下载文件的类型
			fileSize	当前下载文件的大小
			fileName	当前下载文件的名称
cancelDownLoadFail	取消下载失败原因	object	msg	失败原因描述，只在取消失败时触发，成功不触发。
applyPinCode	获取授权码	object	result	0：失败 1：成功
			cid	当前cid
			pinCode	控制权转移所需授权码
			msg	失败提示语
seizingControl	获取控制权事件	object	esult	0：失败 1：成功
			cid	控制权抢夺者cid
			msg	失败提示语
getControl	获取控制权结果	object	result	0：失败 1：成功
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.startGame('example', {
    userInfo: {
        uId: '',
        uToken: '',
        uType: 0
    },
    pkgName: '',
    appChannel: '1',
    cToken: '',
    isPortrait: false,
    priority: 0,
    configInfo: '',
    playingtime: 1200,
    streamType: '1',
    isArchive: true,
    cid: '',
    protoData: '',
    extraId: '',
});

表2-5 参数说明

参数	类型	必填项	说明
uId	string	是	自行定义32位以内a-z、0-9字符串
uToken	string	是	自行定义32位以内a-z、0-9字符串
uType	int	是	默认传0
pkgName	string	是	游戏包名称
appChannel	string	否	游戏渠道号
cToken	string	是	用来校验参数的有效性
isPortrait	boolean	是	游戏的横竖屏属性。 true：竖屏游戏 false：横屏游戏
priority	int	是	申请游戏服务的优先级，默认设置为0，值越大优先级越高
configInfo	string	是	免登录功能所需信息，如不使用，传任意非空字符串
playingtime	int	是	用户可以玩的总游戏时间，单位为s
streamType	string	否	指定使用哪种Streaming。 1：WebRTC 0：H5Streaming
isArchive	boolean	否	是否存档。 true：存档 false：不存档默认为true
cid	int	否	游戏的cid，抢夺控制权时为被抢夺者cid
protoData	string	否	透传字段，服务器端状态同步方法透传使用
extraId	string	否	预留字段，传空字符串
archiveFromUserId	string	否	被读取文档用户id
archiveFromBid	string	否	被读取文档bid
componentType	number	否	组件类型。 0：activity 1：service 2：broadcast
componentName	string	否	指定的组件名，格式（packageName/componentName），如：com.happyelements.AndroidAnimal.**/com.happyelements.hellolua.MainActivity
action	string	否	组件对应的action
extraData	object	否	免登参数，详见表2-6 参数说明
viewResolutionWidth	number	否	游戏画面分辨率宽
viewResolutionHeight	number	否	游戏画面分辨率高
pinCode	string	否	抢夺控制权授权码，抢夺控制权使用，同时需要被抢夺者cid、accessKeyID
bitRate	number	否	清晰度码率（单位：KB，如：200、500、800）
autoPlayAudio	boolean	否	是否自动播放音频
richData	object	否	接入方业务控制透传参数
resolutionId	number	否	清晰度id

表2-6 参数说明

参数	类型	必填项	说明
booleanExtra	boolean	否	向Intent中添加Boolean
integerExtra	number	否	向Intent中添加Integer
integerArrayExtra	array	否	向Intent中添加Integer数组
integerListExtra	array	否	向Intent中添加Integer List
stringExtra	string	否	向Intent中添加String
stringArrayExtra	array	否	向Intent中添加String数组
stringListExtra	array	否	向Intent中添加String List
floatExtra	number	否	向Intent中添加Float
floatArrayExtra	array	否	向Intent中添加Float数组
floatListExtra	array	否	向Intent中添加Float List
longExtra	number	否	向Intent中添加Long
longArrayExtra	array	否	向Intent中添加Long数组
longListExtra	array	否	向Intent中添加Long List
componentNameExtra	string	否	向Intent中添加componentName
uriExtra	object	否	向Intent中添加uri

3 国际化

云游戏内部默认使用中文，若希望使用其他语言，则需要进行多语言设置。以英文为例，在导入SDK的html 中增加英文语言包。

示例代码：

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
    <link rel="stylesheet" type="text/css" href="./saas-sdk.css">
    <script src="./saas-sdk-en-US.js"></script>
    <script src="./saas-sdk.js"></script>
</head>
<body>
    <div id="example"></div>
</body>
</html>

4 API说明

4.1 停止游戏方法

需要停止游戏时，请调用该方法。

示例代码：

Cloudplay.stopGame(function(data){});

表4-1 回调函数返回数据说明

参数	类型	说明
code	int	0：成功非0：失败

4.2 音频播放方法

可以通过该方法控制音频播放，true表示播放，false表示静音。

示例代码：

Cloudplay.enableAudio(enabled);

表4-2 参数配置

参数	类型	必填项	说明
enabled	boolean	是	是否播放音频。 true：播放 false：静音

🔘说明：

因Safari浏览器的特殊性，初始时传true不会播放音频，需要用户点击后传true方可播放音频。
微信内置浏览器可以通过监听”WeixinJSBridgeReady”事件执行Cloudplay.enableAudio(true)来自动播放音频，否则也和Safari浏览器一样，需要用户点击后传true方可播放音频。

4.3 切换清晰度方法

切换清晰度，传入清晰度id切换到对应的分辨率下。异步处理切换清晰度，成功失败以场景回调为准。

示例代码：

Cloudplay.switchResolution(id,callback);

表4-3 参数说明

参数	类型	必填项	说明
id	string	是	需要切换到的清晰度id
callback	function	是	清晰度切换结束之后回调函数

5 进阶API

5.1 获取cid方法

通过该方法获取本次云游戏的cid。

示例代码：

Cloudplay.getCid();

表5-1 返回的数据说明

参数	类型	说明
cid	string	本次游戏的cid

5.2 获取游戏存档状态方法

查看当前用户的游戏是否正在存档中，如果是非”正在存档“状态可以进行游戏，否则需要等存档完成。

示例代码：

Cloudplay.getGameArchiveStatus({
    userInfo: {
        uId: '',
        uToken: '',
        uType: 0
    },
    pkgName: '',
    appChannel: '1',
    ifCanPlay: function (res) {
        // todo
    },
});

表5-2 参数配置

参数	类型	必填项	说明
uId	string	是	自行定义32位以内a-z、0-9字符串
uToken	string	否	自行定义32位以内a-z、0-9字符串
uType	int	否	默认传0
pkgName	string	是	游戏包名称
appChannel	string	否	游戏渠道号
ifCanPlay	function	是	回调函数

表5-3 回调函数返回数据说明

属性	类型	说明
code	int	0：获取信息成功 1：获取信息失败
errorMessage	string	报错信息
ifCanPlay	boolean	true：可以进行游戏 false：不可进行游戏

5.3 查询游戏是否存在存档方法

查看当前用户的当前游戏在云端是否存在存档。

示例代码：

Cloudplay.gameArchived({
    userInfo: {
        uId: '',
        uToken: '',
        uType: 0
    },
    pkgName: '',
    appChannel: '1',
    hasArchive: function (res) {
        // todo
    },
});

表5-4 参数配置

参数	类型	必填项	说明
uId	string	是	自行定义32位以内a-z、0-9字符串
uToken	string	否	自行定义32位以内a-z、0-9字符串
uType	int	否	默认传0
pkgName	string	是	游戏包名称
appChannel	string	否	游戏渠道号
hasArchive	function	是	回调函数

表5-5 回调函数返回的数据说明

属性	类型	说明
code	int	0：获取信息成功 1：获取信息失败
errorMessage	string	报错信息
hasArchive	boolean	true：有存档 false：没有存档

5.4 检测未释放游戏方法

检测当前用户在云端运行中的游戏信息，并获取未释放游戏的列表及每个游戏的详细信息，开发者可以根据游戏的详细信息进行启动游戏或停止游戏操作。

示例代码：

Cloudplay.checkPlayingGame({
    userInfo: {
        uId: '',
        uToken: '',
        uType: 0
    },
    playingGame: function (res) {
        // todo
    },
});

表5-6 参数配置

参数	类型	必填项	说明
uId	string	是	自行定义32位以内a-z、0-9字符串
uToken	string	否	自行定义32位以内a-z、0-9字符串
uType	int	否	默认传0
playingGame	function	是	回调函数

表5-7 回调函数返回数据说明

属性	类型	说明
code	int	0：获取信息成功 1：获取信息失败
errorMessage	string	报错信息
playingGame	array	[{appChannel: “”, cid: “”, pkgName: “”}] 未释放游戏的appChannel、cid、pkgName信息。如果数组为空，则没有未释放的游戏

5.5 获取云游戏状态码方法

收到stop场景时，可以调用该方法来获取云游戏状态码，来分析和统计游戏失败的原因。

示例代码：

Cloudplay.getCloudPlayStatusCode();

表5-8 返回数据说明

属性	类型	说明
100999001	int	无流地址，cid未获取成功（初始状态）
100999002	int	无流地址，cid获取成功，Socket连接失败
100999003	int	无流地址，cid获取成功，Socket连接成功，乒乓状态异常
100999004	int	无流地址，cid获取成功，Socket连接成功，乒乓状态正常
100999005	int	有流地址，video成功
100999006	int	有流地址，video失败，audio成功
100999007	int	有流地址，video失败，audio失败，input成功
100999008	int	有流地址，video失败，audio失败，input失败

5.6 云游戏结束信息上报方法

游戏结束时，通过该方法上报游戏是否正常结束。

示例代码：

Cloudplay.reportFinishInfo({
    finishCode: 0,
    pkgName: '',
    appChannel: '',
    gameId: '',
    cid: '',
    sdkVersion: '',
});

表5-9 参数配置

参数	类型	说明
finishCode	string	结束状态。 0：正常结束 1：超时结束 2：异常结束有SDK错误码 3：异常结束无SDK错误码
pkgName	string	云游戏包名
appChannel	string	云游戏渠道号
gameId	string	云游戏id号
cid	string	云游戏cid
sdkVersion	string	SDK版本号

5.7 获取网络请求数据方法

查看游戏申请过程中请求游戏信息以及连接游戏所用的时间。

示例代码：

Cloudplay.getNetInfo();

表5-10 返回参数说明

参数	类型	说明
url	string	网络请求的url
time	string	请求耗时
result	string	请求结果
msg	string	结果详细描述
uid	string	当前用户的uid
cid	string	当前云游的cid
action	string	请求的类型。长连接：access input连接：input 视频流：videoUrl 音频流：audioUrl action：actionId
transId	string	当前申请的唯一ID
packageName	string	请求的游戏包名
startTime	string	开始请求的时间
responseTime	string	请求结束的时间

5.8 发送消息到服务器方法

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

示例代码：

Cloudplay.sendMessage(payload);

表5-11 参数说明

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

5.9 获取视频流地址域名方法

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

示例代码：

Cloudplay.getStreamingDomain();

5.10 上传图片到游戏方法

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

表5-12 参数说明

参数	类型	必填项	说明
file	File	是	要上传的文件
opType	string	是	文件类型，目前支持类型：upload_image
onSuccess	function	是	上传成功回调
onError	function	是	上传失败回调

*表5-13 onSuccess回调说明 *

参数	类型	必填项	说明
file	File	是	上传成功的原始文件
opType	string	是	目前支持类型：upload_image

*表5-14 onError回调说明 *

参数	类型	必填项	说明
message	File	是	上传成功的原始文件
opType	string	是	当前上传类型：upload_image

5.11 发送文本到云端剪贴板方法

发送文本内容到云端剪贴板。该方法会返回一个布尔值，表示内容是否已发送。

示例代码：

Cloudplay.sendWSMessage({
        type: 'clipboard',
        data: [{itemType: 'text/plain', itemData: 'abc'}],
        mid: (Math.random() * 1000000).toString().replace('.', ''),
        callback: function (messageId, successed, message) {
            console.log('sendWSMessage id: ' + messageId + ', result: ' + successed + ', description: ' + message);
        }
    }
);

表5-15 参数说明

参数	类型	必填项	说明
type	String	是	消息类型，目前支持：clipboard剪贴板
data	Array	是	发送的内容
mid	String	是	消息唯一ID
callback	function	是	发送结果回调

*表5-16 onSuccess回调说明 *

参数	类型	必填项	说明
messageId	String	是	发送是填入的消息ID
successed	Boolean	是	是否发送成功
message	String	是	发送结果说明

5.12 设置游戏画面方向方法

控制游戏画面是横向还是竖向。使用此方法时initSDK中的isIgnoreResizeEvent必须设置为true。此方法必须在获取到第一帧后使用。

示例代码：

Cloudplay.setScreenDirection(direction);

表5-17 参数说明

参数	类型	必填项	说明
direction	string	是	画面方向。 landscape：横向 portrait：竖向

5.13 获取可下载图片列表方法

获取当前可下载图片列表。
该方法会返回一个表示获取可下载图片列表请求是否已发送的布尔值。

示例代码：

Cloudplay.getFileList(option);

表5-18 参数说明

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

5.14 下载指定图片方法

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

⚠注意：

使用此功能，须引入<script src=”https://cdn.bootcss.com/crypto-js/3.1.9-1/crypto-js.js">\。

示例代码：

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

表5-19 参数说明

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

5.15 取消下载图片方法

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

示例代码：

Cloudplay.cancelDownLoadFile(name);

表5-20 参数说明

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

5.16 获取授权码方法

夺取控制权时使用。

示例代码：

Cloudplay.getPinCode();

🔘说明：

使用控制权转移功能时需要注意，抢夺者需使用被抢夺者cid、accessKeyID，以及被抢夺者提供的pinCode。抢夺控制权为游戏操控权限抢夺，不会重新启动游戏。

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

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

示例代码：

Cloudplay.updateGameUID(data, callback);

表5-21 参数说明

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

表5-22 data参数说明

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

表5-23 回调函数参数说明

参数	类型	必填项	说明
code	number	是	状态码（0：成功）
msg	string	是	提示信息

5.18 云游戏中远端实例状态通知接口

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

示例代码：

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

表5-24 分享事件返回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：朋友圈分享安卓分享无需传值
type	String	android_share：安卓系统分享事件 weixin_share：微信分享事件 weibo_share：微博分享事件 qq_share：QQ分享事件
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：扩展字段

5.19 开始下载保活方法（X86不支持）

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

示例代码：

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

5.20 结束保活方法（X86不支持）

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

示例代码：

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

5.21 获取文件列表方法（X86不支持）

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

示例代码：

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

5.22 注册监听帧变化方法

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

示例代码：

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

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

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

5.23 移除监听帧变化方法

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

示例代码：

Cloudplay.removeRequestVideoFrameCallback()

6 场景说明

6.1 排队管理

实例数不足时，会发生排队现象。通过SDK提供的方法，可以让用户选择是否进入排队队列，具体过程如下图所示。

示例代码：

function sceneChanged(sceneId, extraInfo) {
    if (sceneId == 'wait' && extraInfo.reason == 'whetherToQueue') {
        var queueOrNot = confirm("是否进入排队");//可以设计漂亮UI提示代替这部分内容
        if (queueOrNot == true) {
            Cloudplay.enterQueue();
        } else {
            Cloudplay.outQueue();
        }
    }
}

6.2 游戏时间

启动游戏时，可以设定可玩游戏时间。当可玩游戏时间用尽，系统会停止游戏，并通过回调函数通知SDK。可玩游戏时间可以通过Cloudplay.startGame()中的playingtime来设置，单位为s。例如设置3600s，即60min。

示例代码：

Cloudplay.startGame('example', {
    pkgName: testPackageName,
    userInfo: {
        uId: testUserId,
        uToken: testUserToken,
        uType: 0
    },
    priority: 0,
    extraId: '',
    playingtime: 3600,
    configInfo: 'a',
    cToken: generateCToken(),
    isArchive: false,
    isPortrait: false,
    appChannel: testAppChannel
});

在游戏过程中，可能收到sceneId为totalTime、remainingTime、timeout等场景，收到这些场景时，可以给用户相应的消息提示：

totalTime：本次游戏可玩时长。
remainingTime：游戏剩余时间。
timeout：游戏时间结束，但不结束游戏。

示例代码：

function sceneChanged(sceneId, extraInfo) {
    if (sceneId == 'totalTime') {
        alert('你本次游戏可玩时长' + extraInfo.time + '秒。');
    }

    if (sceneId == 'remainingTime') {
        alert('你的游戏时间还剩' + extraInfo.time + '秒。');
    }

    if (sceneId == 'timeout') {
        alert('你已经玩了' + extraInfo.interval + '秒,游戏时间已用完。');
    }
}

6.3 检测进行中的游戏

检测当前用户在云端运行的游戏，根据cid信息可进行启动游戏或者停止游戏操作。

示例代码：

function sceneChanged(sceneId, extraInfo) {
    if (sceneId == 'stop' && extraInfo.reason == 'instanceLimit') { 
        //用户启动实例超限制时的场景
        Cloudplay.checkPlayingGame({ 
            //检测该用户在云端正在进行中的游戏
            userInfo: {
                uId: '',
                uToken: '',
                uType: 0
            },
            playingGame: function (res) {
                if (res.code == 0 && res.playingGame.length > 0) {
                    // 用户在云端有正运行的实例
                    var startGameData = {
                        userInfo: {
                            uId: "hmTest01",
                            uToken: "hmTest",
                            uType: 0
                        },
                        priority: 0,
                        extraId: '',
                        playingtime: 3600,
                        configInfo: 'a',
                        isArchive: false,
                        isPortrait: false,
                        cid: res.playingGame[0].cid, // 处理请查询返回的数据
                        pkgName: res.playingGame[0].pkgName, // 处理请查询返回的数据
                        appChannel: res.playingGame[0].appChannel, // 处理请查询返回的数据
                        cToken: generateCToken() //根据查询的数据生成cToken，生成cToken方法请参看demo
                    }
                    Cloudplay.startGame('example', startGameData); //利用查询的数据启动游戏
                }
            },
        });
    }
}

6.4 将游戏切换到前台

场景描述：

用户点击“与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');
}

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

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

更多建议

联系方式

您尚未登录

您尚未登录

推荐您使用PC浏览器访问

H5 SDK 开发指南

1 产品简介

2 快速开始

2.1 导入SDK

2.2 初始化

2.2.1 场景切换回调

2.2.2 消息回调

2.3 开始游戏

3 国际化

4 API说明

4.1 停止游戏方法

4.2 音频播放方法

4.3 切换清晰度方法

5 进阶API

5.1 获取cid方法

5.2 获取游戏存档状态方法

5.3 查询游戏是否存在存档方法

5.4 检测未释放游戏方法

5.5 获取云游戏状态码方法

5.6 云游戏结束信息上报方法

5.7 获取网络请求数据方法

5.8 发送消息到服务器方法

5.9 获取视频流地址域名方法

5.10 上传图片到游戏方法

5.11 发送文本到云端剪贴板方法

5.12 设置游戏画面方向方法

5.13 获取可下载图片列表方法

5.14 下载指定图片方法

5.15 取消下载图片方法

5.16 获取授权码方法

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

5.18 云游戏中远端实例状态通知接口

5.19 开始下载保活方法（X86不支持）

5.20 结束保活方法（X86不支持）

5.21 获取文件列表方法（X86不支持）

5.22 注册监听帧变化方法

5.23 移除监听帧变化方法

6 场景说明

6.1 排队管理

6.2 游戏时间

6.3 检测进行中的游戏

6.4 将游戏切换到前台

6.5 QQ登录接入过程说明