跳到主要内容

基本功能

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

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

平台会如何请求​

请求体概述​

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

请求示例​

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

以下是请求 notify_type 为 QUERY_ROLE 的一个示例，不同的 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 '{
      "notify_type": "QUERY_ROLE",
      "timestamp": 1624529209,
      "version": "v2",
      "sign_type": "MD5",
      "sign": "8dca510ff04a20b40f2beac436db7083",
      "body": {
        "user_id": 700098915,
        "game_id": "119121100",
        "server_id": ""
      }
    }'
提示

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

请求参数说明​

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

游戏方应如何响应​

响应体概述​

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

响应示例​

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "11232131",
      "name": "角色名称",
      "level": 0,
      "created_at": 1642509786
    }
  ],
  "trace_id": "1555475844061728768"
}

响应参数说明​

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

消息类型 notify_type​

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

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

消息类型说明备注
CREATE_CHARGE_ORDER创建直充订单
PAY_CALLBACK支付成功回调（在用户支付成功时使用）
CHARGE_PAY_CALLBACK直充支付成功回调（在用户直充支付成功时使用）
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": "QUERY_ROLE",
  "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"