OpenAPI-V4 对接文档


1. 概述

1.1 产品介绍

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

1.2 核心能力

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

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

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

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

1.3 使用流程

客户端携带组件 ID(`slot_id`)和上下文(Context)信息调用推荐接口。
服务端返回个性化游戏推荐列表。
客户端渲染组件内容。
客户端上报曝光、点击及游戏启动等行为事件。
推荐模型基于用户行为持续训练和优化,不断提升推荐效果。

1.4 术语定义

术语说明
client_id商户唯一标识,由 MiniGame.Com 分配,请求头中使用 x-md-global-cid 传递
api_keyAPI 访问密钥,由商户在商户平台自行创建获取(见密钥获取),用于生成 sign
slot_id组件 ID,由商户在 Partner 平台技术对接页面自行获取
组件承载游戏位的模块,包括推荐卡片、视频、游戏信息流、游戏中心大厅、新游、随机游戏和历史游戏等类型;每个组件通过组件 ID(slot_id)标识
游戏位组件内用于进入单个游戏的接口
request_id请求 ID,用于一次推荐请求的链路追踪;gameFlow 翻页时需要继续传递
content_ids游戏 App ID 列表,用于事件回传,可用英文逗号分隔多个游戏

2. 环境与测试参数

2.1 接口环境

环境组件 API HOST_PREFIX事件回传 API
测试环境https://openapi-sandbox.minigame.aihttps://stats-sandbox.minigame.com/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 类型
slot_idGCTESTHALL01gameCenter 游戏中心大厅组件

测试参数仅用于开发联调。正式上线前请联系 MiniGame.Com 获取正式环境 client_id 与组件 ID(slot_id),正式环境 api_key 请在商户平台自行创建获取(见密钥获取),并确保测试环境和正式环境配置隔离。


3. 签名校验规则

3.1 密钥获取

client_id 由 MiniGame.Com 技术人员提供。

api_key 由商户在商户平台自行创建获取:登录商户平台,进入「控制台」菜单栏的「账号信息」页面,在「Api Key」处点击创建,得到的参数即为 api_key。如不慎遗忘,可删除后重建。可通过以下链接快捷进入该页面:

https://business.minigame.com/console/account/info

api_key 用于生成签名,应妥善保管,不建议直接暴露在客户端可读取的位置。

3.2 参数范围

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

参与签名的参数范围:

  • URL 查询参数,例如组件 API 的 slot_id、user_id、country、app_ids 等。

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

  • HTTP Header 中的 ts 时间戳。

不参与签名的字段:

  • sign 本身。

  • x-md-global-cid。

  • x-user-ip。

  • gameFlow 翻页场景下的 request_id。

  • 事件回传 API 的路径参数 event_id(如 show、click)。

  • 空值字段。

关于 event_id:规范上事件回传的路径参数 event_id 不参与签名。服务端已做兼容——无论贵方现有实现是否将 event_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://openapi-sandbox.minigame.ai",
};

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"
}

历史组件的 app_ids 使用实际发送、URL 解码后的原始字符串参与签名,不能先去空格、去重或改变顺序。URL 编码在签名后进行。例如:

请求参数:slot_id=HISTORY_SLOT,language=en,app_ids=game-b, game-a,game-b
签名参数串:app_ids=game-b, game-a,game-b&language=en&slot_id=HISTORY_SLOT&ts=1790000123
签名公式:SHA256("5e567421-c0a5-4723-80a6-2f5567517146" + 签名参数串)
发送Query:slot_id=HISTORY_SLOT&language=en&app_ids=game-b%2C%20game-a%2Cgame-b
请求头ts:1790000123

新游组件(newGames)、随机组件(randomGames)和历史组件(historyGames)无需传 request_id;成功响应会返回新的 request_id。

3.6 签名排查建议

问题常见原因处理建议
invalid signature参数排序不一致打印参与签名的参数名并确认 ASCII 排序
invalid signaturets 未参与签名将请求头 ts 显式加入签名参数
invalid signature空值字段参与签名过滤 null、空字符串和未传字段
invalid signatureapp_ids 被提前去重或去空白使用实际发送、URL 解码后的原始字符串签名
invalid signature事件回传的 position 未参与签名position 有值时必须参与签名

4. 组件 API

4.1 接口描述

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

核心逻辑:

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

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

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

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

数据冗余策略:

  • bigCard、threeCards、bigVideo、newGames 采用 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 备用否视频进入可视区后自动静音播放
gameCenter游戏中心大厅组件不返回游戏否返回完整大厅链接 hall_url,详见 4.11
newGames新游组件2 + 2 备用,最多 4 款否items 前 2 款展示、后 2 款备用;不足 4 款按实际数量返回,均含游戏资料、链接和上架时间
randomGames随机组件最多 20 款否一次返回,无备用列表;不同请求的结果可能相同或部分重合
historyGames历史组件最多 20 款否根据传入游戏 ID 返回当前可用资料和链接,并返回大厅及历史页入口

4.4 请求头

名称描述类型必填示例值说明
sign签名string是1ac91fb23ab2b...按签名校验规则生成
ts时间戳int是1749193616使用当前秒级时间戳,并将原值参与签名
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否1gameFlow 沿用分页;三种新组件只允许省略或 1,显式 0、负数或大于 1 报错
request_id请求 IDstringgameFlow 第 2 页起必填5e2ef168670507758a992fcbac140910gameFlow 第一页可省略,第 2 页起传同一会话的 request_id;沿用不签此字段的方式。三种新组件不使用分页会话,省略此参数;传入也不会续页或复用响应 ID
app_ids待查询游戏 IDstring否game-b,game-a仅 historyGames;英文逗号分隔,原始 UTF-8 字符串最多 4096 字节,去重后最多 20 个 ID

app_ids 处理规则:

  • 省略、空字符串或全空白字符串:成功时返回空 items 及两个入口链接,仍需正常鉴权。

  • 服务端在验签后去除每个 ID 两侧空白,再校验 ID 并去重;重复 ID 保留首次出现顺序。返回按此顺序排列,不存在或不可用的游戏被省略。

  • ID 只允许 ASCII 字母、数字、_、-、.;空段(如 a,,b)、单独 ./..、路径分隔符等非法内容返回参数错误。

  • 超过 20 个不同 ID 或 4096 字节返回错误,不静默截断。请使用一个 app_ids 参数,勿重复同名查询参数。

  • app_ids 仅适用于历史组件(historyGames),其他组件请勿传入。

  • 如历史查询同时传入 orientation,返回结果也受该筛选条件影响;核对全部历史时请勿添加排除部分记录的筛选条件。

4.6 请求示例

curl -G "https://openapi-sandbox.minigame.ai/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"

历史组件查询指定游戏时,在上述请求中增加以下参数,并按实际参数重新签名(参数名为 app_ids,不是上报中的宿主应用字段 app_id):

--data-urlencode "app_ids=million-star"

4.7 响应字段

名称描述类型示例值说明
request_id请求 IDstringb4f67172-a9dd-4d10-ab04-011faedc2867唯一标识本次推荐请求
total游戏数量int860gameFlow 为当前分页会话游戏总数;三种新组件为本次实际返回数量(新游包含备用游戏),不是候选总量;gameCenter 固定为 0
m_icon_modeM 标接入模式stringcompositedcomposited=图片素材已由服务端合成 M 标角标,客户端勿再叠加;overlay=素材不含角标。按组件类型返回,详见 4.10
hall_url完整大厅链接stringhttps://games.example/?slot_id=HISTORY_SLOT#request_id=history-requestgameCenter 和 historyGames 返回;客户端直接使用返回值跳转,无需拼接域名或路径
history_url完整历史页链接stringhttps://games.example/fr/recetlyplayed?slot_id=HISTORY_SLOT#request_id=history-request仅 historyGames 返回;当前站点、当前语言的完整入口,直接跳转,无需自行拼接
items游戏列表array-游戏数组
items[].id游戏 App IDstringneo-adventure用于事件回传的内容 ID
items[].link游戏链接string-链接会自动带上 request_id 等参数
items[].detail游戏信息object-游戏元信息和素材
items[].detail.new_game_published_at上架时间integer 或 null1790000000仅 newGames 返回,UTC Unix 秒(不是毫秒或字符串);null 表示时间未知,不显示推算的上架文案
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 地址
items[].detail.m_iconM 标角标图stringhttps://res.minigame.vip/gc-assets/0/mg_corner.pngm_icon_mode=composited 时返回官方角标图 URL,仅供客户端叠加到视频(video)上;其余场景为空,详见 4.10

注意:m_icon_mode=composited 时,图片素材 URL 会附带 ?x-oss-process=image/watermark,... 处理参数(服务端合成 M 标角标)。请将素材 URL 原样用于加载展示,不要截断、拼接或改写 URL 中的任何参数。

历史记录由客户端本地维护,API 不保存用户游玩历史。正常展示、打开可使用缓存资料和链接;主动刷新时用 app_ids 批量更新,只有完整成功响应才可清理未返回的记录,失败时保留原记录。My Games 无本地历史时使用返回的 hall_url;有历史时使用 history_url,直接跳转,无需拼接地址。

4.8 成功响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "detail": {
          "banner": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_banner.png?x-oss-process=image/watermark,...",
          "big_icon": "https://res0.debug.minigame.vip/gc-assets/neo-adventure/neo-adventure_big_icon.png?x-oss-process=image/watermark,...",
          "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?x-oss-process=image/watermark,...",
          "m_icon": "https://res.minigame.vip/gc-assets/0/mg_corner.png",
          "name": "Neo Adventure",
          "orientation": "vertical",
          "small_icon": "https://res.minigame.vip/gc-assets/neo-adventure/neo-adventure_icon_small.png?x-oss-process=image/watermark,...",
          "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?x-oss-process=image/watermark,...",
          "big_icon": "https://res0.debug.minigame.vip/gc-assets/super-spy/super-spy_big_icon.png?x-oss-process=image/watermark,...",
          "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?x-oss-process=image/watermark,...",
          "m_icon": "https://res.minigame.vip/gc-assets/0/mg_corner.png",
          "name": "Super Spy",
          "orientation": "vertical",
          "small_icon": "https://res.minigame.vip/gc-assets/super-spy/super-spy_icon_small.png?x-oss-process=image/watermark,...",
          "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"
      }
    ],
    "m_icon_mode": "composited",
    "request_id": "925c0a74287d00a5a0588c1726b542a4",
    "total": 2
  },
  "ts": 1775723742
}

4.9 失败响应及错误码

组件接口业务错误通常以 HTTP 200 返回,必须检查响应中的 code;只有 code=200 才表示业务成功。

codemessage含义及处理
400new components only accept page=1 or no page三种新组件分页参数非法,请省略或传 1
400app_ids is only supported by historyGames新游或随机组件传入非空 app_ids
400app_ids exceeds 4096 bytes原始字符串长度超限
400app_ids contains an invalid game ID包含空段或非法 ID
400app_ids supports at most 20 unique game IDs去重后数量超限
401invalid signature签名错误,核对原始参数和凭据
401get secret failed, please check it out.商户凭据无法获取,请核对商户及凭据状态
404game slot not found or unavailableSlot 归属检查未通过,请使用当前商户的 Slot
500slot unavailableSlot 不可用;不存在、停用等其他分支也可能返回 500,具体 message 以响应为准
503new game data is not ready新游数据尚未就绪;新游请求暂不可用,保留现有内容后重试
500paging session expired, please request from page 1GameFlow 会话过期,重新请求第 1 页
500paging session invalid, please request from page 1GameFlow 会话不可继续使用,重新请求第 1 页

其他数据加载错误同样按失败处理,不清理历史记录。典型响应(时间戳为示例):

{"code":400,"message":"app_ids supports at most 20 unique game IDs","ts":1790000123}
{"code":503,"message":"new game data is not ready","ts":1790000123}
{
  "code": 401,
  "message": "invalid signature",
  "ts": 1773735959
}

4.10 M 标 icon 适配规范

游戏素材已支持 M 标 icon(游戏角标,标识游戏由 MiniGame.Com 提供)。M 标由服务端合成进图片素材,绝大多数场景客户端零适配、按 URL 直接渲染即可。请严格按响应中的 m_icon_mode 字段分支处理:

m_icon_mode = composited(bigCard、bigVideo、threeCards 返回此模式)

  • 以下图片素材的右下角已由服务端合成 M 标角标,客户端直接加载渲染即可,不要再自行叠加任何角标(否则会出现双重 M 标):

    • bigCard / bigVideo:封面图(banner、big_icon)及下方横条小图标(icon、small_icon)

    • threeCards:竖卡主图(flash、banner)

  • 唯一例外是视频:bigVideo 的 video(mp4)无法服务端合成。播放视频时,请客户端将 items[].detail.m_icon 返回的官方角标图叠加到视频画面右下角(尺寸比例参考第 7 章 UI 标注中 bigvideo 封面图上的角标)。

  • 已合成角标的素材 URL 带有 ?x-oss-process=image/watermark,... 参数,属正常现象,请原样使用。

m_icon_mode = overlay(gameFlow、gameCenter 等不合成角标的组件返回此模式)

  • 素材不含角标、URL 不带处理参数,客户端无需做任何 M 标处理。

4.11 游戏中心大厅组件(gameCenter)

gameCenter 是一类特殊组件,用于动态获取游戏中心大厅链接。大厅组件的 slot_id 由 MiniGame.Com 技术人员创建并提供。

请求方式:与普通组件完全一致(同一接口、同一签名规则),仅需传入大厅组件的 slot_id。

响应特点:不返回游戏列表(items 为空、total=0),hall_url 字段为完整大厅链接,客户端直接使用返回值跳转。

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [],
    "request_id": "925c0a74287d00a5a0588c1726b542a4",
    "total": 0,
    "hall_url": "https://games.example/?slot_id=GAME_CENTER_SLOT#request_id=925c0a74287d00a5a0588c1726b542a4",
    "m_icon_mode": "overlay"
  },
  "ts": 1775723742
}

接入要求:

  • 请在用户进入游戏中心入口时(或以不超过 1 天的周期缓存)通过本接口动态获取 hall_url,禁止将大厅 URL 写死在客户端。域名可能因运营需要调整,动态获取可保证无需发版即自动生效。

  • 游戏中心入口的曝光/点击埋点:使用事件回传 API 正常上报 show / click 事件,slot_id 传大厅组件的 slot_id,content_ids 传固定值 game_center。

  • 入口图标出现在可视区域时上报一次曝光;被用户真实点击时上报一次点击。

5. 用户行为事件回传 API

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

5.1 接口描述

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

5.2 基本信息

环境接口 URL
测试环境https://stats-sandbox.minigame.com/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...计算签名,未传值字段不参与签名
ts事件触发时刻对应的时间戳int是1749193616使用当前秒级时间戳,并将原值参与签名
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 签名示例

事件回传签名包含实际发送的非空请求体参数及请求头 ts(参考5.7);签名时保留字段原值。下例为独立参数示例,5.9的请求需用它自身的参数重新签名。

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": "aqua-funny-park, super-spy",
  "country": "cn",
  "language": "zh",
  "orientation": "vertical",
  "user_id": "123341",
  "session_id": "a0ba8227028cff0d4029905c0ededccb",
  "device_id": "8587a1b8e654070c",
  "device_brand": "OPPO",
  "device_model": "CPH2269",
  "app_id": "com.unite.demo",
  "device_type": "mobile",
  "viewport": "720x1456",
  "app_version": "v1.0.0",
  "slot_id": "TSZ3R9W6P2K8",
  "ts": 1790000123
});

console.log(sign);

输出示例:

8f8a9e4ba8425b3b62aa15dc3b54eaa0713e40d9e24db60c084e91e0ff98b65e

5.9 POST 请求示例

各游戏列表组件(包括新游、随机和历史组件)共用以下事件接口、字段及签名规则。曝光请求示例:

curl -X POST "https://stats-sandbox.minigame.com/api/wy/report/show" \ 
  -H "Content-Type: application/json" \ 
  -H "sign: c48c9fc90824d9654fe6da696e59281ae503e933ba32ef04169990b52d8a4eba" \ 
  -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"
  }'

点击上报沿用上述请求结构,将路径替换为 /api/wy/report/click,content_ids 改为实际点击的游戏 ID,使用当次事件时间戳并按实际参数重新签名。

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 对接常见问题

  • 游戏中心大厅链接请通过已开通的 gameCenter 或 historyGames 响应的 hall_url 动态获取并直接跳转,不从游戏链接截取域名,也不自行拼接路径。历史页直接使用 history_url,见 4.7。

  • 游戏中心的曝光与点击事件通过事件回传 API 上报:已开通 gameCenter 大厅组件的,slot_id 传大厅组件的 slot_id、content_ids 传 game_center;未开通大厅组件的,跟随其中一个组件的 slot_id 上报。

  • 当游戏中心的图标出现在可视区域时,需上报一次曝光;当游戏中心的图标被用户真实点击时,需上报一次点击。

  • gameFlow 跨页会重复游戏吗?首次请求会生成并缓存固定游戏序列;后续每页复用第一页返回的同一 request_id,按每页 10 个顺序切片返回,因此同一有效分页会话内不会跨页重复。该会话有效期约 60 分钟;续页保持相同商户、Slot、语言/国家及方向参数,不跨组件复用会话。游戏可用性变化可能使续页数量减少。未传、换传或过期 request_id 时,应从第 1 页重新开始,否则可能出现重复或分页会话过期错误。若收到会话失效或不可用错误,重新从第 1 页获取,不继续重试旧会话。

  • 支持哪些埋点和归因?标准事件回传支持 show、click、vplay 三类事件,用于用户行为数据回传、统计分析与推荐效果评估。游戏链接会携带 request_id,用于关联本次推荐请求。此外,游戏内会提供游戏时长事件;该事件未在当前 API 文档中详细介绍,如有需要请联系 MiniGame.Com 技术人员获取接入说明。如需接入其他事件、归因字段或定制化归因链路,请联系 MiniGame.Com 技术人员确认对接方案。

6.2 常见错误

错误说明处理建议
invalid signature签名校验失败检查参数范围、排序、api_key、ts 和 slot_id 是否正确
contentIds is required事件回传缺少内容 ID检查 content_ids 是否传入且字段名正确
slot_id is required缺少组件 ID组件 API 和事件回传 API 都需要传入 slot_id
game slot not found or unavailableSlot 归属检查未通过确认 slot_id 属于当前商户;其他不可用分支见4.9

6.3 常用国家代码

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

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

6.4 常用语言代码

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

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

6.5 界面适配与交互注意事项

为了提供顺畅的游戏体验并保障广告模块的正常运行,请在对接时留意以下界面的适配与图层管理,避免因 UI 遮挡影响用户的正常操作。

1. 顶部区域适配(关闭按钮防遮挡)

  • 注意事项:广告页面的顶部通常会展示"关闭"或"跳过"按钮。请留意 iOS 与 Android 设备的安全区(如刘海屏、挖孔屏)适配。

  • 对接建议:请尽量避免 App 的状态栏或自定义顶部导航栏覆盖在本页面上方,以确保用户可以顺畅点击关闭按钮。无论 iOS 还是安卓,都要避免我们的页面覆盖到顶部导致广告关闭按钮无法正常点击。

2. 底部及全局元素管理

  • 注意事项:游戏的核心交互区域以及广告的转化按钮、合规文本等关键信息,通常分布在页面中下部及边缘。

  • 对接建议:在进入页面时,建议 App 配合隐藏底部导航栏(Tab Bar),并暂缓展示全局悬浮组件(如客服球、业务活动弹窗等),避免对当前页面的视觉或点击交互造成阻挡。

3. 客户端适配建议

  • 视图层级:请确保当前接入的页面能够正常处于前端展示,不被宿主原生 View 覆盖。

  • 悬浮组件:页面唤起期间,建议妥善管理并隐藏非必要的全局 UI 组件。

💡 提示:保持页面元素的完整展示与交互按钮的可点击状态,不仅能提升用户的体验与整体广告转化表现,也有助于避免触发广告的展示合规限制。


7 UI标注

  • bigcard UI标注
    bigcard.png#585px #454px


  • bigvideo UI标注
    bigvideo.png#585px #585px


  • threecard UI标注
    threecard.png#585px #379px

更新日志

版本日期更新内容
v4.7.02026-11-04新增新游、随机和历史组件调用说明;补充 app_ids 签名、上架时间、完整入口链接、空结果与错误、刷新/历史使用及事件示例。
v4.6.02026-08-21术语更新:将承载游戏位的模块统一称为“组件”,将单个进入游戏的接口定义为“游戏位”;将“游戏位 ID”统一调整为“组件 ID”;补充 gameFlow 跨页去重、分页会话有效期,以及标准埋点与归因支持的对接常见问题。
v4.5.02026-07-20① 新增 gameCenter 游戏中心大厅位:请求返回大厅域名 hall_url,大厅链接改为从 API 动态获取(4.11);② 游戏素材新增 M 标 icon:threeCards、bigCard、bigVideo 封面及 bigCard、bigVideo 下方横条 icon 图右下角由服务端合成 M 标,新增响应字段 m_icon_mode、items[].detail.m_icon,视频由客户端叠加(4.10);③ 事件回传验签兼容 event_id:签名带或不带 event_id 均可通过(3.2);④ api_key 改为商户在商户平台「控制台 → 账号信息 → Api Key Secret」自行创建获取(3.1)。
v4.4.02026-07-02新增分布式游戏中心(TAB)对接说明(大厅域名需从游戏位接口动态获取、曝光/点击事件跟随游戏位上报);新增「界面适配与交互注意事项(顶部关闭按钮防遮挡)」章节;补充 bigcard、bigvideo、threecardsUI 标注示例图。
v4.3.02026-05-08事件回传 API 新增游戏视频播放 vplay 事件,新增 threeCards类型三联卡片position上报。
v4.2.02026-03-17多游戏位请求、内嵌 tracker URL、HMAC-SHA256 签名
v4.1.02026-03-15统一响应结构、新增分页参数、补充错误码

技术支持

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

商务对接
商务对接
公众号
公众号