logo微游H5出海开发者中心

游戏位OpenAPI-V4对接文档

1. 概述

1.1 产品介绍

OpenAPI-V4 游戏位专为合作渠道的客户端游戏内容消费场景设计，支持原生 App、Web、WebView、小程序等多种载体。本接口提供标准化的 H5 游戏内容列表获取能力，帮助渠道方快速构建个性化游戏推荐模块。

1.2 核心能力

  • 多维度筛选：支持按渠道、语言、国家、游戏类别、屏幕方向等条件获取可玩的 H5 游戏列表。

  • 智能排序：基于 MiniGame AI 算法，融合本地化用户行为偏好、收入表现等多重因子进行个性化推荐。

  • 数据闭环：客户端需要接入曝光、点击、视频播放等用户行为事件回传机制，用于持续优化推荐效果、数据统计和归因分析。

  • 样式适配：支持大卡片、三联卡片、视频、游戏信息流等不同游戏位类型。

1.3 使用流程

Client requests the slot API with slot and context parameters.
Server returns a personalized game list.
Client renders the game slot.
Client reports show, click, and play events.
Recommendation models continue to optimize.

1.4 术语定义

术语说明
client_id商户唯一标识，由微游互娱分配，请求头中使用 x-md-global-cid 传递
api_keyAPI 访问密钥，由微游互娱技术人员提供，用于生成 sign
slot_id游戏位 ID，由微游互娱技术或运营人员创建并提供
request_id请求 ID，用于一次推荐请求的链路追踪；gameFlow 翻页时需要继续传递
content_ids游戏 App ID 列表，用于事件回传，可用英文逗号分隔多个游戏

2. 环境与测试参数

2.1 接口环境

环境游戏位 API HOST_PREFIX事件回传 API
测试环境https://mdev.minigamevs.com/openapiv4_servicehttps://mdev.minigamevs.com/stats_service/api/wy/report/{event_id}
正式环境https://openapi.minigame.aihttps://stats.minigame.com/api/wy/report/{event_id}

游戏位接口完整路径：

{HOST_PREFIX}/openapi/v4/game/slot

2.2 测试环境参数

参数值说明
client_id233802991579168768商户 ID，请求头 x-md-global-cid 使用该值
api_key5e567421-c0a5-4723-80a6-2f5567517146API 访问密钥，用于生成 sign
slot_idTSZ3R9W6P2K8bigCard 类型
slot_idTSK9P4X1Q6B2threeCards 类型
slot_idTSB4F2H8Y3Q7bigVideo 类型

测试参数仅用于开发联调。正式上线前请联系微游互娱获取正式环境参数，并确保测试环境和正式环境配置隔离。

3. 签名校验规则

3.1 密钥获取

client_id 和 api_key 由微游互娱技术人员提供。api_key 用于生成签名，应妥善保管，不建议直接暴露在客户端可读取的位置。

3.2 参数范围

所有 API 请求参数需要按规则参与签名，空值字段不参与签名。

参与签名的参数范围：

  • URL 查询参数，例如游戏位 API 的 slot_id、user_id、country 等。

  • POST 请求体参数，例如事件回传 API 的 content_ids、slot_id、display_duration 等。

  • HTTP Header 中的 ts 时间戳。

  • 事件回传 API 的路径参数 event_id。

不参与签名的字段：

  • sign 本身。

  • x-md-global-cid。

  • x-user-ip。

  • gameFlow 翻页场景下的 request_id。

  • 空值字段。

3.3 拼接规则

  1. 将参与签名的参数按照 参数名=参数值 的格式拼接。

  2. 多个参数之间使用 & 连接。

  3. 所有参数按照参数名 ASCII 码从小到大排序。

  4. 空值参数不参与签名。

拼接格式示例：

key1=value1&key2=value2

3.4 签名生成

  1. 将拼接好的参数字符串前面追加 api_key。

  2. 对追加后的字符串进行 SHA256 哈希运算。

  3. 生成的十六进制哈希值即为最终签名字符串 sign。

公式：

sign = SHA256(api_key + sorted_parameter_string)

3.5 签名示例

以下示例使用固定 ts 便于复现。实际接入时，ts 应使用当前秒级时间戳。

const crypto = require("crypto");

const config = {
  apiKey: "5e567421-c0a5-4723-80a6-2f5567517146",
  clientId: "233802991579168768",
  baseUrl: "https://mdev.minigamevs.com/openapiv4_service",
};

function generateSignature(params) {
  const filteredParams = Object.fromEntries(
    Object.entries(params).filter(([, value]) => value !== undefined && value !== null && value !== "")
  );

  const signString = Object.keys(filteredParams)
    .sort()
    .map((key) => `${key}=${filteredParams[key]}`)
    .join("&");

  const rawSignString = config.apiKey + signString;
  const sign = crypto.createHash("sha256").update(rawSignString).digest("hex");

  return {
    ts: filteredParams.ts,
    sign,
    rawSignString,
  };
}

const signResult = generateSignature({
  country: "TW",
  device_brand: "moto",
  device_id: "jdhjdgh1",
  device_model: "X100",
  language: "zh",
  orientation: "vertical",
  slot_id: "TSZ3R9W6P2K8",
  ts: 1773653443,
  user_id: "123441",
});

console.log(signResult);

输出示例：

{
  "ts": 1773653443,
  "sign": "1ac91fb23ab2befdaad3f54ca61fa594a0adfbb393c283c99de5db97dc4c13ab",
  "rawSignString": "5e567421-c0a5-4723-80a6-2f5567517146country=TW&device_brand=moto&device_id=jdhjdgh1&device_model=X100&language=zh&orientation=vertical&slot_id=TSZ3R9W6P2K8&ts=1773653443&user_id=123441"
}

3.6 签名排查建议

问题常见原因处理建议
invalid signature参数排序不一致打印参与签名的参数名并确认 ASCII 排序
invalid signaturets 未参与签名将请求头 ts 显式加入签名参数
invalid signature空值字段参与签名过滤 null、空字符串和未传字段
invalid signaturerequest_id 被纳入游戏位翻页签名gameFlow 翻页的 request_id 不纳入签名
invalid signature事件 API 未纳入 event_id事件回传 API 需要将路径参数 event_id 纳入签名
timestamp expired客户端或服务端时间不准使用秒级时间戳，并保证在 ±5 分钟有效期内

4. 游戏位 API

4.1 接口描述

获取指定游戏位的个性化推荐游戏列表。本接口用于首页、详情页、推荐位、游戏流等位置的游戏推荐模块，返回内容包括游戏元数据、用于渲染的素材地址以及渠道专属游戏链接。

核心逻辑：

  • 根据游戏位类型和上下文信息返回个性化推荐游戏列表。

  • 游戏名称、介绍、玩法等元信息会根据请求中的国家和语言参数返回对应版本。

  • 素材地址会根据不同游戏位样式要求返回图标、卡片背景、横幅、闪屏图、视频等 CDN 资源。

  • 游戏链接为当前渠道生成的专属地址，通常会自动带上 request_id 等归因参数。

数据冗余策略：

  • 为确保推荐位展示效果和容灾能力，非分页类游戏位采用 1:1 冗余机制。

  • 如果游戏位需要展示 n 个游戏，接口会返回 2n 个游戏数据，供客户端优选或降级替换。

  • 示例：bigCard 位置只展示 1 个游戏，接口会返回 2 个游戏。

4.2 基本信息

项目值
请求方式GET
请求路径/openapi/v4/game/slot
完整地址{HOST_PREFIX}/openapi/v4/game/slot
Content-Type无请求体

4.3 游戏位类型

类型标识描述返回游戏数量是否支持分页说明
bigCard大卡片1 + 1 备用否本样式只展示 1 款游戏，接口会另外提供 1 款备用游戏
gameFlow游戏信息流精选库是分页返回精选库游戏，每页 10 个游戏，需要传分页参数；第 2 页开始需要传上一页响应中的 request_id
threeCards三联卡片3 + 3 备用否展示 3 款游戏，建议在用户重新回到界面且展示超过1min时更新一组
bigVideo视频1 + 1 备用否视频进入可视区后自动静音播放

4.4 请求头

名称描述类型必填示例值说明
sign签名string是1ac91fb23ab2b...按签名校验规则生成
ts时间戳int是174919361610 位秒级时间戳，±5 分钟有效
x-md-global-cid商户唯一标识int是233802991579168768对应 client_id

4.5 请求参数

名称描述类型必填示例值说明
slot_id游戏位 IDstring是TSZ3R9W6P2K8根据游戏位类型使用对应 ID
user_id用户 IDstring否123456建议传入，可使用渠道侧 Open UID
device_id设备 IDstring否01c081dd1edc建议传入，可使用 GAID 或渠道设备标识
device_brand设备品牌string否XIAOMI设备品牌
device_model设备机型string否Note 13 Pro设备型号
language语言标准代码string否zh建议传入；优先推荐适合该语言的游戏，不是强筛选
country国家标准代码string否CN优先推荐适合该国家的游戏，不是强筛选
categories游戏类别string否puzzle,casual多个分类用英文逗号分隔；如当前游戏位未开放分类筛选，以后台配置为准
orientation屏幕方向string否vertical用于筛选适配屏幕方向的游戏；可选 horizontal、vertical
page分页页码int否1部分游戏位支持分页，例如 gameFlow；默认第 1 页
request_id请求 IDstringgameFlow 第 2 页起必填5e2ef168670507758a992fcbac140910gameFlow 第一页可传空字符串，第 2 页起必须传上一页响应中的 request_id；不纳入签名

4.6 请求示例

curl -G "https://mdev.minigamevs.com/openapiv4_service/openapi/v4/game/slot" \ 
  -H "sign: 1ac91fb23ab2befdaad3f54ca61fa594a0adfbb393c283c99de5db97dc4c13ab" \ 
  -H "ts: 1773653443" \ 
  -H "x-md-global-cid: 233802991579168768" \ 
  --data-urlencode "slot_id=TSZ3R9W6P2K8" \ 
  --data-urlencode "user_id=123441" \ 
  --data-urlencode "device_id=jdhjdgh1" \ 
  --data-urlencode "device_brand=moto" \ 
  --data-urlencode "device_model=X100" \ 
  --data-urlencode "language=zh" \ 
  --data-urlencode "country=TW" \ 
  --data-urlencode "orientation=vertical"

4.7 响应字段

名称描述类型示例值说明
request_id请求 IDstringb4f67172-a9dd-4d10-ab04-011faedc2867唯一标识本次推荐请求
total游戏数量int860当前响应或分页条件下的游戏数量
items游戏列表array-游戏数组
items[].id游戏 App IDstringneo-adventure用于事件回传的内容 ID
items[].link游戏链接string-链接会自动带上 request_id 等参数
items[].detail游戏信息object-游戏元信息和素材
items[].detail.name游戏名称stringNeo Adventure按国家或语言返回对应版本
items[].detail.categories游戏分类array["puzzle", "io"]一个游戏可有一个或多个分类
items[].detail.how_to_play游戏玩法stringFollow hints and defeat monsters.玩法说明
items[].detail.description游戏简介stringHelp Neo finish the adventure.游戏介绍
items[].detail.orientation屏幕方向stringvertical可选 horizontal、vertical
items[].detail.icon游戏图标object 或 string-URL 地址
items[].detail.small_icon游戏小图标string-URL 地址
items[].detail.big_icon游戏大图标string-URL 地址
items[].detail.banner游戏横幅string-URL 地址
items[].detail.flash游戏闪屏图string-URL 地址
items[].detail.video游戏视频string-URL 地址

4.8 成功响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "detail": {
          "banner": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_banner.png",
          "big_icon": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_big_icon.png",
          "categories": ["puzzle", "io"],
          "description": "Help Neo finish the adventure.",
          "flash": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_flash.png",
          "how_to_play": "Follow hints, upgrade weapons, and defeat monsters.",
          "icon": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_icon.png",
          "name": "Neo Adventure",
          "orientation": "vertical",
          "small_icon": "https://res.minigame.vip/gc-assets/neo-adventure/neo-adventure_icon_small.png",
          "video": "https://res.minigame.vip/gc-assets/minigame/weiyou.png"
        },
        "id": "neo-adventure",
        "link": "https://test1.minigame.com/en/game/neo-adventure/play/m?slot_id=TSZ3R9W6P2K8#request_id=925c0a74287d00a5a0588c1726b542a4"
      },
      {
        "detail": {
          "banner": "https://res0.debug.minigame.vip/gc-assets/super-spy/super-spy_banner.png",
          "big_icon": "https://res0.debug.minigame.vip/gc-assets/super-spy/super-spy_big_icon.png",
          "categories": ["battle"],
          "description": "Become a spy and aim with precision.",
          "flash": "https://res0.debug.minigame.vip/gc-assets/super-spy/super-spy_flash.png",
          "how_to_play": "Aim at enemies and complete the mission.",
          "icon": "https://res0.debug.minigame.vip/gc-assets/super-spy/super-spy_icon.png",
          "name": "Super Spy",
          "orientation": "vertical",
          "small_icon": "https://res.minigame.vip/gc-assets/super-spy/super-spy_icon_small.png",
          "video": "https://res.minigame.vip/gc-assets/minigame/weiyou.png"
        },
        "id": "super-spy",
        "link": "https://test1.minigame.com/en/game/super-spy/play/m?slot_id=TSZ3R9W6P2K8#request_id=925c0a74287d00a5a0588c1726b542a4"
      }
    ],
    "request_id": "925c0a74287d00a5a0588c1726b542a4",
    "total": 2
  },
  "ts": 1775723742
}

4.9 失败响应示例

{
  "code": 401,
  "message": "invalid signature",
  "ts": 1773735959
}

5. 用户行为事件回传 API

2026-05-08 更新：事件回传 API 新增请求头 x-user-ip 和请求体字段 slot_id。

5.1 接口描述

用户行为事件回传 API 用于接收客户端上报的用户行为事件，例如游戏曝光、游戏点击、视频播放等。合作方需要将事件数据回传至本接口，以便进行数据统计、效果分析、推荐优化和归因计算。

5.2 基本信息

环境接口 URL
测试环境https://mdev.minigamevs.com/stats_service/api/wy/report/{event_id}
正式环境https://stats.minigame.com/api/wy/report/{event_id}

测试参数：

参数值说明
client_id233802991579168768商户 ID，请求头 x-md-global-cid 使用该值
api_key5e567421-c0a5-4723-80a6-2f5567517146API 访问密钥，用于生成 sign

5.3 支持事件类型

event_id事件名称触发时机说明
show曝光事件游戏位展示时游戏卡片或素材进入屏幕可视区域时触发
click点击事件游戏位点击时用户点击游戏位并开始跳转时触发
vplay播放事件视频播放与暂停视频开始和停止播放时记录播放时间并上报

5.4 请求方式

事件回传 API 同时支持 GET 和 POST。

GET 请求通过 URL Query String 传参：

GET /report/show?content_ids=neo-adventure&slot_id=TSZ3R9W6P2K8

POST 请求通过 JSON Body 传参：

POST /report/show HTTP/1.1
Content-Type: application/json

{
  "content_ids": "neo-adventure",
  "slot_id": "TSZ3R9W6P2K8"
}

5.5 请求头

名称描述类型必填示例值说明
sign签名string是05c56a07a720...计算签名时需要包含路径参数 event_id，未传值字段不参与签名
ts事件触发时刻对应的时间戳int是174919361610 位秒级时间戳，±5 分钟有效
x-md-global-cid商户唯一标识int是233802991579168768对应 client_id
x-user-ip用户 IPstring否183.23.63.82服务端上报时建议填写

5.6 路径参数

字段描述类型必填示例值说明
event_id事件名称string是show可选 show、click、vplay

5.7 请求体字段

字段描述类型必填示例值说明
content_ids内容 ID 列表string是neo-adventure,super-spy游戏 App ID，可用英文逗号分隔多个游戏
slot_id游戏位 IDstring是TSZ3R9W6P2K8根据游戏位类型传对应 ID
session_id会话 IDstring否abcdefg123用于分析用户单次访问行为路径
device_id设备 IDstring否d52ad7b6-5c86-4131-a79f-7236f7b183e2设备唯一标识
device_brand设备品牌string否XIAOMI设备品牌
device_model设备机型string否Note 13 Pro设备型号
app_id应用 IDstring否com.unite.demo安卓或 iOS 应用 ID 或应用包名
device_type设备类型string否mobile可选 desktop、mobile、tablet、other
orientation屏幕方向string否vertical可选 horizontal、vertical
user_id用户 IDstring否10011用户唯一标识，例如登录用户 ID
country国家标准代码string否CN用户所在国家
language语言标准代码string否zh用户语言
display_duration展示时长int否120游戏在屏幕上的展示时长，单位秒
viewport视口大小string否540x960游戏展示的视口大小，格式为宽 x 高
app_version应用版本string否v1.0.0应用每次发布的版本号
play_start_ts播放开始时间int64否1778146175764毫秒级时间戳，播放事件传递
play_stop_ts播放结束时间int64否1778146177226毫秒级时间戳，播放事件传递
play_duration播放时长int64否1462单位毫秒，播放事件传递
position展示位置string否1或1,2,3threeCards类型每个被曝光卡片的索引位置，索引不能是0

5.8 签名示例

事件回传 API 的签名参数需要包含路径参数 event_id。

const crypto = require("crypto");

const apiKey = "5e567421-c0a5-4723-80a6-2f5567517146";

function signEvent(params) {
  const filteredParams = Object.fromEntries(
    Object.entries(params).filter(([, value]) => value !== undefined && value !== null && value !== "")
  );

  const signString = Object.keys(filteredParams)
    .sort()
    .map((key) => `${key}=${filteredParams[key]}`)
    .join("&");

  return crypto.createHash("sha256").update(apiKey + signString).digest("hex");
}

const sign = signEvent({
  content_ids: "neo-adventure,super-spy",
  event_id: "show",
  slot_id: "TSZ3R9W6P2K8",
  ts: 1773653443,
  user_id: "123441",
});

console.log(sign);

输出示例：

05c56a07a72076ac8ea0f9c667b2a5b2a417c2226a33819885833de8b093eb0e

5.9 POST 请求示例

curl -X POST "https://mdev.minigamevs.com/stats_service/api/wy/report/show" \ 
  -H "Content-Type: application/json" \ 
  -H "sign: 05c56a07a72076ac8ea0f9c667b2a5b2a417c2226a33819885833de8b093eb0e" \ 
  -H "ts: 1773653443" \ 
  -H "x-md-global-cid: 233802991579168768" \ 
  -H "x-user-ip: 183.23.63.82" \ 
  -d '{
    "content_ids": "neo-adventure,super-spy",
    "slot_id": "TSZ3R9W6P2K8",
    "user_id": "123441"
  }'

5.10 响应字段

名称描述类型示例值说明
received成功数量int1成功接收的事件数量
tid链路 IDstringa7fc67356697492a92ee8b3054a6a3b8失败排查时建议记录

成功响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "received": 1
  },
  "ts": 1773729283,
  "tid": "a7fc67356697492a92ee8b3054a6a3b8"
}

失败响应示例：

{
  "code": 500,
  "message": "contentIds is required",
  "ts": 1773731064,
  "tid": "56d1f0a015a340e9931971885da2909e"
}

5.11 上报建议

  • show 事件应在游戏卡片或素材进入可视区域时触发。

  • click 事件应在用户点击游戏位并开始跳转时触发。

  • vplay 事件用于游戏视频播放记录，建议传入 play_start_ts、play_stop_ts 和 play_duration。

  • 同一展示周期内应避免对同一游戏和同一事件重复上报。

  • 网络传输存在代理上报时建议配置Header x-user-ip，用于数据分析。

  • 事件上报失败不应阻断用户打开游戏或继续浏览。

6. 附录

6.1 常见错误

错误说明处理建议
invalid signature签名校验失败检查参数范围、排序、api_key、ts 和 event_id 是否正确
timestamp expired时间戳过期使用秒级时间戳，并保证在 ±5 分钟内
contentIds is required事件回传缺少内容 ID检查 content_ids 是否传入且字段名正确
slot_id is required缺少游戏位 ID游戏位 API 和事件回传 API 都需要传入 slot_id
invalid slot_id游戏位不存在或无权限确认 slot_id 是否属于当前商户

6.2 常用国家代码

代码国家/地区
CN中国大陆
TW中国台湾
HK中国香港
JP日本
KR韩国
US美国
GB英国
DE德国
FR法国
BR巴西
ID印度尼西亚
TH泰国
VN越南
MY马来西亚
PH菲律宾
SG新加坡

完整列表可参考 ISO 3166-1 alpha-2。

6.3 常用语言代码

代码语言
zh中文
en英语
ja日语
ko韩语
es西班牙语
pt葡萄牙语
fr法语
de德语
id印尼语
th泰语
vi越南语
ms马来语
ar阿拉伯语

完整列表可参考 ISO 639-1。

更新日志

版本日期更新内容
v4.3.02026-05-08事件回传 API 新增游戏视频播放 vplay 事件，新增 threeCards类型三联卡片position上报。
v4.2.02026-03-17多游戏位请求、内嵌 tracker URL、HMAC-SHA256 签名
v4.1.02026-03-15统一响应结构、新增分页参数、补充错误码

技术支持

如有疑问，请联系MiniGame技术支持团队。

logo
微游中心：https://minigame.com
Copyright © 2019-2026 MiniGame
商务对接
商务对接
公众号
公众号