OpenAPI-V4 对接文档
1. 概述
1.1 产品介绍
OpenAPI-V4 组件专为合作渠道的客户端游戏内容消费场景设计,支持原生 App、Web、WebView、小程序等多种载体。本接口提供标准化的 H5 游戏内容列表获取能力,帮助渠道方快速构建个性化游戏推荐模块。
1.2 核心能力
多维度筛选:支持按渠道、语言、国家、游戏类别、屏幕方向等条件获取可玩的 H5 游戏列表。
智能排序:基于 MiniGame AI 算法,融合本地化用户行为偏好、收入表现等多重因子进行个性化推荐。
数据闭环:客户端需要接入曝光、点击、视频播放等用户行为事件回传机制,用于持续优化推荐效果、数据统计和归因分析。
样式适配:支持大卡片、三联卡片、视频、游戏信息流等不同组件类型。
1.3 使用流程
1.4 术语定义
| 术语 | 说明 |
|---|---|
client_id | 商户唯一标识,由 MiniGame.Com 分配,请求头中使用 x-md-global-cid 传递 |
api_key | API 访问密钥,由商户在商户平台自行创建获取(见密钥获取),用于生成 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.ai | https://stats-sandbox.minigame.com/api/wy/report/{event_id} |
| 正式环境 | https://openapi.minigame.ai | https://stats.minigame.com/api/wy/report/{event_id} |
组件接口完整路径:
2.2 测试环境参数
| 参数 | 值 | 说明 |
|---|---|---|
client_id | 233802991579168768 | 商户 ID,请求头 x-md-global-cid 使用该值 |
api_key | 5e567421-c0a5-4723-80a6-2f5567517146 | API 访问密钥,用于生成 sign |
slot_id | TSZ3R9W6P2K8 | bigCard 类型 |
slot_id | TSK9P4X1Q6B2 | threeCards 类型 |
slot_id | TSB4F2H8Y3Q7 | bigVideo 类型 |
slot_id | GCTESTHALL01 | gameCenter 游戏中心大厅组件 |
测试参数仅用于开发联调。正式上线前请联系 MiniGame.Com 获取正式环境
client_id与组件 ID(slot_id),正式环境api_key请在商户平台自行创建获取(见密钥获取),并确保测试环境和正式环境配置隔离。
3. 签名校验规则
3.1 密钥获取
client_id 由 MiniGame.Com 技术人员提供。
api_key 由商户在商户平台自行创建获取:登录商户平台,进入「控制台」菜单栏的「账号信息」页面,在「Api Key」处点击创建,得到的参数即为 api_key。如不慎遗忘,可删除后重建。可通过以下链接快捷进入该页面:
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 拼接规则
将参与签名的参数按照
参数名=参数值的格式拼接。多个参数之间使用
&连接。所有参数按照参数名 ASCII 码从小到大排序。
空值参数不参与签名。
拼接格式示例:
3.4 签名生成
将拼接好的参数字符串前面追加
api_key。对追加后的字符串进行 SHA256 哈希运算。
生成的十六进制哈希值即为最终签名字符串
sign。
公式:
3.5 签名示例
以下示例使用固定 ts 便于复现。实际接入时,ts 应使用当前秒级时间戳。
输出示例:
历史组件的 app_ids 使用实际发送、URL 解码后的原始字符串参与签名,不能先去空格、去重或改变顺序。URL 编码在签名后进行。例如:
新游组件(newGames)、随机组件(randomGames)和历史组件(historyGames)无需传 request_id;成功响应会返回新的 request_id。
3.6 签名排查建议
| 问题 | 常见原因 | 处理建议 |
|---|---|---|
invalid signature | 参数排序不一致 | 打印参与签名的参数名并确认 ASCII 排序 |
invalid signature | ts 未参与签名 | 将请求头 ts 显式加入签名参数 |
invalid signature | 空值字段参与签名 | 过滤 null、空字符串和未传字段 |
invalid signature | app_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 | 组件 ID | string | 是 | TSZ3R9W6P2K8 | 根据组件类型使用对应 ID |
user_id | 用户 ID | string | 否 | 123456 | 建议传入,可使用渠道侧 Open UID |
device_id | 设备 ID | string | 否 | 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,显式 0、负数或大于 1 报错 |
request_id | 请求 ID | string | gameFlow 第 2 页起必填 | 5e2ef168670507758a992fcbac140910 | gameFlow 第一页可省略,第 2 页起传同一会话的 request_id;沿用不签此字段的方式。三种新组件不使用分页会话,省略此参数;传入也不会续页或复用响应 ID |
app_ids | 待查询游戏 ID | string | 否 | 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 请求示例
历史组件查询指定游戏时,在上述请求中增加以下参数,并按实际参数重新签名(参数名为 app_ids,不是上报中的宿主应用字段 app_id):
4.7 响应字段
| 名称 | 描述 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|
request_id | 请求 ID | string | b4f67172-a9dd-4d10-ab04-011faedc2867 | 唯一标识本次推荐请求 |
total | 游戏数量 | int | 860 | gameFlow 为当前分页会话游戏总数;三种新组件为本次实际返回数量(新游包含备用游戏),不是候选总量;gameCenter 固定为 0 |
m_icon_mode | M 标接入模式 | string | composited | composited=图片素材已由服务端合成 M 标角标,客户端勿再叠加;overlay=素材不含角标。按组件类型返回,详见 4.10 |
hall_url | 完整大厅链接 | string | https://games.example/?slot_id=HISTORY_SLOT#request_id=history-request | gameCenter 和 historyGames 返回;客户端直接使用返回值跳转,无需拼接域名或路径 |
history_url | 完整历史页链接 | string | https://games.example/fr/recetlyplayed?slot_id=HISTORY_SLOT#request_id=history-request | 仅 historyGames 返回;当前站点、当前语言的完整入口,直接跳转,无需自行拼接 |
items | 游戏列表 | array | - | 游戏数组 |
items[].id | 游戏 App ID | string | neo-adventure | 用于事件回传的内容 ID |
items[].link | 游戏链接 | string | - | 链接会自动带上 request_id 等参数 |
items[].detail | 游戏信息 | object | - | 游戏元信息和素材 |
items[].detail.new_game_published_at | 上架时间 | integer 或 null | 1790000000 | 仅 newGames 返回,UTC Unix 秒(不是毫秒或字符串);null 表示时间未知,不显示推算的上架文案 |
items[].detail.name | 游戏名称 | string | Neo Adventure | 按国家或语言返回对应版本 |
items[].detail.categories | 游戏分类 | array | ["puzzle", "io"] | 一个游戏可有一个或多个分类 |
items[].detail.how_to_play | 游戏玩法 | string | Follow hints and defeat monsters. | 玩法说明 |
items[].detail.description | 游戏简介 | string | Help Neo finish the adventure. | 游戏介绍 |
items[].detail.orientation | 屏幕方向 | string | vertical | 可选 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_icon | M 标角标图 | string | https://res.minigame.vip/gc-assets/0/mg_corner.png | m_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 成功响应示例
4.9 失败响应及错误码
组件接口业务错误通常以 HTTP 200 返回,必须检查响应中的 code;只有 code=200 才表示业务成功。
| code | message | 含义及处理 |
|---|---|---|
| 400 | new components only accept page=1 or no page | 三种新组件分页参数非法,请省略或传 1 |
| 400 | app_ids is only supported by historyGames | 新游或随机组件传入非空 app_ids |
| 400 | app_ids exceeds 4096 bytes | 原始字符串长度超限 |
| 400 | app_ids contains an invalid game ID | 包含空段或非法 ID |
| 400 | app_ids supports at most 20 unique game IDs | 去重后数量超限 |
| 401 | invalid signature | 签名错误,核对原始参数和凭据 |
| 401 | get secret failed, please check it out. | 商户凭据无法获取,请核对商户及凭据状态 |
| 404 | game slot not found or unavailable | Slot 归属检查未通过,请使用当前商户的 Slot |
| 500 | slot unavailable | Slot 不可用;不存在、停用等其他分支也可能返回 500,具体 message 以响应为准 |
| 503 | new game data is not ready | 新游数据尚未就绪;新游请求暂不可用,保留现有内容后重试 |
| 500 | paging session expired, please request from page 1 | GameFlow 会话过期,重新请求第 1 页 |
| 500 | paging session invalid, please request from page 1 | GameFlow 会话不可继续使用,重新请求第 1 页 |
其他数据加载错误同样按失败处理,不清理历史记录。典型响应(时间戳为示例):
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 字段为完整大厅链接,客户端直接使用返回值跳转。
响应示例:
接入要求:
请在用户进入游戏中心入口时(或以不超过 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_id | 233802991579168768 | 商户 ID,请求头 x-md-global-cid 使用该值 |
api_key | 5e567421-c0a5-4723-80a6-2f5567517146 | API 访问密钥,用于生成 sign |
5.3 支持事件类型
event_id | 事件名称 | 触发时机 | 说明 |
|---|---|---|---|
show | 曝光事件 | 组件展示时 | 游戏卡片或素材进入屏幕可视区域时触发 |
click | 点击事件 | 游戏入口点击时 | 用户点击组件中的游戏入口并开始跳转时触发 |
vplay | 播放事件 | 视频播放与暂停 | 视频开始和停止播放时记录播放时间并上报 |
5.4 请求方式
事件回传 API 同时支持 GET 和 POST。
GET 请求通过 URL Query String 传参:
POST 请求通过 JSON Body 传参:
5.5 请求头
| 名称 | 描述 | 类型 | 必填 | 示例值 | 说明 |
|---|---|---|---|---|---|
sign | 签名 | string | 是 | 05c56a07a720... | 计算签名,未传值字段不参与签名 |
ts | 事件触发时刻对应的时间戳 | int | 是 | 1749193616 | 使用当前秒级时间戳,并将原值参与签名 |
x-md-global-cid | 商户唯一标识 | int | 是 | 233802991579168768 | 对应 client_id |
x-user-ip | 用户 IP | string | 否 | 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 | 组件 ID | string | 是 | TSZ3R9W6P2K8 | 根据组件类型传对应 ID |
session_id | 会话 ID | string | 否 | abcdefg123 | 用于分析用户单次访问行为路径 |
device_id | 设备 ID | string | 否 | d52ad7b6-5c86-4131-a79f-7236f7b183e2 | 设备唯一标识 |
device_brand | 设备品牌 | string | 否 | XIAOMI | 设备品牌 |
device_model | 设备机型 | string | 否 | Note 13 Pro | 设备型号 |
app_id | 应用 ID | string | 否 | com.unite.demo | 安卓或 iOS 应用 ID 或应用包名 |
device_type | 设备类型 | string | 否 | mobile | 可选 desktop、mobile、tablet、other |
orientation | 屏幕方向 | string | 否 | vertical | 可选 horizontal、vertical |
user_id | 用户 ID | string | 否 | 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,3 | threeCards类型每个被曝光卡片的索引位置,索引不能是0 |
5.8 签名示例
事件回传签名包含实际发送的非空请求体参数及请求头 ts(参考5.7);签名时保留字段原值。下例为独立参数示例,5.9的请求需用它自身的参数重新签名。
输出示例:
5.9 POST 请求示例
各游戏列表组件(包括新游、随机和历史组件)共用以下事件接口、字段及签名规则。曝光请求示例:
点击上报沿用上述请求结构,将路径替换为 /api/wy/report/click,content_ids 改为实际点击的游戏 ID,使用当次事件时间戳并按实际参数重新签名。
5.10 响应字段
| 名称 | 描述 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|
received | 成功数量 | int | 1 | 成功接收的事件数量 |
tid | 链路 ID | string | a7fc67356697492a92ee8b3054a6a3b8 | 失败排查时建议记录 |
成功响应示例:
失败响应示例:
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 unavailable | Slot 归属检查未通过 | 确认 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标注

bigvideo UI标注

threecard UI标注

更新日志
| 版本 | 日期 | 更新内容 |
|---|---|---|
| v4.7.0 | 2026-11-04 | 新增新游、随机和历史组件调用说明;补充 app_ids 签名、上架时间、完整入口链接、空结果与错误、刷新/历史使用及事件示例。 |
| v4.6.0 | 2026-08-21 | 术语更新:将承载游戏位的模块统一称为“组件”,将单个进入游戏的接口定义为“游戏位”;将“游戏位 ID”统一调整为“组件 ID”;补充 gameFlow 跨页去重、分页会话有效期,以及标准埋点与归因支持的对接常见问题。 |
| v4.5.0 | 2026-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.0 | 2026-07-02 | 新增分布式游戏中心(TAB)对接说明(大厅域名需从游戏位接口动态获取、曝光/点击事件跟随游戏位上报);新增「界面适配与交互注意事项(顶部关闭按钮防遮挡)」章节;补充 bigcard、bigvideo、threecardsUI 标注示例图。 |
| v4.3.0 | 2026-05-08 | 事件回传 API 新增游戏视频播放 vplay 事件,新增 threeCards类型三联卡片position上报。 |
| v4.2.0 | 2026-03-17 | 多游戏位请求、内嵌 tracker URL、HMAC-SHA256 签名 |
| v4.1.0 | 2026-03-15 | 统一响应结构、新增分页参数、补充错误码 |
技术支持
如有疑问,请联系MiniGame技术支持团队。



