玩家啟動遊戲流程

遊戲啟動流程圖

遊戲請求端點

遵從服務間認證文件，API 端點：

https://{GameProviderEndpoint}/api/{Version}/UA

URL 參數列表

欄位	描述
GameProviderEndpoint	Game Provider 提供的 API Domain
Version	Game Provider 的 API 版本號

JSON Payload 參數

欄位	描述	類型	需求
player		object
player.id	玩家唯一識別碼，由 Licensee 提供	string	Required
player.nickname	玩家顯示名稱	string	Optional
player.language	玩家偏好的語言	string	Optional
player.currency	玩家使用的貨幣	string	Required
player.session		string	Optional
launch		string	Required
config		object
config.playMode	遊戲模式	"real_money", "credit", "demo"	Required
config.urls	其他選項	{type: string, url: string}[]	Optional

• 型別為 object 的欄位，若子欄位的需求皆為 optional，其欄位也會被標注為 optional

Player 相關設定

• player.id：Player 在 Licensee 系統上的唯一識別碼。
• player.nickname：在部份可互動桌台遊戲 (e.g. baccarat)，若玩家需要識別名稱可填入該欄位；否則將由 Game Provider 隨機生成遮罩後的 ID (e.g. Player-61535yuh)。
• player.language：現代的 HTML 5 遊戲通常允許在遊戲內調整語系，該欄位會嘗試讓遊戲切換至此語系；若遊戲端不支援，則使用預設語系。
• player.currency：請參考貨幣代碼。
• player.session：若 Licensee 需要限制玩家的連線時間，可設定此欄位。當 Game Provider 發送錢包扣款需求時，將會使用此欄位值而非 player.id。

Launch 相關設定

launch 使用URI Based-on RFC3986¹ 來表達遊戲啟動的所有參數與階層關係：

• yac://:licensee['/' :agents ...]/_/:gameId['/' :unit ...]['?' :params]['&' :more_params ...]
• yac://:licensee['/' :agents ...]/@/:lobby['/' :gameId]['/' :unit ...]['?' :params]['&' :more_params ...]

範例：

yac://asia-platform-1/agent1/subagent/c/_/baccart001
└┬┘   └──────┬──────┘ └───────┬───────┘   └───┬────┘
scheme  licensee         agent-layer        gameId

名稱	用途	需求
scheme	固定為字串 "yac"	Required
licensee	Licensee 的識別碼	Required
agent-chain	代理層級	Optional
_	分割字元(僅包含遊戲)	Condition
@	分割字元(包含大廳)	Condition
gameId	Game Provider 提供的遊戲識別碼	Required
unit	遊戲的更小單元，例如桌子、座位(由Game Provider 定義)	Required
params	保留給 Licensee 客製化的參數	Optional

分割字元：

• _ 後方僅允許放置 gameId 與可選的 unit
• @ 後首個 Path 片段為 lobby，其後的 gameId 與 unit 皆為可選

params 與 more_params

• params 於 ? 使用 KEY=VALUE 或 KEY:TYPE=VALUE 表示
  1. promotion=false 解析成 { "promotion": "false" }
  2. promotion:bool=false 解析成 { "promotion": false }
  3. TYPE 支援 string, bool, number，預設使用 string 解析
• more_params 若超過一個參數，首個參數後使用 & 連接多個 params

---

• 無代理，進入 baccart001 遊戲

  yac://asia-platform-1/_/baccart001
  └┬┘   └──────┬──────┘   └───┬────┘
  scheme  licensee         gameId
  

• 包含代理 agent1 直接進入 ac2501 的 002 桌

  yac://asia-platform-1/agent1/_/ac2501/2
  └┬┘   └──────┬──────┘ └──┬─┘   └─┬──┘ └tableId
  scheme  licensee    agent-layer  gameId
  

• 包含多個代理並直接進入 ac2501 的 002 桌，且座位指定9號

  yac://asia-platform-1/agent1/subagent/c/_/ac2501/2/9
  └┬┘   └──────┬──────┘ └───────┬───────┘   └─┬──┘ │ └ seatId
  scheme  licensee         agent-layer      gameId └ tableId
  

• 無代理，進入大廳且預設廳別選用 poker

  yac://asia-platform-1/@/lobby?category=poker
  └┬┘   └──────┬──────┘   └─┬─┘ └────┬───────┘
  scheme  licensee        lobby      query params
  

• 無代理，包含大廳且直接進入 vip 廳別的 baccarat01 遊戲

  yac://asia-platform-1/@/lobby/baccarat01/?category=vip
  └┬┘   └──────┬──────┘   └─┬─┘ └───┬────┘  └─────┬────┘
  scheme  licensee        lobby   gameId     query params
  

• 有多個代理，包含大廳且直接進入 vip 廳別的 baccarat01 遊戲，並帶入多個客製化參數

  yac://asia-platform-1/agent1/agent2/@/lobby/baccarat01/?category=vip&param=1&maxBet=100&promo:bool=false
  └┬┘   └──────┬──────┘└──────┬─────┘   └─┬─┘ └───┬────┘  └───────────────────────┬──────────────────────┘
  scheme  licensee       agent-layer      lobby   gameId                       query params
  

保留的 Params Key

本系統遊戲啟動參數以 URI 表達。 URI 能通過標準化的字串，同時描述資源位置與啟動參數，並天然支援層級結構與擴展。
且大多程式語言都有支援解析與建立 URI 的函式庫。

保留名稱	用途
campaign	行銷活動識別碼，用於統計或推廣追蹤。
category	使用作廳別分類。
token	留給 Player 用來放置驗證權杖。

以上三個是保留的 Params Key，請勿使用。

若 Licensee 需要 Game Provider 額外處理啟動參數，請聯繫 KAM

Game 相關設定

• config.playMode：
  1. "credit" 使用玩家餘額下注 (預設值)
  2. "demo" 則不對錢包扣款。
  3. "real_money" 等同於設定 "credit" 相同，相容舊有系統而保留。
• config.urls：允許 Licensee 設定一些特殊的網址，需與 Game Provider 協調如何使用
  1. "lobby": "https://game-provider.lobby.com/baccarat"
  2. "lobby": "https://licensee.lobby.com/baccarat"
  3. 以大廳來說，可能存在 Game Provider 實作的大廳，與 Licensee 提供的大廳。可使用此參數決定退出遊戲時的返回位置。

Schema Define

DeclareJSON Schema

declare interface UserAuthRequest {
  player: {
    id: string;
    nickname?: string;
    language?: string;
    currency: string;
    session?: string;
  };
  launch: string;
  config?: {
    playMode?: "credit" | "credit" | "demo";
    urls?: { type: string; url: string }[];
  };
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "player",
    "launch"
  ],
  "properties": {
    "player": {
      "type": "object",
      "required": ["id", "currency"],
      "properties": {
        "id": { "type": "string" },
        "nickname": { "type": "string" },
        "language": { "type": "string" },
        "currency": { "type": "string" },
        "session": { "type": "string" }
      },
    },
    "launch": {
      "type": "string"
    },
    "config": {
      "type": "object",
      "properties": {
        "playMode": {
          "type": "string",
          "enum": ["credit", "demo"]
        },
        "urls": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type","url"],
            "properties": {
              "type": {"type": "string"},
              "url": { "type": "string", "format": "uri"}
            },
            "additionalProperties": false
          }
        }
      }
    }
  }
}

請求範例

最小請求示範所有可選請求示範

curl -X POST "https://api.game-provider.example.com/api/v1/UA" \
  -H "content-type: application/json" \
  -H "yac-client-id: asia-platform-1" \
  -H "yac-timestamp: 1772532662" \
  -H "yac-nonce: 8f3c9a1e7b" \
  -H "authorization: ECDSA-SHA256 MEUCIAxFDTqxDSQqkhWVoBPVPkLpZ2legE+jdSrmc56GXdc6AiEA+XOgxPad1YFScBdP6VoSAr01zzdGzPGKR017MAfjNUk=" \
  -d '{
    "player": {
      "id": "player-918273",
      "currency": "USD"
    },
    "launch": "yac://asia-platform-1/agent1/subagent/@/lobby/baccarat01?category=vip&campaign=summer2026&promo:bool=false",
    "config": {
      "playMode": "credit",
    }
  }'

curl -X POST "https://api.game-provider.example.com/api/v1/UA" \
  -H "content-type: application/json" \
  -H "yac-client-id: asia-platform-1" \
  -H "yac-timestamp: 1772532662" \
  -H "yac-nonce: 8f3c9a1e7b" \
  -H "authorization: ECDSA-SHA256 MEUCIAxFDTqxDSQqkhWVoBPVPkLpZ2legE+jdSrmc56GXdc6AiEA+XOgxPad1YFScBdP6VoSAr01zzdGzPGKR017MAfjNUk=" \
  -d '{
    "player": {
      "id": "player-918273",
      "nickname": "LuckyPlayer",
      "language": "en",
      "currency": "USD",
      "session": "sess_WFAQL8GkrabBS7xYVNpo"
    },
    "launch": "yac://asia-platform-1/agent1/subagent/@/lobby/baccarat01?category=vip&campaign=summer2026&promo:bool=false",
    "config": {
      "playMode": "credit",
      "urls": [
        {
          "type": "lobby",
          "url": "https://licensee.example.com/lobby/baccarat"
        }
      ]
    }
  }'

---

成功回應失敗回應

entry 將會回應遊戲網址，將 token 作為 Querystring

{
  "entry": "https://fake.example.org",
  "token": "eyJhbGciOiJFUzI1NiJ9.eyJpZCI6InBsYXllci05MTgyNzMiLCJjdXJyZW5jeSI6IlVTRCIsInBsYXlNb2RlIjoiY3JlZGl0IiwibGF1bmNoIjp7Im1vZGUiOiJsb2JieSIsImxpY2Vuc2VlIjoiYXNpYS1wbGF0Zm9ybS0xIiwiYWdlbnRzIjpbImFnZW50MSIsInN1YmFnZW50Il0sImxvYmJ5IjoibG9iYnkiLCJnYW1lSWQiOiJiYWNjYXJhdDAxIiwidW5pdHMiOltdLCJwYXJhbXMiOnsiY2F0ZWdvcnkiOiJ2aXAiLCJjYW1wYWlnbiI6InN1bW1lcjIwMjYiLCJwcm9tbzpib29sIjoiZmFsc2UifX0sImlzcyI6ImlkZW50aXR5LmVyaWNhc2luby5vcmciLCJzdWIiOiJhc2lhLXBsYXRmb3JuLTE6cGxheWVyLTkxODI3MyIsImF1ZCI6ImdhbWUtcHJvdmlkZXIuZXJpY2FzaW5vLm9yZyIsImlhdCI6MTc3MzExNzM4MSwiZXhwIjoxNzczMTE3OTgxfQ.I6u12uTO2-0yA32aSJXxa0Taco57XNL4k3--HUvyfT_yOrFH0pvykUzFNrP9hfbwjIvllJd7jn7K8oFTHNkRJA"
}

依照此回應，遊戲啟動網址應為https://fake.example.org?token=eyJhbGciOiJFUzI1NiJ9.eyJpZCI6InBsYXllci05MTgyNzMiLCJjdXJyZW5jeSI6IlVTRCIsInBsYXlNb2RlIjoiY3JlZGl0IiwibGF1bmNoIjp7Im1vZGUiOiJsb2JieSIsImxpY2Vuc2VlIjoiYXNpYS1wbGF0Zm9ybS0xIiwiYWdlbnRzIjpbImFnZW50MSIsInN1YmFnZW50Il0sImxvYmJ5IjoibG9iYnkiLCJnYW1lSWQiOiJiYWNjYXJhdDAxIiwidW5pdHMiOltdLCJwYXJhbXMiOnsiY2F0ZWdvcnkiOiJ2aXAiLCJjYW1wYWlnbiI6InN1bW1lcjIwMjYiLCJwcm9tbzpib29sIjoiZmFsc2UifX0sImlzcyI6ImlkZW50aXR5LmVyaWNhc2luby5vcmciLCJzdWIiOiJhc2lhLXBsYXRmb3JuLTE6cGxheWVyLTkxODI3MyIsImF1ZCI6ImdhbWUtcHJvdmlkZXIuZXJpY2FzaW5vLm9yZyIsImlhdCI6MTc3MzExNzM4MSwiZXhwIjoxNzczMTE3OTgxfQ.I6u12uTO2-0yA32aSJXxa0Taco57XNL4k3--HUvyfT_yOrFH0pvykUzFNrP9hfbwjIvllJd7jn7K8oFTHNkRJA

若使用 iframe 作為遊戲啟動的途徑，同樣將網址設定成以上的組合模式即可。

{
  "success": false,
  "code": "<ERROR_CODE>",
  "reason": "<ERROR_REASON>"
}

Error reason 可能為空字串

---

1. RFC3986 - URI ↩