介接流程

三個步驟讓你的遊戲擁有排行榜、雲端存檔和成就系統。

複製// 也可透過 API 建立 App（需先在控制台登入取得 JWT token）
POST https://game.upliftorch.com/api/game/developer/app
Authorization: Bearer <your_jwt_token>
{ "appName": "My Awesome Game" }
// → 回傳 apiKey

{
  "data": {
    "developerAppId": 1,
    "appName": "My Awesome Game",
    "apiKey": "gs_a1b2c3d4e5f6...",
    "isActive": true
  }
}

複製// 提交分數到排行榜
const res = await fetch('https://game.upliftorch.com/api/game/leaderboard/score', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'gs_your_api_key',
  },
  body: JSON.stringify({
    game_id: 'my-game',
    player_id: 'player-001',
    player_name: 'Alice',
    score: 9999,
  }),
})

{ "data": { "rank": 1, "is_new_best": true, "best_score": 9999 } }

複製const res = await fetch(
  'https://game.upliftorch.com/api/game/leaderboard?gameId=my-game&limit=10',
  { headers: { 'x-api-key': 'gs_your_api_key' } }
)
const { data } = await res.json()
// data.entryList = [{ rank, player_name, score, ... }, ...]

認證方式

所有 API 呼叫都需要在 header 帶上你的 API Key：

x-api-key: gs_your_api_key_here

Base URL

https://game.upliftorch.com

共通回應格式

所有 API 回應格式為 { "data": ... }，錯誤時回傳 { "error": "error_code", "message": "描述" }。

API 測試台

填入你的 API Key 和參數，即時測試 API 呼叫。

提交分數

POST/api/game/leaderboard/score

提交玩家分數到排行榜。若玩家已有紀錄且新分數更佳，會自動更新。

Request Body

{
  "data": {
    "rank": 3,
    "is_new_best": true,
    "best_score": 9999
  }
}

查詢排行榜

GET/api/game/leaderboard

取得指定遊戲的排行榜資料。

Query Parameters

{
  "data": {
    "game_id": "my-game",
    "sort_order": "desc",
    "total": 42,
    "entryList": [
      { "rank": 1, "player_name": "Alice", "score": 9999, ... }
    ]
  }
}

查詢玩家排名

GET/api/game/leaderboard/player

Query Parameters

{ "data": { "rank": 5, "player_name": "Alice", "score": 8500 } }

寫入存檔

PUT/api/game/save

儲存遊戲進度到雲端。每位玩家可以有多個存檔槽位。

Request Body

複製await fetch('/api/game/save', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json', 'x-api-key': 'gs_...' },
  body: JSON.stringify({
    game_id: 'my-game',
    player_id: 'player-001',
    slot_key: 'slot1',
    save_data: { level: 5, hp: 100, inventory: ["sword", "shield"] },
  }),
})

讀取存檔

GET/api/game/save

Query Parameters

列出存檔

GET/api/game/save/list

列出玩家在指定遊戲的所有存檔槽位。參數同上（gameId、playerId）。

刪除存檔

DELETE/api/game/save

Request Body

列出成就

GET/api/game/achievement

Query Parameters

{ "data": [{ "slug": "first-win", "name": "首勝", "requiredCount": 1, "xpReward": 100 }] }

更新成就進度

POST/api/game/achievement/progress

增加玩家成就進度。達到 requiredCount 時自動解鎖。

Request Body

{ "data": { "slug": "first-win", "newlyUnlocked": true, "xpReward": 100 } }

查詢玩家成就

GET/api/game/achievement/player

Query Parameters

Widget SDK — 一行嵌入排行榜

不想自己刻 UI？用我們的 Widget SDK 一行嵌入排行榜和成就元件。

方法一：HTML 屬性（最簡單）

複製<!-- 放一個容器 -->
<div id="gs-leaderboard" data-game-id="my-game"></div>

<!-- 引入 SDK -->
<script src="https://game.upliftorch.com/sdk/game-service.js"
  data-api-key="gs_your_api_key">
</script>

方法二：JS API

複製// 初始化
GameService.init({ apiKey: 'gs_your_api_key' })

// 渲染排行榜（支援 dark / light 主題）
GameService.renderLeaderboard('#my-board', {
  gameId: 'my-game',
  limit: 10,
  theme: 'dark',
})

// 渲染成就
GameService.renderAchievements('#my-ach', {
  gameId: 'my-game',
  playerId: 'player-001',
})

查看 Widget Demo 頁面看實際效果。