跳到主要内容

基本功能

平台的基本功能包括登录、支付、角色管理，不同游戏需要接入的功能可能不同。

这些功能的后端对接有个共同点：平台都会调用游戏方的同一个回调接口。
也就是说，游戏方需要且只需要准备一个回调接口 callback_url 被平台调用，即可实现后端对接。

平台会如何请求​

请求体概述​

  • HTTP 请求方法：POST
  • HTTP 请求标头：Content-Type: application/json

请求示例​

请求体是一个 JSON，包含字段 notify_type 表示消息类型。游戏方后端通过消息类型区分平台在请求什么操作。

以下是请求 notify_type 为 AUTH_KEY 的一个示例，不同的 notify_type 会有不同的 body 数据结构，但其他字段的数据格式是一致的。

curl --location --request POST 'http://api-login-wan-ssl.xunlei.com/v1/user/game/tlogin/getLoginToken' \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "body": {
        "game_id": "102011619",
        "server_id": "",
        "user_id": "821407262"
    },
    "notify_type": "AUTH_KEY",
    "sign": "8dca510ff04a20b40f2beac436db7083",
    "sign_type": "MD5",
    "timestamp": 1647918463
    }'
提示

示例请求的接口 http://api-login-wan-ssl.xunlei.com/v1/user/game/tlogin/getLoginToken 仅作演示，实际使用需要替换为游戏方的回调接口。

请求参数说明​

参数类型示例说明
notify_typestringAUTH_KEY回调消息类型。
timestampint1733194509Unix 时间戳（单位：秒）。
versionstringv2回调消息版本，如果对接时没看到此参数，默认为 v2 版本。如需变更版本，请联系迅雷同学。
sign_typestringMD5消息签名规则，默认为 MD5。
signstring8dca510ff04a20b40f2beac436db7083签名。
bodyobject消息结构，与 notify_type 相关联。

游戏方应如何响应​

响应体概述​

  • HTTP 响应标头：Content-Type: application/json
  • HTTP 响应体 JSON 各字段的数据类型必须与文档保持一致。

响应示例​

{
  "code": 0,
  "message": "成功",
  "data": {
    "auth_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjo4MjE0MDcyNjIsImdhbWVfaWQiOjEwMjAxMTYxOSwic2VydmVyX2lkIjowLCJleHAiOjE2NTk2OTExMTUyMjcwODc3NzMsImlhdCI6MTY1OTY4OTMxNSwiaXNzIjoieGwtZ2FtZSJ9.FMilAq3hcRIgQ1M27790FTlU-B0WCULPCsDkjjwhrU0",
    "ext": "821407262_102011619_0"
  },
  "trace_id": "1555475844061728768"
}

响应参数说明​

参数类型示例说明
codeint0响应码，0：成功，非 0：失败。
messagestringsuccess响应说明，游戏方可自定义 message 内容，但应保持语义明确。
dataobject响应数据，不同的回调消息类型需要的响应数据不一样。空数据可为 {} 或 null。

消息类型 notify_type​

游戏类型不同，平台调用回调接口时，使用的消息类型 notify_type 也会不同。

总的来说，后端在接下来的章节对接不同功能时，可能会遇到以下的消息类型。

消息类型说明
VERIFY_PRICE获取内购商品价格（在平台需要获取价格显示时使用）
CREATE_ORDER创建订单
CREATE_CHARGE_ORDER创建直充订单
PAY_CALLBACK支付成功回调（在用户支付成功时使用）
CHARGE_PAY_CALLBACK直充支付成功回调（在用户直充支付成功时使用）
AUTH_KEY获取 auth_key（在用户启动游戏时使用）
QUERY_ROLE获取游戏角色（当平台需要获取用户角色信息时使用）
QUERY_ALL_ROLE获取游戏内所有角色，此消息与活动运营相关，当需要接入时平台方会与游戏方沟通
USER_BLOCK游戏角色封禁
CHAT_BLOCK游戏角色禁言

签名规则​

1. 签名规则​

  • 仅 body 内的字段参与签名。
  • 值为空字符串的字段不参与签名。
  • 将参与签名的参数按属性名升序排序，然后拼接为 k1=v1&k2=v2 格式（类似于浏览器的 URLSearchParams 但不需要对字符进行转义 ）
  • 将游戏的签名密钥 sign_key 拼接到上面 k1=v1&k2=v2 字符串的末尾，得到 k1=v1&k2=v2sign_key。
  • 对上面得到的字符串 k1=v1&k2=v2sign_key 进行 MD5 计算，得到 32 位小写字符串，即 MD5(k1=v1&k2=v2sign_key)。

2. 签名计算示例​

假设签名密钥 sign_key 为 test_key_e3654407c996bd0f8a45a14，回调消息如下：

{
  "notify_type": "AUTH_KEY",
  "timestamp": 1624529209,
  "version": "v2",
  "sign_type": "MD5",
  "sign": "8dca510ff04a20b40f2beac436db7083",
  "body": {
    "user_id": 700098915,
    "game_id": "119121100",
    "server_id": ""
  }
}

将参与签名的参数按属性名升序排序，然后拼接为 k1=v1&k2=v2 格式：

const signString = "game_id=119121100&user_id=700098915";

将签名密钥 sign_key 拼接字符串的末尾：

const signStringWithKey =
  "game_id=119121100&user_id=700098915test_key_e3654407c996bd0f8a45a14";

MD5 计算字符串，得到签名（32 位小写字符串）：

const sign = MD5(signStringWithKey) = "8dca510ff04a20b40f2beac436db7083"