logo微游H5出海开发者中心

游戏位OpenAPI-V4对接文档

1. 概述

1.1 产品介绍

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

1.2 核心能力

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

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

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

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

1.3 使用流程

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

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 类型
slot_idGCTESTHALL01gameCenter 游戏中心大厅位

测试参数仅用于开发联调。正式上线前请联系微游互娱获取正式环境 client_id 与游戏位 slot_id，正式环境 api_key 请在商户平台自行创建获取（见密钥获取），并确保测试环境和正式环境配置隔离。

3. 签名校验规则

3.1 密钥获取

client_id 由微游互娱技术人员提供。

api_key 由商户在商户平台自行创建获取：登录商户平台，进入「控制台」菜单栏的「账号信息」页面，在「Api Key Secret」部分创建，得到的参数即为 api_key。可通过以下链接快捷进入该页面：

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

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

3.2 参数范围

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

参与签名的参数范围：

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

  • 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://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事件回传的 position 未参与签名position 有值时必须参与签名
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 备用否视频进入可视区后自动静音播放
gameCenter游戏中心大厅位不返回游戏否不返回游戏列表，返回游戏中心大厅域名 hall_url，用于动态获取大厅链接，详见 4.11

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当前响应或分页条件下的游戏数量；gameCenter 位固定为 0
m_icon_modeM 标接入模式stringcompositedcomposited=图片素材已由服务端合成 M 标角标，客户端勿再叠加；overlay=素材不含角标。按游戏位类型返回，详见 4.10
hall_url游戏中心大厅域名stringhttps://abc.minigame.com仅 gameCenter 大厅位返回，其余游戏位为空，详见 4.11
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 地址
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 中的任何参数。

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 失败响应示例

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

4.10 M 标 icon 适配规范

游戏素材已支持 M 标 icon（游戏角标，标识游戏由微游互娱提供）。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 由微游互娱技术人员创建并提供。

请求方式：与普通游戏位完全一致（同一接口、同一签名规则），仅需传入大厅位的 slot_id。

响应特点：不返回游戏列表（items 为空、total=0），hall_url 字段即游戏中心大厅域名。

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [],
    "request_id": "925c0a74287d00a5a0588c1726b542a4",
    "total": 0,
    "hall_url": "https://abc.minigame.com",
    "m_icon_mode": "overlay"
  },
  "ts": 1775723742
}

接入要求：

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

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

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

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...计算签名，未传值字段不参与签名
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 的签名参数(参考5.7请求体字段)。

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",
  "orientation":"vertical"
});

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 分布式游戏中心的对接常见问题

  • 游戏中心大厅的 URL 须动态获取，不推荐直接使用固定 URL。推荐方式：请求 gameCenter 大厅位，取响应中的 hall_url 字段（见 4.11）。如贵方尚未开通大厅位，也可从分布式 API 任意游戏位接口返回的游戏链接中提取域名。例：游戏位返回 https://abc.minigame.com/en/game/2048fall/play/m?slot_id=123456#request_id=abcdef，取 abc.minigame.com 即为游戏中心大厅的目标域名。

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

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

6.2 常见错误

错误说明处理建议
invalid signature签名校验失败检查参数范围、排序、api_key、ts 和 slot_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.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.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技术支持团队。

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