Game Slot OpenAPI-V4 Integration Guide

1. Overview

1.1 Product Introduction

OpenAPI-V4 Game Slot is designed for client-side game content consumption scenarios of partner channels. It supports native apps, web, WebView, mini programs, and other carriers. This API provides standardized HTML5 game list retrieval capabilities, helping channels quickly build personalized game recommendation modules.

1.2 Core Capabilities

Multi-dimensional filtering: Retrieve playable HTML5 game lists by channel, language, country, game category, screen orientation, and other conditions.
Intelligent ranking: MiniGame AI combines localized user behavior preferences, revenue performance, and other factors to generate personalized recommendations.
Data closed loop: Clients need to report user behavior events such as exposure, click, and video playback so that recommendation quality, statistics, and attribution can be continuously optimized.
Style adaptation: Supports different game slot types, including large card, three-card layout, video, and game feed.

1.3 Usage Flow

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 Terminology

Term	Description
`client_id`	Unique merchant identifier assigned by Weiyou Interactive. It is passed through the `x-md-global-cid` request header.
`api_key`	API access key provided by Weiyou Interactive technical staff. It is used to generate `sign`.
`slot_id`	Game slot ID created and provided by Weiyou Interactive technical or operations staff.
`request_id`	Request ID used for tracing one recommendation request. It must be passed again when paginating `gameFlow`.
`content_ids`	List of game App IDs used for event reporting. Multiple games can be separated by English commas.

2. Environments and Test Parameters

2.1 API Environments

Environment	Game Slot API `HOST_PREFIX`	Event Reporting API
Test	`https://mdev.minigamevs.com/openapiv4_service`	`https://mdev.minigamevs.com/stats_service/api/wy/report/{event_id}`
Production	`https://openapi.minigame.ai`	`https://stats.minigame.com/api/wy/report/{event_id}`

Full game slot API path:

{HOST_PREFIX}/openapi/v4/game/slot

2.2 Test Environment Parameters

Parameter	Value	Description
`client_id`	`233802991579168768`	Merchant ID. Use this value in the `x-md-global-cid` request header.
`api_key`	`5e567421-c0a5-4723-80a6-2f5567517146`	API access key used to generate `sign`.
`slot_id`	`TSZ3R9W6P2K8`	`bigCard` type
`slot_id`	`TSK9P4X1Q6B2`	`threeCards` type
`slot_id`	`TSB4F2H8Y3Q7`	`bigVideo` type

Test parameters are only for development and debugging. Before production launch, contact Weiyou Interactive for production environment parameters and keep test and production configurations isolated.

3. Signature Verification Rules

3.1 Getting Keys

client_id and api_key are provided by Weiyou Interactive technical staff. api_key is used to generate signatures and should be protected carefully. It is not recommended to expose it directly in a client-readable location.

3.2 Parameter Scope

All API request parameters must participate in signing according to the rules. Empty fields do not participate in signing.

Parameters included in signing:

URL query parameters, such as slot_id, user_id, and country in the game slot API.
POST request body parameters, such as content_ids, slot_id, and display_duration in the event reporting API.
The ts timestamp in the HTTP Header.
The path parameter event_id of the event reporting API.

Fields not included in signing:

sign itself.
x-md-global-cid.
x-user-ip.
request_id in gameFlow pagination scenarios.
Empty fields.

3.3 Concatenation Rules

Concatenate all signing parameters as parameter_name=parameter_value.
Use & between multiple parameters.
Sort all parameters by parameter name in ascending ASCII order.
Empty parameters do not participate in signing.

Concatenation format example:

key1=value1&key2=value2

3.4 Signature Generation

Prefix the concatenated parameter string with api_key.
Apply SHA256 hashing to the resulting string.
The generated hexadecimal hash is the final sign string.

Formula:

sign = SHA256(api_key + sorted_parameter_string)

3.5 Signature Example

The following example uses a fixed ts for reproducibility. In real integration, ts should use the current Unix timestamp in seconds.

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);

Output:

{
  "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 Signature Troubleshooting

Issue	Common Cause	Recommended Handling
`invalid signature`	Parameter sorting is inconsistent	Print the parameter names participating in signing and confirm ASCII sorting
`invalid signature`	`ts` was not included in signing	Explicitly add the request header `ts` to the signing parameters
`invalid signature`	Empty fields participated in signing	Filter `null`, empty strings, and omitted fields
`invalid signature`	`request_id` was included in game slot pagination signing	`request_id` for `gameFlow` pagination does not participate in signing
`invalid signature`	`event_id` was not included for the event API	The event reporting API must include the path parameter `event_id` in signing
`timestamp expired`	Client or server time is inaccurate	Use a seconds-level timestamp and keep it within the ±5 minute validity window

4. Game Slot API

4.1 API Description

This API retrieves a personalized recommended game list for a specified game slot. It is used for recommendation modules on home pages, detail pages, recommendation positions, game feeds, and similar placements. The response includes game metadata, rendering assets, and channel-specific game links.

Core logic:

Return a personalized recommendation list based on game slot type and context information.
Game metadata such as name, description, and how-to-play is returned in the corresponding localized version based on country and language parameters.
Asset URLs are returned according to the size requirements of different game slot styles, including icons, card backgrounds, banners, splash images, videos, and other CDN resources.
Game links are channel-specific URLs and usually include attribution parameters such as request_id.

Redundancy strategy:

To ensure display quality and fault tolerance for recommendation slots, non-paginated game slots use a 1:1 redundancy mechanism.
If a game slot needs to display n games, the API returns 2n game records for client-side selection or fallback.
Example: a bigCard slot displays only 1 game, and the API returns 2 games.

4.2 Basic Information

Item	Value
Method	`GET`
Path	`/openapi/v4/game/slot`
Full URL	`{HOST_PREFIX}/openapi/v4/game/slot`
Content-Type	No request body

4.3 Game Slot Types

Type	Description	Returned Game Count	Pagination	Notes
`bigCard`	Large card	`1 + 1` backup	No	This style displays 1 game, and the API provides 1 additional backup game
`gameFlow`	Game feed	Curated library	Yes	Returns curated games by page, 10 games per page; pagination parameters are required, and from page 2 onward, pass the `request_id` returned by the previous page
`threeCards`	Three-card layout	`3 + 3` backup	No	Displays 3 games. It is recommended to refresh one group when the user returns to the page and the display duration exceeds 1 minute
`bigVideo`	Video	`1 + 1` backup	No	Video auto-plays muted when it enters the visible viewport

4.4 Request Headers

Name	Description	Type	Required	Example	Notes
`sign`	Signature	`string`	Yes	`1ac91fb23ab2b...`	Generated according to Signature Verification Rules
`ts`	Timestamp	`int`	Yes	`1749193616`	10-digit seconds-level timestamp, valid within ±5 minutes
`x-md-global-cid`	Unique merchant identifier	`int`	Yes	`233802991579168768`	Corresponds to `client_id`

4.5 Request Parameters

Name	Description	Type	Required	Example	Notes
`slot_id`	Game slot ID	`string`	Yes	`TSZ3R9W6P2K8`	Use the corresponding ID based on game slot type
`user_id`	User ID	`string`	No	`123456`	Recommended; can use the channel-side Open UID
`device_id`	Device ID	`string`	No	`01c081dd1edc`	Recommended; can use GAID or a channel-side device identifier
`device_brand`	Device brand	`string`	No	`XIAOMI`	Device brand
`device_model`	Device model	`string`	No	`Note 13 Pro`	Device model
`language`	Language standard code	`string`	No	`zh`	Recommended; prioritizes games suitable for this language, not a strict filter
`country`	Country standard code	`string`	No	`CN`	Prioritizes games suitable for this country, not a strict filter
`categories`	Game categories	`string`	No	`puzzle,casual`	Use English commas for multiple categories; if category filtering is not enabled for the slot, backend configuration prevails
`orientation`	Screen orientation	`string`	No	`vertical`	Used to filter games adapted to screen orientation; values: `horizontal`, `vertical`
`page`	Page number	`int`	No	`1`	Some slot types support pagination, such as `gameFlow`; defaults to page 1
`request_id`	Request ID	`string`	Required from page 2 onward for `gameFlow`	`5e2ef168670507758a992fcbac140910`	For `gameFlow`, page 1 can pass an empty string, and page 2 onward must pass the `request_id` returned by the previous page; it does not participate in signing

4.6 Request Example

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 Response Fields

Name	Description	Type	Example	Notes
`request_id`	Request ID	`string`	`b4f67172-a9dd-4d10-ab04-011faedc2867`	Uniquely identifies this recommendation request
`total`	Game count	`int`	`860`	Number of games under the current response or pagination condition
`items`	Game list	`array`	-	Game array
`items[].id`	Game App ID	`string`	`neo-adventure`	Content ID used for event reporting
`items[].link`	Game link	`string`	-	Link automatically includes `request_id` and other parameters
`items[].detail`	Game information	`object`	-	Game metadata and assets
`items[].detail.name`	Game name	`string`	`Neo Adventure`	Returned in the localized version based on country or language
`items[].detail.categories`	Game categories	`array`	`["puzzle", "io"]`	A game may have one or more categories
`items[].detail.how_to_play`	How to play	`string`	`Follow hints and defeat monsters.`	Gameplay instructions
`items[].detail.description`	Game description	`string`	`Help Neo finish the adventure.`	Game introduction
`items[].detail.orientation`	Screen orientation	`string`	`vertical`	Values: `horizontal`, `vertical`
`items[].detail.icon`	Game icon	`object` or `string`	-	URL
`items[].detail.small_icon`	Small game icon	`string`	-	URL
`items[].detail.big_icon`	Large game icon	`string`	-	URL
`items[].detail.banner`	Game banner	`string`	-	URL
`items[].detail.flash`	Game splash image	`string`	-	URL
`items[].detail.video`	Game video	`string`	-	URL

4.8 Successful Response Example

{
  "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 Failed Response Example

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

5. User Behavior Event Reporting API

2026-05-08 update: The event reporting API adds the x-user-ip request header and the slot_id request body field.

5.1 API Description

The user behavior event reporting API receives user behavior events reported by the client, such as game exposure, game click, and video playback. Partners need to report event data to this API for statistics, performance analysis, recommendation optimization, and attribution.

5.2 Basic Information

Environment	API URL
Test	`https://mdev.minigamevs.com/stats_service/api/wy/report/{event_id}`
Production	`https://stats.minigame.com/api/wy/report/{event_id}`

Test parameters:

Parameter	Value	Description
`client_id`	`233802991579168768`	Merchant ID. Use this value in the `x-md-global-cid` request header.
`api_key`	`5e567421-c0a5-4723-80a6-2f5567517146`	API access key used to generate `sign`.

5.3 Supported Event Types

`event_id`	Event Name	Trigger Timing	Description
`show`	Exposure event	When the game slot is displayed	Triggered when a game card or asset enters the visible viewport
`click`	Click event	When the game slot is clicked	Triggered when the user clicks the game slot and starts navigation
`vplay`	Playback event	Video play and pause	Records playback time when the video starts and stops

5.4 Request Method

The event reporting API supports both GET and POST.

GET requests pass parameters through the URL Query String:

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

POST requests pass parameters through a JSON Body:

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

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

5.5 Request Headers

Name	Description	Type	Required	Example	Notes
`sign`	Signature	`string`	Yes	`05c56a07a720...`	Signature parameters must include the path parameter `event_id`; fields without values do not participate in signing
`ts`	Timestamp corresponding to the event trigger time	`int`	Yes	`1749193616`	10-digit seconds-level timestamp, valid within ±5 minutes
`x-md-global-cid`	Unique merchant identifier	`int`	Yes	`233802991579168768`	Corresponds to `client_id`
`x-user-ip`	User IP	`string`	No	`183.23.63.82`	Recommended for server-side reporting

5.6 Path Parameters

Field	Description	Type	Required	Example	Notes
`event_id`	Event name	`string`	Yes	`show`	Allowed values: `show`, `click`, `vplay`

5.7 Request Body Fields

Field	Description	Type	Required	Example	Notes
`content_ids`	Content ID list	`string`	Yes	`neo-adventure,super-spy`	Game App IDs. Multiple games can be separated by English commas.
`slot_id`	Game slot ID	`string`	Yes	`TSZ3R9W6P2K8`	Use the corresponding ID based on game slot type
`session_id`	Session ID	`string`	No	`abcdefg123`	Used to analyze the user's single-visit behavior path
`device_id`	Device ID	`string`	No	`d52ad7b6-5c86-4131-a79f-7236f7b183e2`	Unique device identifier
`device_brand`	Device brand	`string`	No	`XIAOMI`	Device brand
`device_model`	Device model	`string`	No	`Note 13 Pro`	Device model
`app_id`	App ID	`string`	No	`com.unite.demo`	Android or iOS app ID or package name
`device_type`	Device type	`string`	No	`mobile`	Values: `desktop`, `mobile`, `tablet`, `other`
`orientation`	Screen orientation	`string`	No	`vertical`	Values: `horizontal`, `vertical`
`user_id`	User ID	`string`	No	`10011`	Unique user identifier, such as logged-in user ID
`country`	Country standard code	`string`	No	`CN`	User country
`language`	Language standard code	`string`	No	`zh`	User language
`display_duration`	Display duration	`int`	No	`120`	Time the game is displayed on screen, in seconds
`viewport`	Viewport size	`string`	No	`540x960`	Viewport size for game display, in width x height format
`app_version`	App version	`string`	No	`v1.0.0`	Version number for each app release
`play_start_ts`	Playback start time	`int64`	No	`1778146175764`	Millisecond timestamp, passed for playback events
`play_stop_ts`	Playback stop time	`int64`	No	`1778146177226`	Millisecond timestamp, passed for playback events
`play_duration`	Playback duration	`int64`	No	`1462`	In milliseconds, passed for playback events
`position`	Display position	`string`	No	`1` or `1,2,3`	Index position of each exposed card for `threeCards`; the index cannot be 0

5.8 Signature Example

The event reporting API signature parameters must include the path parameter 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);

Output:

05c56a07a72076ac8ea0f9c667b2a5b2a417c2226a33819885833de8b093eb0e

5.9 POST Request Example

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 Response Fields

Name	Description	Type	Example	Notes
`received`	Successful count	`int`	`1`	Number of successfully received events
`tid`	Trace ID	`string`	`a7fc67356697492a92ee8b3054a6a3b8`	Recommended to record for failure diagnosis

Successful response example:

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

Failed response example:

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

5.11 Reporting Recommendations

The show event should be triggered when a game card or asset enters the visible viewport.
The click event should be triggered when the user clicks the game slot and starts navigation.
The vplay event is used for game video playback records. It is recommended to pass play_start_ts, play_stop_ts, and play_duration.
Avoid reporting the same game and same event repeatedly within the same display cycle.
When network transmission uses proxy reporting, it is recommended to configure the x-user-ip header for data analysis.
Event reporting failures should not block users from opening games or continuing browsing.

6. Appendix

6.1 Common Errors

Error	Description	Recommended Handling
`invalid signature`	Signature verification failed	Check parameter scope, sorting, `api_key`, `ts`, and `event_id`
`timestamp expired`	Timestamp expired	Use a seconds-level timestamp and keep it within ±5 minutes
`contentIds is required`	Event reporting is missing content IDs	Check that `content_ids` is provided and the field name is correct
`slot_id is required`	Missing game slot ID	Both the game slot API and event reporting API require `slot_id`
`invalid slot_id`	Game slot does not exist or access is not authorized	Confirm that `slot_id` belongs to the current merchant

6.2 Common Country Codes

Code	Country/Region
`CN`	Mainland China
`TW`	Taiwan, China
`HK`	Hong Kong, China
`JP`	Japan
`KR`	South Korea
`US`	United States
`GB`	United Kingdom
`DE`	Germany
`FR`	France
`BR`	Brazil
`ID`	Indonesia
`TH`	Thailand
`VN`	Vietnam
`MY`	Malaysia
`PH`	Philippines
`SG`	Singapore

For the full list, see ISO 3166-1 alpha-2.

6.3 Common Language Codes

Code	Language
`zh`	Chinese
`en`	English
`ja`	Japanese
`ko`	Korean
`es`	Spanish
`pt`	Portuguese
`fr`	French
`de`	German
`id`	Indonesian
`th`	Thai
`vi`	Vietnamese
`ms`	Malay
`ar`	Arabic

For the full list, see ISO 639-1.

Changelog

Version	Date	Changes
v4.3.0	2026-05-08	Added the `vplay` game video playback event to the event reporting API, and added `position` reporting for `threeCards` three-card layout.
v4.2.0	2026-03-17	Multi-slot request, embedded tracker URL, HMAC-SHA256 signature
v4.1.0	2026-03-15	Unified response structure, added pagination parameters, added error codes

Technical Support

If you have questions, contact the MiniGame technical support team.

Outline