首页
游戏试玩 API 接入文档
APP
1
应用数
API
1
启动接口
DOCS
3015
游戏资源
类型统计
POST1
作者
平台官方
分组
| 名称 | 方式 | 接口 |
|---|---|---|
| 启动游戏 | POST | /api/launch.php |
接入概览
本文档面向第三方试玩站服务端接入。接入方根据平台提供的商户信息和游戏资源清单，在服务端请求启动接口，成功后将玩家跳转到平台返回的播放地址。
玩家点击游戏
接入方服务端签名
平台返回 play_url
302 跳转玩家
商户密钥只允许保存在服务端，不得出现在前端代码、App 包、公开仓库或日志明文中。
启动游戏
POST
{API_BASE_URL}/api/launch.php
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| merchant_id | string | 是 | 平台分配的商户 ID |
| launch_code | string | 是 | 游戏资源清单中的启动码 |
| timestamp | int | 是 | Unix 秒级时间戳，有效期 5 分钟 |
| nonce | string | 是 | 随机字符串，建议每次请求唯一 |
| signature | string | 是 | HMAC-SHA256 签名 |
| user_ip | string | 建议 | 玩家客户端 IP，用于安全校验 |
| visitor_id | string | 建议 | 同一玩家保持稳定 |
| user_agent | string | 建议 | 玩家浏览器 User-Agent |
签名规则
从请求 JSON 中移除 signature 字段，按参数名升序排序，使用 JSON 编码后，以商户密钥计算 HMAC-SHA256。
function canonicalPayload(array $payload): string
{
unset($payload['signature']);
ksort($payload);
return json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
}
$payload['signature'] = hash_hmac('sha256', canonicalPayload($payload), $merchantSecret);响应格式
成功响应
{
"success": true,
"message": "",
"data": {
"play_url": "https://play.example.com/xxx/index.html?...",
"play_ttl_seconds": 900,
"charged": 0.001
}
}失败响应
{
"success": false,
"message": "签名无效",
"data": []
}错误码
| HTTP 状态 | message 示例 | 处理建议 |
|---|---|---|
| 400/422 | 请求格式无效 / 缺少参数 | 检查 JSON 和必填参数 |
| 403 | 签名无效 | 检查签名字段、密钥和参数排序 |
| 403 | 服务器 IP 不在白名单 | 联系平台添加服务端出口 IP |
| 422 | 游戏不存在或未开通 | 检查 launch_code 是否来自最新资源清单 |
| 429 | 请求频率超限 | 增加防抖和服务端冷却 |
| 502 | 游戏启动失败，请稍后重试 | 稍后重试或联系平台排查 |
游戏资源
游戏资源清单独立提供，接入方前台展示游戏时使用 game_name、category、logo_url；启动游戏时只传对应的 launch_code。
{
"game_id": 1,
"game_name": "麻将胡了",
"category": "PG",
"launch_code": "g_d18d2c8a5d6f308aceb362c500750499",
"logo_url": "https://654.si/uploads/games/6924366a236e9.png"
}联调清单
- 平台提供 API 地址、商户 ID、商户密钥和游戏资源清单。
- 接入方提供服务端出口 IP，平台完成白名单配置。
- 接入方根据游戏资源清单展示游戏列表。
- 接入方服务端生成签名并请求启动接口。
- 成功响应后将玩家跳转到
play_url。 - 测试签名错误、无效 launch_code、IP 未白名单等异常场景。