玩家与进入游戏

创建或取得玩家

POST {API_URL}/v1/players

商户用自己的玩家 ID 换取平台的 player_id。同一个 external_player_id 永远对应同一个 player_id，所以可以在每次进入游戏前都调用一次。

参数	必填	类型	说明
external_player_id	是	string	商户侧玩家 ID，1–128 字节（UTF-8），商户下唯一
display_name	否	string	显示名，最多 160 字节（UTF-8）

{ "external_player_id": "merchant-user-1", "display_name": "Alice" }

成功响应

新建返回 201，已存在返回 200：

{
  "data": {
    "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
    "external_player_id": "merchant-user-1",
    "display_name": "Alice"
  },
  "request_id": "0192f6a4-req-0001"
}

• 玩家已存在时，不会用新的 display_name 覆盖旧值。
• external_player_id 就是单一钱包回调中用来定位玩家的 ID，请使用稳定、不会变化的值，不要用昵称或手机号。
• 创建玩家不会创建钱包，钱包在首次进入游戏或首次资金交易时创建。

请求进入游戏

POST {API_URL}/v1/launches

为某个玩家签发一次性的游戏地址。

参数	必填	类型	说明
player_id	是	string	平台玩家 ID
game_id	是	string	游戏 ID，来自游戏列表
currency	是	string	本次游戏使用的币种
locale	否	string	语言标签，默认 en。应在游戏的 languages 之中
return_url	否	string	玩家退出游戏后返回的地址，必须在平台登记的范围内，最长 2048
display_mode	否	string	full（默认）、compact 或 landscape，须为游戏支持的模式

{
  "player_id": "0192f6a4-3c1e-7b2a-9d40-5e8f1a2b3c4d",
  "game_id": "0192f6a5-1111-7aaa-8bbb-000000000001",
  "currency": "USD",
  "locale": "zh-Hans",
  "return_url": "https://www.example.com/lobby"
}

成功响应 201

字段	类型	说明
launch_id	string	本次启动的 ID
launch_url	string	游戏地址，直接交给玩家的浏览器打开
expires_at	string	地址过期时间

{
  "data": {
    "launch_id": "0192f6f4-6e7d-7091-b2c3-9d0e1f2a3b4c",
    "launch_url": "https://game.example.com/releases/hilo/15/index.html#mj_launch=AbC…",
    "expires_at": "2026-09-23T08:01:00Z"
  },
  "request_id": "0192f6f4-req-0001"
}

使用 launch_url

• 原样打开：用跳转、新窗口或 iframe 打开都可以，但不要修改、拼接或解析地址。票据放在 #mj_launch 片段中，不会发到任何服务器的访问日志里。
• 尽快打开：地址在 60 秒内有效，并且只能使用一次。不要预先生成、缓存或分享给其他玩家。
• 刷新和断线重连不需要重新签发：游戏客户端会用已有的会话自动恢复。只有玩家重新从商户大厅进入游戏时，才需要再调用一次本接口。
• 重新签发要换 Idempotency-Key：用同一个幂等键重放，只会拿回原来那个（可能已过期的）地址。

失败响应

HTTP	error.code	说明
404	RESOURCE_NOT_FOUND	玩家或游戏不存在，或不属于当前商户
403	LAUNCH_DENIED	当前不允许该玩家进入，例如玩家或商户已被停用
409	IDEMPOTENCY_CONFLICT	同一个 Idempotency-Key 已用于不同内容的请求
422	GAME_NOT_AVAILABLE	游戏未授权、维护中或暂不可启动
422	CURRENCY_NOT_SUPPORTED	币种未开通
422	VALIDATION_FAILED	参数不合法，例如 return_url 不在登记范围、display_mode 游戏不支持