跳到主要内容

平台方服务端集成

1 SDK集成​

详情请见 应用集成 - SDK集成 - [Android/iOS/PC]应用集成 - 快速集成

2 平台服务端集成​

2.1 Channel API​

面向第三方游戏平台,Minihost 提供 Channel API 接入能力来对托管在 Minihost 上的游戏内容和游戏包进行统一管理。

2.1.1 接入说明​

在进行 API 对接之前平台方需要获取对应的 Channel AccessToken 作为 API 访问密钥。

若 Channel AccessToken 泄露,请立即联系我们进行重置。

生产环境的 API 使用规则如下:

METHOD PATH HTTP/1.1
Host: minihost.tuanjie.cn
Authorization: Bearer <Channel AccessToken>

请求体和响应体默认均为 JSON 格式。

当返回的状态码大于 400 时认为是接口报错,应通过如下响应体进行错误处理:

{
"errorCode": "example error", // 用于推断错误类型
"message": "example message", // 提示信息(英文)
"target": "example" // 出错的字段/对象名
}
2.1.1.1 错误码说明​
错误码HTTP状态码描述
InvalidParameter400无效参数
InvalidRequestBody400无效请求体
ResourceNotFound404资源未找到
InternalServerError500内部服务器错误
InvalidOperation400无效操作
NotAuthenticatedError401未认证错误
AuthorizationError403授权错误
2.1.1.2 渠道关联游戏​

渠道关联流程

渠道方关联游戏时需要开发者提供 associateKey 进行关联游戏,可以参考渠道关联

  1. 渠道方根据 associateKey 获取游戏信息
GET /api/channel/v1/game_app/associate/:associateKey/info
参数类型值类型必填说明
associateKeypathstring是游戏关联时生成的临时密钥

响应体说明

{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
  1. 渠道关联游戏成功后通知关联
POST /api/channel/v1/game_app/associate/:associateKey/success

入参说明

参数类型值类型必填说明
associateKeypathstring是游戏关联时生成的临时密钥

请求体说明

{
"gameId": "string",
"channelGameId": "string",
}

响应体说明

{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
2.1.1.3 游戏管理​

当开发者在 Minihost 上选择将游戏提交到对应平台方之后,平台方可以使用下列 API 在自己的平台上提供相应的游戏管理能力。

后台侧:

  1. 获取游戏列表 获取所有与平台方有关的游戏的列表。
  2. 获取游戏信息
  3. 编辑游戏信息 游戏上架平台后开发者无法再在 Minihost 界面更新游戏信息,平台方应当在合适的时机(如:游戏内容审核通过后)调用此接口,以确保 Minihost 宿主在实际运行时能显示正确的游戏信息和进行支付等需要平台方参与的调用。
  4. 下架游戏 当平台方与开发者解约,需要解除游戏关联时可以调用此接口。

开发者侧:

  1. 上线游戏 当游戏开发者在平台进行游戏包上线操作时,平台方需要调用此 API 以告知 Minihost 游戏线上版本需要使用的游戏包 ID。
2.1.1.3.1 获取游戏列表​
GET /api/channel/v1/game_app_list

入参说明

参数类型值类型必填说明
pagequeryint否页码,起始和默认值为 1
pageSizequeryint否一页的大小,默认值为 100
orderByquerystring否排序,可选择 createdTime 或 updatedTime 进行排序
orderquerystring否顺序,asc 或 desc

响应体说明

{
"items": [
{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"latestBundleId": "string", // 上线的游戏包
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
],
"total": 0
}
2.1.1.3.2 获取游戏信息​
GET /api/channel/v1/game_app/:id/info

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏对应的 ID

响应体说明

{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"latestBundleId": "string", // 上线的游戏包
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
2.1.1.3.3 编辑游戏信息​
PUT /api/channel/v1/game_app/:id/info

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏对应的 ID

请求体说明

{
"name": "游戏名称",
"iconUrl": "https://example.cdn.com/example.png", // 公网可访问的图标地址
"briefIntro": "游戏描述",
}

提供需要更新的字段以进行更新(如:不打算更新 name 字段,那么 JSON 中不应存在该字段)。

响应体说明

{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"latestBundleId": "string", // 上线的游戏包
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
2.1.1.3.4 上线游戏​
POST /api/channel/v1/game_app/:id/publish

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏对应的 ID

请求体说明

{
"bundleId": "example_id"
}

响应体说明

{
"id": "string", // gameId
"launchKey": "string", // launchKey
"orgId": "string", // 上传游戏所属的组织
"name": "string", // 游戏名字
"briefIntro": "string", // 游戏描述
"iconUrl": "string", // 游戏图标
"latestBundleId": "string", // 上线的游戏包
"tags": [ // 标签
"string"
],
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
2.1.1.3.5 下架游戏​
DELETE /api/channel/v1/game_app/:id

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏对应的 ID

响应体说明

下架成功后会返回 "OK"

2.1.1.4 游戏包管理​

渠道审核流程

当开发者在 Minihost 选择将游戏包提交给平台方后(需要先将游戏关联到平台 Channel),平台方可以使用下列 API 在自己的平台上提供相应的游戏包管理能力。

后台侧:

  1. 获取游戏包列表 可以使用此 API 查看所有提交的游戏包,可以通过筛选审查状态实现审核列表。
  2. 获取游戏包临时会话 提供审核试玩游戏的功能,将临时会话的访问链接制成二维码可以使用平台方的 APP 扫码进行审核试玩。
  3. 更新游戏包审核信息 记录游戏包最终的审核结果,支持撤销。

开发者侧:

  1. 获取游戏包列表 此 API 携带 gameId 参数,可以开发者在平台查看对应游戏的游戏包审核状态,并使用 上线游戏 上线已经通过审核的版本。
2.1.1.4.1 获取游戏包列表​
GET /api/channel/v1/game_bundle_list

入参说明

参数类型值类型必填说明
pagequeryint否页码,起始和默认值为 1
pageSizequeryint否一页的大小,默认值为 100
gameIdquerystring否游戏包所属游戏的 ID
auditStatusquerystring否游戏包审核状态
publishStatusquerystring否游戏包上线状态
orderByquerystring否排序,可选择 createdTime 或 updatedTime 进行排序
orderquerystring否顺序, asc 或 desc

游戏包审核状态说明

状态说明
pending游戏包上传成功后的初始状态
reviewing游戏包开始审核后的状态
accepted游戏包审核通过后的状态
denied游戏包审核未通过后的状态
cancelled游戏包取消审核后的状态

游戏包上线状态

状态说明
online游戏包上线后的状态
offline游戏包历史上线版本

响应体说明

{
"items": [
{
"id": "string", // bundleId
"gameId": "string", // gameId
"auditStatus": "pending", // 游戏包审核状态
"publishStatus": "online", // 游戏包上线状态
"description": "string", // 描述信息
"version": "string", // 版本号
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
],
"total": 0
}
2.1.1.4.2 获取游戏包临时会话​
POST /api/channel/v1/game_bundle/:id/temp_session

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏包对应的 ID

响应体说明

{
"url": "https://minihost.tuanjie.cn/api/game_app/example_id/temp_session/example_session_id/start", // 临时会话的访问 URL,制成二维码后可以使用宿主扫码
"expiresIn": 180 // 临时会话几秒以后过期
}
2.1.1.4.3 更新游戏包审核信息​
PUT /api/channel/v1/game_bundle/:id/audit_info

入参说明

参数类型值类型必填说明
idpathstring是要访问的游戏包对应的 ID

请求体说明

{
"auditStatus": "accepted" // 应填写 reviewing/accepted/denied/cancelled 中的其中一个
}

响应体说明

{
"id": "string", // bundleId
"gameId": "string", // gameId
"auditStatus": "pending", // 游戏包审核状态
"publishStatus": "online", // 游戏包上线状态
"description": "string", // 描述信息
"version": "string", // 版本号
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}
2.1.1.5 游戏包上传推送​

在开发者将游戏关联到渠道方后,当游戏包上传成功后会自动推送给渠道方, 渠道方需要提供接收推送的接口。

请求体说明

{
"id": "string", // bundleId
"gameId": "string", // gameId
"auditStatus": "pending", // 游戏包审核状态
"publishStatus": "online", // 游戏包上线状态
"description": "string", // 描述信息
"version": "string", // 版本号
"createdTime": "createdTime",
"updatedTime": "updatedTime",
}

响应体说明

{
"code": 200,
"message": "success"
}
2.1.1.6 用户身份验证接口​

渠道方需要提供用户身份验证接口,以便宿主平台能够验证用户身份。具体实现请参考 服务端集成文档 中的 jscode2session 接口规范。

渠道方需提供以下接口供宿主平台调用:

GET /jscode2session?js_code={code} HTTP/1.1

详细参数说明和响应格式请参考 jscode2session 规范。

2.1.1.7 支付通知接口​

宿主平台提供支付通知接口,渠道方需要调用这些接口以完成支付流程。具体接口规范请参考 服务端集成文档 中的支付通知 API 规范。

宿主平台提供以下支付通知接口供渠道方调用:

POST /game-api/v2/payment/callback
Host: minihost.tuanjie.cn
Authorization: Bearer {service_token}

以及退款通知接口:

POST /game-api/v2/payment/callback/refund
Host: minihost.tuanjie.cn
Authorization: Bearer {service_token}

详细的参数说明、签名规则和响应格式请参考 支付通知 API 和 退款通知 API 规范。

2.2 服务端令牌集成规范​

2.2.1 使用令牌获取小游戏列表​

平台方可以使用服务端令牌来获取宿主应用的小游戏列表。

请求示例:

GET /api/game/list?appId={appId} HTTP/1.1
Host: minihost.tuanjie.cn
Authorization: Bearer {service_token}

请求参数说明:

参数说明
appId宿主应用的 ID
Authorization服务端令牌,格式为 Bearer {service_token}

响应示例:

HTTP/1.1 200 OK
Content-Type: application/json

[
{
"id": "67b*********************",
"appId": "67b*********************",
"name": "游戏名称",
"briefIntro": "简介",
"gameType": "weixinminigame",
"iconUrl": "https://minihost.cdn.tuanjie.cn/game_app/67b6eb506ffcda2559ecd19d/app_icon/********.png",
"launchKey": "67b*********************",
}
]

响应字段说明:

字段说明
id游戏 ID
appId宿主应用 ID
name游戏名称
briefIntro游戏简介
gameType游戏类型
iconUrl游戏图标 URL
launchKey这里返回值是游戏 ID

关于launchKey的用法参考游戏启动参数

2.2.2 服务端 API 接入规范​

备注

此接入规范是平台方 API 的实现规范,如果您是游戏侧开发者,请参考 小游戏 API 进行接入。

2.2.2.1 ping​

用于测试宿主后台与平台方的网络连通性,连通性验证成功之后,才可以将 URL 配置到宿主后台中。

请求示例:

GET /ping HTTP/1.1

响应示例:

HTTP/1.1 200 OK
Content-Type: text/plain

pong
2.2.2.2 jscode2session​

提供平台方的登录能力,宿主后台会将用户的登录凭证(code)传递给平台方,平台方需要根据该凭证返回用户的登录信息。

宿主后台会结合请求的上下文,将平台方返回的 uid 映射为游戏侧可用的 openid 和 unionid,同时转发 session_key 给游戏侧做为登录凭证。

请求示例:

GET /jscode2session?js_code={code} HTTP/1.1
Authorization: Bearer {service_token}

请求参数说明:

参数说明
js_code平台方登录凭证
Authorization服务端令牌,格式为 Bearer {service_token}

响应示例:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uid": "123456"
"session_key": "abcdefg",
"errcode": 0,
"errmsg": "ok"
}

响应字段说明:

字段说明
uid平台方返回的用户唯一标识
session_key平台方返回的 session_key
errcode错误码,0 表示成功
errmsg错误信息

2.2.3 支付签名验证​

平台采用SHA1方式对参数进行加密验签

2.2.3.1 签名规则​
  1. 参数大小写敏感(区分大小写)
  2. 多参数拼接采用&符号作为分隔符
  3. 参数的value为null或空字符串("")时不参与签名
  4. 签名参数(sign)本身不参与签名
  5. 参数签名顺序按照参数名的ASCII码从小到大排序
  6. 所有业务参数按顺序拼接完成后,再在末尾拼接secret参数
  7. 签名值:将拼接完成的字符串进行SHA1加密,截取后32位字符,并转换为大写
待签名参数示例​
{
"amount": 1,
"appId": "692ee200dc0f40766a42504f",
"count": 1,
"couponDeductAmount": 0,
"cpOrderId": "27308454202512031028289635",
"currency": "CNY",
"extra": "{\"orderId\":\"27308454202512031028289635\",\"userId\":\"693003df1cf21a89eacc8366\"}",
"nonce": "20251203183012fd2948",
"productCode": "1001",
"productName": "Product For Demo",
"productPrice": 1,
"tradeNo": "20251203182830033010000117646468"
}
签名字符串示例​
amount=1&appId=692ee200dc0f40766a42504f&count=1&couponDeductAmount=0&cpOrderId=27308454202512031028289635&currency=CNY&extra={"orderId":"27308454202512031028289635","userId":"693003df1cf21a89eacc8366"}&nonce=20251203183012fd2948&productCode=1001&productName=Product For Demo&productPrice=1&tradeNo=20251203182830033010000117646468&secret=Qaf2xQ56XnLUw5bgelfvPAbQnn8
最终签名值​
69D48E7D9AF3EB7680570894B6D07845
2.2.3.2 支付通知 API​

平台支付流程

POST /game-api/v2/payment/callback
Host: minihost.tuanjie.cn
Authorization: Bearer {service_token}

请求参数说明:

参数说明
Authorization服务端令牌,格式为 Bearer {service_token}
请求体说明​
{
"appId": "appId", // 游戏ID
"tradeNo": "tradeNo", // 交易编号
"cpOrderId": "cpOrderId", // 小游戏订单号
"amount": 1, // 支付金额
"count": 1, // 商品数量
"currency": "currency", // 货币类型
"productCode": "productCode", // 商品编码
"productName": "productName", // 商品名称
"productPrice": 1, // 商品价格
"couponDeductAmount": 0, // 优惠券抵扣金额
"extra": "extra", // 附加信息
"nonce": "nonce", // 随机字符串
"sign": "sign" // 签名信息 参考上面签名规则
}
响应体说明​
{
"code": 200, //响应状态码
"message": "message" //状态码描述信息
}

code响应码说明

状态码描述
200业务处理成功,发货成功
22100数据签名不正确
22101接口参数验证不通过
22102订单失败(例如因为无库存、商品下架等原因,明确指出该笔订单无法执行)
22103未知业务错误
2.2.3.3 退款通知 API​
POST /game-api/v2/payment/callback/refund
Host: minihost.tuanjie.cn
Authorization: Bearer {service_token}

请求参数说明:

参数说明
Authorization服务端令牌,格式为 Bearer {service_token}

请求体说明

{
"appId": "appId", // 游戏ID
"tradeNo": "tradeNo", // 交易编号
"cpOrderId": "cpOrderId", // 小游戏订单号
"refundNo": "refundNo", // 退款编号
"refundAmount": 1, // 退款金额
"nonce": "nonce", // 随机字符串
"sign": "sign" // 签名信息 参考上面签名规则
}

响应体说明

{
"code": 200, //响应状态码
"message": "message" //状态码描述信息
}

code响应码说明

状态码描述
200业务处理成功,退款处理成功
22100数据签名不正确
22101接口参数验证不通过
22103未知业务错误

2.3 登录API​

2.3.1 登录全流程​

在上述diagram中,需要平台方集成的API为第10步中的code2session。

2.3.2 平台方Code2Session​

提供平台方的登录能力,宿主后台会将用户的登录凭证(code)传递给平台方,平台方需要根据该凭证返回用户的登录信息。

宿主后台会结合请求的上下文,将平台方返回的 uid 映射为游戏侧可用的 openid 和 unionid,同时转发 session_key 给游戏侧做为登录凭证。

请求示例

GET /jscode2session?js_code={code} HTTP/1.1
Authorization: Bearer {service_token}

请求参数说明:

参数说明
js_code平台方登录凭证
Authorization服务端令牌,格式为 Bearer {service_token}

响应示例:

HTTP/1.1 200 OK
Content-Type: application/json

{
"uid": "123456"
"session_key": "abcdefg",
"errcode": 0,
"errmsg": "ok"
}

响应字段说明:

FieldDescription
uidUnique user identifier returned by the platform
session_keysession_key returned by the platform
errcodeError code, 0 indicates success
errmsgError Message

2.4 支付API​

2.4.1 支付全流程​

2.4.1.1 小游戏支付​

2.4.1.2 游戏服务端主动查询订单​

2.4.2 平台服务端回调接口​

支付成功后,平台服务端向宿主服务端发送支付成功回调。宿主服务端在验签后将回调发送给游戏服务端。 与上方2.4.1.1的第六步一致

2.4.2.1 回调地址​

POST https://minihost.tuanjie.cn/game-api/v1/payment/callback

2.4.2.2 请求参数​
参数名类型说明
timestampstring时间戳
noncestring随机数
msgstringJson string类型的支付结果信息,参见PaymentInfo对象
signaturestring签名,签名算法参见2.1.4签名部分
2.4.2.3 PaymentInfo​
参数名类型说明
appidstring小游戏appid
cp_ordernostring开发者自定义订单号,tj.requestPayment方法中的customId参数
cp_extrastring开发者传的额外参数,tj.requestPayment方法中的extra参数
order_no_channelstring小游戏后台交易单号
amount_centint64订单金额,单位人民币分
amount_coinint64购买游戏币数量
currencystring支付币种,CNY 人民币
product_codestring商品编号,tj.requestPayment方法中的options.PRODUCT_CODE参数
2.4.2.4 签名​

根据 token,timestamp,nonce,msg ,使用 SHA1 算法生成 signature,与平台方的服务端返回的 signature 对比。

前置条件:在关联游戏时,平台方需要将token传递给宿主,用于签名校验

golang示例代码:

sortedString := make([]string, 4)
sortedString = append(sortedString, token)
sortedString = append(sortedString, timestamp)
sortedString = append(sortedString, nonce)
sortedString = append(sortedString, string(msg))
sort.Strings(sortedString)h := sha1.New()
h.Write([]byte(strings.Join(sortedString, "")))_signature := h.Sum(nil)
2.4.2.5 响应​

宿主服务器返回200状态码,作为成功响应。若返回 http 状态码非200,表示通知失败,需要进行重试。

2.4.3 游戏服务端主动查询订单​

服务端支付回调可能由于网络异常等原因导致无法 100%触达,开发者可以通过该接口主动回查订单状态,防止超发漏发。开发者向宿主服务端发送查询订单请求,宿主封装后向平台方服务端发送查询订单请求。

2.4.3.1 接口地址​

由平台方提供

2.4.3.2 请求参数​
参数名类型说明
tokenstring双方约定服务端token
ordernostringcp 自定义订单号,在下单的时候传入,tj.requestPayment方法中的customId参数
2.4.3.3 响应​
参数名类型说明
statusstring支付状态。success 表示支付成功且发币到账,unsuccess 表示支付失败
2.4.3.4 鉴权​

请求需包含双方约定好的服务器令牌,放在Auhthorization header里,格式形如

Bearer {service_token}