Version History

• Version 1.1.0
  • 在 遊戲後端實作「開始遊戲」API 這邊遊戲後端需要開新遊戲，並記錄 roomId & 參與的玩家。 Request:， Request 新增屬性 roomId
  • 新增步驟: 遊戲後端實作「結束遊戲」API 在任何時刻，遊戲結束時，後端必須呼叫大平台的「結束遊戲」API

Requirements

• 遊戲已在某雲端上架
• 對 JWT (JSON Web Token) 有基本的理解

Integration Steps

1. 拿自己的 JWT

   1. 由 https://lobby.gaas.waterballsa.tw 登入

   2. 登入後，開 F12 找 Cookie (name = _token)，你會看到以下

      %22eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImlrN3l5VkpoM3pFSW1hLWduZ2lTRCJ9.eyJpc3MiOiJodHRwczovL2Rldi0xbDBpeGp3OHlvaHNsdW9pLnVzLmF1dGgwLmNvbS8iLCJzdWIiOiJnb29nbGUtb2F1dGgyfDEwODI0Mjc1MjAyMjAzNDkzNjYwNCIsImF1ZCI6WyJodHRwczovL2FwaS5nYWFzLndhdGVyYmFsbHNhLnR3IiwiaHR0cHM6Ly9kZXYtMWwwaXhqdzh5b2hzbHVvaS51cy5hdXRoMC5jb20vdXNlcmluZm8iXSwiaWF0IjoxNjkyNDU4MzE3LCJleHAiOjE2OTI0NjE5MTcsImF6cCI6IjBaN2huRGxkNXRyUHFpMnYwbGxvQlk3NE1IZERZR0V5Iiwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCBvZmZsaW5lX2FjY2VzcyJ9.m_2_IkZ1OLhoq3hlXzIpLiZy3z4D_zbVGAhQFAnsLMDtoD-F0Bn08lqGh80jLos36VBFSd8jwDkEiGvufjz2b9DYQAUqaX-Vvs5rFZ3gRt1jC5oZeOtoDrd4ZD8PJFiia1yL2ohQZC7caVaqjeHhbYlCWbANMrVakKTOKdd7Pk5MQLo3xDio-o1y6kheDxVj33XMkj19C4jF8C479s4JNbFKRe9_0RcefmQ2IZl1g7aPJB7ULtmjRGc1KM37Z_KK7GopKIzRdQK-0HKjZXKaFnnXuXmqG3tAiB77vyM9uT-HBB2jjAa42f1rPA1WQKTjw5asIyUUQOBAv6GYPjdAPQ%22
      

   3. 頭尾去掉 %22 就是 JWT Token 了

      <aside> ℹ️ 拿著 JWT Token 到 https://jwt.io 就可以「解析」內容喔

      注意: 「解析」 ≠ 「驗證」

      </aside>

2. 到大平台註冊遊戲

   POST /games
   Host: <https://api.gaas.waterballsa.tw>
   Authorization: Bearer {遊戲開發者的JWT}
   
   {
   	"uniqueName": "{小寫英文不能與其他遊戲重複，主要由系統使用}",
     "displayName": "{公開的遊戲名字}",
     "shortDescription": "{簡單的遊戲說明}",
     "rule": "{複雜的遊戲規則}",
     "imageUrl": "{遊戲圖片，自行host}",
     "minPlayers": {最少人數},
     "maxPlayers": {最多人數},
     "frontEndUrl": "{前端主機}",
     "backEndUrl": "{後端主機}",
   }
   

   例:

   POST /games
   Host: <https://api.gaas.waterballsa.tw>
   Authorization: Bearer {遊戲開發者的JWT}
   
   {
     "uniqueName": "majong",
     "displayName": "明星3缺1麻將",
     "shortDescription": "麻將遊戲『明星3缺1麻將』台灣最多人玩16張麻將",
     "rule": "基本上，要縱橫牌桌，必須先瞭解牌局三階段的不同，然後針對不同的階段，祭出不同的打法去應戰，才能勝券在握、所向無敵。",
     "imageUrl": "<https://placekitten.com/300/300>",
     "minPlayers": 4,
     "maxPlayers": 4,
     "frontEndUrl": "<https://frontend.majong.com>",
     "backEndUrl": "<https://backend.majong.com>",
   }
   

3. 遊戲後端實作「心跳」API 這支 API 會由大平台的 API Gateway 定時的檢查，代表你的服務有在線上。 Request

   GET /health
   HOST: {你的後端主機}
   

   Response

   <aside> ⛔ Http Status Code 必須是 2xx，否則視為 Server Down。 Response body 這裡無限制，回空白也是可以。

   </aside>

4. 遊戲後端實作「開始遊戲」API 這邊遊戲後端需要開新遊戲，並記錄 roomId & 參與的玩家。 Request:

   POST /games
   Host: {你的後端主機}
   Authorization: Bearer {房主的Jwt}
   
   {
     "roomId": "room_385abe92e39a3",
   	"players": [{
         "id": "6497f6f226b40d440b9a90cc",
         "nickname": "板橋金城武"
      }, {
         "id": "6498112b26b40d440b9a90ce",
         "nickname": "三重彭于晏"
      }, {
         "id": "6499df157fed0c21a4fd0425",
         "nickname": "蘆洲劉德華"
      }, {
         "id": "649836ed7fed0c21a4fd0423",
         "nickname": "永和周杰倫"
      }]
   }
   

   <aside> ⚠️ 目前不支援遊戲專屬的設定，例

   • 遊戲難度: 低，中，高 (不是每組遊戲都有難度)

   </aside>

   Response:

   {
   	"url": "https://{你的前端主機}/games/{gameId}
   }
   

5. 實作 JWT 驗證

   欄位	值
   Issuer / Authority / Domain	https://dev-1l0ixjw8yohsluoi.us.auth0.com/
   Audience	https://api.gaas.waterballsa.tw

6. 呼叫大平台 API GET /users/me

   Request

   GET /users/me
   HOST: api.gaas.waterballsa.tw
   Authorization: Bearer {playerJwt}
   

   Response

   {
   	"id": "{MongoDb.ObjectId}",
   	"email": "{userEmail}",
   	"nickname": "板橋金城武"
   }
   

7. 遊戲前端實作「開始遊戲」頁面 預期在 Browser 打 https://{遊戲前端主機}/games/{gameId}?token={playerJwt} 即可開始讀取遊戲

   <aside> ⚠️ 遊戲前端自己負責儲存 JWT Token

   • local storage
   • session storage
   • … etc

   </aside>

8. 遊戲後端實作「結束遊戲」API 在任何時刻，遊戲結束時，後端必須呼叫大平台的「結束遊戲」API

   POST /rooms/{roomId}:endGame
   Host: api.gaas.waterballsa.tw
   Authorization: Bearer {該遊戲內任一玩家的Jwt}
   
   // 空 Body
   

完成以上步驟後，就可以開始自己的遊戲流程。

Q & A