Kadou Game SDK

目录

• 快速开始
• 初始化参数
• 内部状态说明
• 事件监听列表
• 方法列表
• 用户行为常量

快速开始

Game 侧

import { GameRuntime, SDKEvents, Behaviors } from 'kadou-game-sdk';

const sdk = new GameRuntime({
  role: 'game',
  debug: true
});

sdk.init();

sdk.gameReady({
  gameId: 'demo-game'
});

sdk.on(SDKEvents.GAME_START, () => {
  console.log('收到开始游戏');
});

初始化参数

new GameRuntime(options) 支持的主要参数如下：这些参数来自 GameManager 构造函数。

| 参数 | 说明 | |---|---| | root | UI 挂载根节点，游戏侧浮层挂载到这里，默认 document.body | | debug | 是否开启调试日志 | | role | 当前角色，host 或 game | | selfWindow | 当前窗口对象，默认 window | | targetWindow | 目标窗口，通常是 iframe.contentWindow | | targetOrigin | postMessage 的目标域名 | | allowedOrigins | 允许接收消息的域名白名单 | | source | 消息来源标识，默认 KADOU_GAME_SDK |

示例

const sdk = new GameRuntime({
  root: document.getElementById('app'),
  role: 'host',
  targetWindow: iframe.contentWindow,
  targetOrigin: '*',
  allowedOrigins: ['*'],
  source: 'KADOU_GAME_SDK',
  debug: true
});

内部状态说明

SDK 内部维护以下状态：

{
  sdkReady: false,
  gameReady: false,
  started: false,
  paused: false,
  destroyed: false
}

字段说明

| 字段 | 含义 | |---|---| | sdkReady | SDK 是否已就绪 | | gameReady | 游戏是否已就绪 | | started | 游戏是否已开始 | | paused | 游戏是否处于暂停 | | destroyed | 管理器是否已销毁 |

事件监听列表

使用方式

sdk.on(SDKEvents.GAME_START, (payload, message, context) => {
  console.log('game start', payload);
});

基础事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.MESSAGE | message | 收到任意消息时触发 | | SDKEvents.SDK_READY | sdk:ready | SDK 就绪 | | SDKEvents.GAME_LOAD | game:load | 请求加载游戏 | | SDKEvents.GAME_LOADED | game:loaded | 游戏加载完成 | | SDKEvents.GAME_LOADING | game:loading | 游戏加载中 | | SDKEvents.GAME_READY | game:ready | 游戏已准备完成 | | SDKEvents.GAME_START | game:start | 游戏开始 | | SDKEvents.GAME_RESTART | game:restart | 游戏重新开始 | | SDKEvents.GAME_PAUSE | game:pause | 游戏暂停 | | SDKEvents.GAME_RESUME | game:resume | 游戏恢复 | | SDKEvents.GAME_FINISH | game:finish | 游戏结束 | | SDKEvents.GAME_DESTROY | game:destroy | 游戏销毁 | | SDKEvents.GAME_RANK | game:rank | 查看排行榜 |

配置与系统事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.CONFIG_UPDATE | config:update | 配置更新 | | SDKEvents.SYSTEM_ERROR | system:error | 系统错误上报 | | SDKEvents.THEME_UPDATE | theme:update | 主题更新 |

页面浮层事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.PAGE_START_SHOW | page:start:show | 显示开始页 | | SDKEvents.PAGE_END_SHOW | page:end:show | 显示结束页 |

答题相关事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.ANSWER_START | answer:start | 开始答题 | | SDKEvents.ANSWER_SUBMIT | answer:submit | 提交答案 | | SDKEvents.ANSWER_FEEDBACK | answer:feedback | 答题反馈 |

题目弹窗事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.QUESTION_POPUP_SHOW | question:popup:show | 显示题目弹窗 | | SDKEvents.QUESTION_POPUP_CLOSE | question:popup:close | 关闭题目弹窗 | | SDKEvents.QUESTION_POPUP_FEEDBACK | question:popup:feedback | 弹窗反馈 |

题目切换事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.QUESTION_PREV | question:prev | 上一题 | | SDKEvents.QUESTION_NEXT | question:next | 下一题 |

音量、扩展、心跳事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.VOLUME_CHANGE | volume:change | 音量改变 | | SDKEvents.EXTENSION_EMIT | extension:emit | 扩展消息 | | SDKEvents.HEARTBEAT_PING | heartbeat:ping | 心跳 ping | | SDKEvents.HEARTBEAT_PONG | heartbeat:pong | 心跳 pong |

动作事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.ACTION_START | action:start | 动作开始 | | SDKEvents.ACTION_END | action:end | 动作结束 | | SDKEvents.ACTION_FEEDBACK | action:feedback | 动作反馈 |

用户行为事件

| 事件名 | 常量值 | 说明 | |---|---|---| | SDKEvents.USER_BEHAVIOR | user:behavior | 用户行为上报 |

方法列表

基础方法

init()

启动消息监听。

destroy()

销毁管理器、消息总线、浮层和全部监听。

send(type, payload, meta)

统一发送消息。

sdk.send('custom:type', { a: 1 });

生命周期控制

startGame(data)

开始游戏。会更新本地状态、先本地派发 GAME_START，再发送消息。

restartGame(data)

重新开始游戏。

pauseGame(data)

暂停游戏。

resumeGame(data)

恢复游戏。

finishGame(result)

结束游戏。

destroyGame(data)

通知对端销毁游戏。

错误与状态方法

reportError(error)

支持上报 Error 对象或普通对象。

getState()

获取状态快照。

isReady()

检查是否 ready。

用户行为上报

trackBehavior(payload)

自动生成的快捷发送方法

| 方法名 | 说明 | |---|---| | loadGame(data) | 加载游戏 | | gameLoading(data) | 游戏加载进度 | | gameLoaded(data) | 游戏加载完成 | | startAnswer(data) | 开始答题 | | submitAnswer(data) | 提交答案 | | answerFeedback(data) | 答题反馈 | | showQuestionPop(data) | 显示题目弹窗 | | closeQuestionPop(data) | 关闭题目弹窗 | | questionPopFeedback(data) | 题目弹窗反馈 | | prevQuestion(data) | 上一题 | | nextQuestion(data) | 下一题 | | startAction(data) | 动作开始 | | endAction(data) | 动作结束 | | actionFeedback(data) | 动作反馈 | | setVolume(data) | 调整音量 | | emitExtension(data) | 发扩展事件 |

用户行为常量 Behaviors

游戏级流程

• GAME_ENTER
• GAME_START
• GAME_PAUSE
• GAME_RESUME
• GAME_EXIT
• GAME_FINISH
• GAME_RESTART
• RESULT_SHOW

关卡级流程

• LEVEL_ENTER
• LEVEL_COMPLETE
• LEVEL_EXIT

题目级流程

• QUESTION_ENTER
• QUESTION_LEAVE
• QUESTION_COMPLETE
• QUESTION_RETRY
• QUESTION_NAVIGATE

作答行为

• ANSWER_SUBMIT
• ANSWER_SKIP
• ANSWER_TIMEOUT

反馈与辅助

• FEEDBACK_SHOW
• HINT
• MEDIA

通用交互

• INTERACTION

异常类

• SUBMIT_FAIL
• SUBMIT_RETRY
• NETWORK_ERROR
• RESOURCE_LOAD_FAIL

其他

• OTHER

行为上报字段

行为数据统一采用下面结构：

{
  // 提交器生成不用传
  "recordId": "",
  "totalScore": "",
  "startTime": "", // 毫秒时间戳
  "endTime": "", // 毫秒时间戳
  "duration": "",// 毫秒
  "meta": {
    "sessionId": "",
    "cardId": "",
    "templateId": "",
    "activityId": "",
    "classId": "",
    "roomId": ""
  },
  "extra": {}, // 扩展字段 --- 预留
  "client": { //设置信息 --- 预留 
    "platform": "",
    "deviceType": ""
  },

  //游戏传递
  "actorName": "", // 玩家名称 队伍名 || 分组名|| 用户名
  "level": 1, // 当前关卡
  "questionId": "", // 系统题目id
  "questionType": "", // 系统题目题型
  "itemIndex": "", // 答题子项索引
  "stem": { // 答题子项题干
    "text": "",
    "image": "",
    "sound": ""
  },
  "answer": { // 子项正确答案
    "text": "",
    "image": "",
    "sound": ""
  },
  "userAnswer": { // 用户选择答案
    "text": "",
    "image": "",
    "sound": ""
  },

  "correct": null, // true || false || null
  "score": 0, // 子项得分
  "maxScore": 0, // 游戏最大得分


  "action": , // 用户行为动作 如提交答案 BehaviorActions.QUESTION_COMPLETE
  "actionComment": "" //关于行为的描述文字
}