趣玩通小游戏推广平台

1. 接入说明

外站可自行展示游戏列表。用户点击“马上玩”时，外站调用平台的动态启动接口；平台会为该外站绑定的推广用户动态申请、恢复或复用游戏申请，并返回当次有效的小游戏拉起参数。

不要缓存或自行拼接 wxgamepro、推广链接、小游戏路径。每次用户点击“马上玩”都必须调用动态启动接口。

2. 基础信息

API Base URL：https://api.hzyaoyuan.com/app-api
请求格式：application/json
租户请求头：tenant-id: 1
建议请求头：platform: H5
当前接口不需要登录 Token；动态启动接口通过 H5 大厅链接码识别收益归属。

统一响应格式：

{
  "code": 0,
  "msg": "",
  "data": {}
}

调用方应只在 code = 0 时使用 data。

3. H5 大厅链接码

每个外站会分配一个 H5 大厅链接码，以下文档以 <H5_MARKET_CODE> 表示。该链接码决定收益归属到哪个平台推广用户，请妥善保存。

https://play.hzyaoyuan.com/pages/promote/game-market?code=<H5_MARKET_CODE>

4. 获取游戏分类

GET/game/category-list

curl 'https://api.hzyaoyuan.com/app-api/game/category-list' \
  -H 'tenant-id: 1' \
  -H 'platform: H5'

[
  { "id": "", "name": "全部" },
  { "id": "休闲", "name": "休闲" },
  { "id": "角色", "name": "角色" },
  { "id": "动作", "name": "动作" },
  { "id": "竞技", "name": "竞技" },
  { "id": "棋牌", "name": "棋牌" },
  { "id": "文化互动", "name": "文化互动" },
  { "id": "其他", "name": "其他" }
]

5. 获取游戏列表

GET/game/page?pageNo=1&pageSize=20&category={category}&keyword={keyword}

参数	必填	说明
`pageNo`	是	页码，从 `1` 开始
`pageSize`	是	每页数量，建议不超过 `50`
`category`	否	分类 ID；不传表示全部
`keyword`	否	游戏名称关键词

curl 'https://api.hzyaoyuan.com/app-api/game/page?pageNo=1&pageSize=20&category=%E4%BC%91%E9%97%B2' \
  -H 'tenant-id: 1' \
  -H 'platform: H5'

{
  "list": [
    {
      "id": 13228,
      "name": "示例游戏",
      "iconUrl": "https://.../icon.png",
      "coverUrl": "https://.../cover.png",
      "previewImageUrl": "https://.../preview.png",
      "category": "休闲"
    }
  ],
  "total": 1
}

列表仅返回当前在线游戏。外站应使用 id 作为后续动态启动接口的 gameId。

6. 获取游戏详情

GET/game/detail?id={gameId}

curl 'https://api.hzyaoyuan.com/app-api/game/detail?id=13228' \
  -H 'tenant-id: 1' \
  -H 'platform: H5'

字段	说明
`id`	游戏 ID
`sourceGameId`	小游戏 AppID，仅用于展示或调试
`name`	游戏名称
`description`	游戏描述
`iconUrl` / `coverUrl`	图标和封面 URL
`screenshots`	游戏截图 URL 数组
`category`	游戏分类

拉起小游戏时必须使用动态启动接口返回的 targetAppId 和 targetPath，不要使用详情接口字段自行构造。

7. 动态申请并启动小游戏

POST/promote/h5-market-launch

请求体

{
  "code": "<H5_MARKET_CODE>",
  "gameId": 13228,
  "anonymousVisitorKey": "site-user-or-device-unique-id",
  "landingUrl": "https://partner.example.com/games/13228"
}

字段	必填	说明
`code`	是	平台分配的 H5 大厅链接码
`gameId`	是	游戏列表接口返回的游戏 ID
`anonymousVisitorKey`	否	稳定匿名 ID，用于启动日志追踪；请勿传手机号、身份证号等敏感信息
`landingUrl`	否	当前外站落地页 URL，用于访问日志追踪

调用示例

curl -X POST 'https://api.hzyaoyuan.com/app-api/promote/h5-market-launch' \
  -H 'Content-Type: application/json' \
  -H 'tenant-id: 1' \
  -H 'platform: H5' \
  -d '{
    "code": "<H5_MARKET_CODE>",
    "gameId": 13228,
    "anonymousVisitorKey": "visitor-9f2c3a",
    "landingUrl": "https://partner.example.com/games/13228"
  }'

成功响应的常用字段

{
  "h5MarketApplied": true,
  "applicationId": 2892,
  "promoterUserId": 1001,
  "gameId": 13228,
  "targetAppId": "wx1234567890abcdef",
  "targetPath": "?wxgamepro=CpsCB...",
  "officialPromotedLink": "https://...",
  "bridgeUrlLink": "https://...",
  "scheme": "weixin://...",
  "launchH5Url": "https://..."
}

1. 校验：平台校验游戏在线状态和可用名额。

2. 动态申请：未申请则创建；已冻结或释放则恢复/重新申请。

3. 返回参数：返回当前有效的 CPS 参数、桥接链接和小游戏拉起参数。

4. 记录启动：记录本次 H5 启动行为，供归因和排查使用。

8. 拉起小游戏规则

officialPromotedLink 非空：浏览器顶层跳转到该链接。
否则，使用 bridgeUrlLink 或 scheme 进行微信环境拉起。
仅在具备微信小游戏拉起能力的容器中，使用 targetAppId 和 targetPath 直接拉起。

外站不得自行固定或修改 targetPath 中的 wxgamepro 参数。游戏释放、重新申请或坑位变化后，旧参数可能不再用于新的归因。

9. 归因与收益说明

同一个 code 启动的游戏收益，统一归属到该 code 绑定的推广用户。
anonymousVisitorKey 仅用于访问和启动日志追踪，不会把收益分配给外站访客本人。
游戏低收益自动释放后，外站下次点击“马上玩”仍应重新调用动态启动接口，平台会返回当前有效的申请和 CPS 参数。
请勿缓存动态启动接口的返回结果，也不要将某个游戏的启动参数复用于其他游戏。

10. 接入前确认事项

当前平台 API 已允许浏览器跨域调用，外站可直接请求 API；若后续安全策略调整，平台会提前通知需要登记的域名。
外站需要保存并传递稳定的 anonymousVisitorKey，建议使用随机 UUID 或站内匿名 ID。