HTML5 接入指南

安装 SDK

SDK 已作为公开包发布到 npm，并配有合适的 Typescript 类型定义，仅需在你的项目中安装即可。

npm

npm install @cloudgaming/paas-web @cloudgaming/rpc

Yarn

yarn add @cloudgaming/paas-web @cloudgaming/rpc

使用 SDK

导入 Game 并构建一个实例

import { Game } from '@cloudgaming/paas-web'

const game = new Game()

准备 DOM 结构

<div class="game-player">
  <div class="game-player__video-container">
    <video width="100%" height="100%" id="game_video"></video>
  </div>
</div>

示例中 game-player 等 class 均可自由定义，但请注意双层 div 结构不可变化。

最里层的 video 标签需要有 id，后续需要传入对应方法。

准备 CSS

.game-player {
  width: 100%;
  position: relative;
  overflow: hidden;
}

.game-player::before {
  display: block;
  content: ' ';
  width: 100%;
  padding-top: 56.25%; /* 16:9 */
}

.game-player__video-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}

这里需要将 .game-player 固定比例展现，在 CSS 中用到 padding-top 来保持固定比例。

如果你在上一步中修改了 class name，那这里的 CSS 也需要对应做出修改。

提示

如果需要对游戏画面进行定位，请对整个 .game-player DOM 进行定位，不要放大或裁剪其中的元素。

检查队列

无论当前是否需要排队，都需要调用该函数，用于检查排队情况、分配服务器。

调用该函数后，会得到排队信息和一些其它的返回值。

const { queuePosition } = await game.checkQueue({
  async getAuthToken() {
    return '' // 自定义获取 authToken 的逻辑，参考下文获取 Token 一节
  },
  gameName, // 游戏名，由庭宇 PaaS 分配
  gameArgs: {
    // 此处传入自定义的游戏启动参数，没有可忽略该字段
  },
  migrateSession: false, // 是否开启跨设备迁移会话，默认为否
})

if (queuePosition == null) { // 此处不可用 === ，也不可写作 if (queuePosition)
  // 无需排队，可以直接进入游戏
  startGame()
} else {
  // 需要排队，已在队列中
  showQueueUi()
}

排队

如果检查队列发现需要排队，那么开发者此时需要展示排队 UI。我们提供了一些事件，用以更新排队位置，或是指示可以开始游戏。

当排队轮到当前用户后，我们将为当前用户保留 1 分钟排队结果。此时，开发者应当展示排队成功的 UI，询问用户是否进入游戏。

根据产品逻辑，亦可以自动进入游戏，但可能造成资源浪费或是用户不知情的消费。

game.on('queueUpdate', (position) => {
  console.log(`当前排队位置：${position + 1}`)
  // position 是从 0 开始计数，故显示位置应当+1
})

game.on('canStartGame', () => {
  showStartGameUi()
})

启动游戏

当用户无需排队、或是排队轮到当前用户后，即可正式开始游戏。

console.log('正在尝试启动游戏')
await game.startGame(
  'game_video', // video 标签的 ID
  getStartToken, // startToken 函数，参考下文获取 Token 一节
  getRenewToken, // renewToken 函数，参考下文获取 Token 一节
  (progress) => console.log(`载入中，进度：${progress}%`)
)
console.log('游戏成功开始')

获取 Token

为了实现 PaaS 端与开发者后端之间鉴权、计费的逻辑，我们引入了三种 token，具体后端实现规范可参考客户后端实现规范。

对于前端开发者而言，需要与后端商量好获取三种 token 的方法，然后在前端逻辑中自行实现，将参数传递到后端，并将后端生成的 token 传入 SDK，SDK 将自动在合适的时候调用函数。

获取 Token 的三个函数签名如下：

Typescript

function getAuthToken(sessionId: string): Promise<string>
function getStartToken(sessionId: string): Promise<string>
function getRenewToken(sessionId: string, lastDeadline: number): Promise<string>

JSDoc

/**
 * @param sessionId string
 * @return Promise<string>
 */
function getAuthToken(sessionId)
/**
 * @param sessionId string
 * @return Promise<string>
 */
function getStartToken(sessionId)
/**
 * @param sessionId string
 * @param lastDeadline number
 * @return Promise<string>
 */
function getRenewToken(sessionId, lastDeadline)

同时我们也提供在线 demo 后端，请联系售前或技术以获取 demo 后端的地址，使用 demo 后端可在开发期间避免后端过早参与。

常见问题

在移动端或触屏设备上不响应触摸事件

当前我们尚未定义移动端或触屏设备的事件响应规则。业务方可根据自己的需要，将触屏定义为模拟鼠标点击，或是滑动的触摸板。