接入开始
接入开始

接入前，请仔细阅读： 【 接入指南】、【 调用方式】， 包括：SDK 参数获取、* 接口协议说明*、业务流程 等。

# 1 登录鉴权

1.1 接口说明

客户端SDK登录成功后，建议cp通过服务端接口验证 AccessToken。

1.2 请求地址

以下都是正式环境，无测试环境，游戏开发者在接入测试时也使用SDK正式环境地址； 请开发者根据自己的服务器所在地区选择合适的SDK服务地址：

  • 母包请求：

    • https://usdk.yingxiong.com/hu/v1/login/checkUserInfo.lg

  • 国内请求： (官方,华为,小米,oppo...)

    • https://usdk.yingxiong.com/hu/v1/login/checkUserInfo.lg

  • 海外请求：

    • https://hgsdkcdn.herogame.com/hgsrv/v1/login/checkUserInfo.lg

提示

注意：海外新增「弱uSDK化」的模式，在该模式下依然保留 usdk 的接入便利性、但缩短了服务器链路：玩家和cp服务端不用访问 usdk 服务器，在开启了弱 usdk 化并且是海外渠道包的情况，cp 需要到海外服务器做登录校验。具体细节请联系平台运营了解。

1.3 请求参数

字段 必填 类型 字段说明
pcode 必须 String ProductId，uSDK的产品ID
data 必须 String 加密后的业务数据，加密前的参数值参考1.4.1 参数生成规则
timestamp 必须 String unix 时间戳，格式如：1626320008
sign 必须 String 签名，参数生成规则

1.3.1 data参数

字段 必填 类型 字段说明
cUid 必须 String 渠道用户ID
cName 可选 String 渠道用户名称
accessToken 必须 String uSDK客户端登录返回的Token

1.4 请求示例

curl https://usdk.yingxiong.com/hu/v1/login/checkUserInfo.lg -d \
  'data=eiJjVWlkIjNiMTAwMmtlIiwiY05hbWUiOyIiLCJhY2olc3NUb2dtbiI6ImV5SmphR0Z1Ym1Wc1gybGtJam9pSWl3aVpYaDBaVzVrSWpvaU1qRXdObnd5TlRWOE1DSXNJbTl6Wkd0ZmRYTmxjbDlwWkNJNklqQXdOakF3TVRWZk1UQXdNbWR0SWl3aWFYQWlPaUl4TWpjdU1DNHdMakVpTENKMGFXMWxJam94TmpJMk1EVTNPVEUyTENKemFXZHVJam9pTUdSbE56RXhOREZsTm1Oak16YzFOMkV6TldWak9EaGlOV1U0WWpabU5HUWlmUT09In0%3D&pcode=17188&sign=55f35601801fa4bb5a1644076076b15e&timestamp=1626057916'
1
2

1.5 响应参数

字段 名称 重要性 类型 说明
code 状态 必须 int 业务状态，0为成功，不为0为失败，具体错误可以查看msg
msg 描述 可选 String 错误信息
cUid 渠道的用户id 必须 String cUid+channelId，可作为唯一ID
cName 渠道的username 必须 String 转发第三方渠道用户名，若渠道不提供用户名，则返回为空字符串
channel 渠道码 必须 String hero、baidu、ysdk
channelId 渠道ID 必须 int 如56，18
swLogin 切登录 可选 int 1: 表示是切登录过来的，默认没有该字段
curChannelUser 切登录 可选 int 当前登录的渠道用户信息，默认没有该字段
uuid 通服ID 可选 String 只针对官方渠道(安卓官方和iOS官方),可直接用该字段做通服判断，安卓和iOS返回的uuid相同
heroSdkUserId 英雄渠道用户ID 可选 String 英雄国内官方渠道用户id
age 年龄 可选 int 年龄
ext 用户额外字段 可选 json 当前登录的渠道用户额外信息，默认没有该字段

提示

由于渠道特性不一样，如果遇到返回的字段与文档不相符，则为当前渠道的特殊字段，如果想确定字段使用规则，请联系SDK研发与运营协助使用

  • 关于 唯一用户ID:

    • cUid 在 渠道内是唯一的，但在不同渠道之间是可能重复；

    • 请使用 channelId 与 cUid 的结合，来确定玩家的唯一账号;

      • 也可以使用 channel 与 cUid 组合

    • 官方渠道需要特殊处理，即「安卓、iOS、PC、鸿蒙的cUid是互通的」；

      • 国内 与 全球 之间不互通；
      channelId channel 渠道名称
      56 ihero 国内-iOS正版
      18 hero 国内-安卓
      237 heropc 国内-PC
      270 herohm 国内-鸿蒙
      channelId channel 渠道名称
      160 heroglobal 全球SDK-谷歌
      171 iheroglobal 全球SDK-苹果
      240 heroglobalpc 全球SDK-PC

名词解释

  • 切登录

    • 非官方渠道无法登录时，可切换到英雄官方渠道登录

  • ext

    • 类型为json

    • ext为额外的字段，根据渠道返回的内容不同；以使用官方国内渠道登录为例：

      | 字段 | 类型 | 说明 | |----|-----|----------------------| | heroLoginType | int | 国内官方渠道登录方式 | | sdkUserId | string | 国内官方渠道用户id | | reg | string | 仅注册返回 0-非首次注册,1-首次注册 | | regTime | string | 注册时间 | | userType | int | 用户类型 | | age | int | 年龄 |

      • 其中，heroLoginType 定义如下:

        • 0: 账密登录
        • 1: 手机
        • 2: 其他三方
        • 3: 游客
        • 5: qq
        • 6: 微信
        • 7: 微博
        • 9: ios
        • 10: taptap
        • 11: kuaibao

      • 其中，userType 定义如下:

        • 0: 游客
        • 1: FACEBOOK
        • 2: GOOGLE
        • 3: GAME_CENTER
        • 5: TWITTER
        • 7: APPLE
        • 8: LINE
        • 12: GAMEWITH
        • 16: EMAIL

1.6 响应示例

{
 "code": 0,
 // code为0代表成功
 "msg": "",
 // code不为0时，具体错误可查看msg的内容
 "timestamp": 1626060519882,
 "channel": "anzhi",
 "channelId": 29,
 "cUid": "20180112002346jUru7agnHW",
 "swLogin": 1,
 "age": 20,
 "heroSdkUserId": "U168000000A",
 "uuid": "hero_138693888",
 "ext": {
   "heroLoginType": 1,
   "reg": "1",
   "reg_time": "2023-09-13 16:15:22",
   "age": 31,
   "sdkUserId": "U40055700A"
 },
 "curChannelUser": {
   "cUid": "97422201",
   "cName": "amengyan",
   "channel": "hero",
   "channelId": 18
 }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

1.7 返回码

code 说明
0 成功
其它 其它均为失败 具体错误，参考响应里的msg

# 2 支付回调

2.1 业务说明

当玩家支付成功后，SDK服务器会将支付结果通知给游戏（CP）提供的回调地址。

  1. 玩家支付成功: 以 uSDK服务端收到、并验证支付结果通过 为准；
  2. 关于回调地址:
    • 请务必在【uSDK管理后台 (opens new window)-游戏管理-游戏基础信息】中填写 Callback_Url，或联系运营协助设置；客户端和中台都能配置回调地址，如果都配置，以中台配置的为准。
    • 请勿泄露真实回调地址；
  3. 回调请求方法: HTTP、POST、application/x-www-form-urlencoded
  4. 回调解密计算:
  5. 回调的响应值:
    • SUCCESS
      • 注意，只有这7个字符，不要有空白或其它字符；
      • 表示支付结果正常受理，流程结束。
    • ABORT
      • 表示 支付结果受理但有异常，流程结束，SDK 服务端不再重试通知该订单的结果；
      • 也可以返回 ABORT:描述信息 来补充少量说明信息；
    • 其它情况均表示 支付结果受理异常，流程未结束，uSDK 会定时重试通知回调地址（见下文 回调重试策略）；

2.2 回调参数

字段 名称 重要性 类型 说明
data String 必须 密文，通知主要内容，需要解密。已做URLEncode编码，格式见下文
sign String 必须 签名

  • data解密后的基础字段说明:

    参数 类型 重要性 来源 描述
    amount Double 必须 SDK 成交金额，单位元（CNY）， channel为全球渠道(iglobal和iheroglobal)时，单位为实际支付的币种，取currency字段
    gameOrder Sring 必须 游戏 游戏订单号
    orderNo String 必须 SDK 整合sdk订单号
    status int 必须 SDK 交易状态，0表示成功
    selfDefine String 可选 游戏 透传参数
    channelUid String 必须 SDK 渠道的用户id
    payTime String 必须 SDK 交易时间yyyy-MM-dd HH:mm:ss
    channel String 必须 SDK 渠道类型
    channelId int 必须 SDK 渠道ID
    goodsId String 必须 SDK 渠道的档位ID
    goodsName String 必须 SDK 商品名称
    serverId String 必须 SDK 区服ID
    roleId String 必须 SDK 角色ID
    isTest int 可选 SDK 是否是测试，1是测试，只有值等于1的时候，才会有 isTest 字段

  • data解密后的额外字段说明，有代金券、iOS订阅、其他需求可使用

    参数 类型 重要性 来源 描述
    yx_is_in_intro_offer_period String 可选 SDK 订阅：是否处于介绍价格期仅英雄国内iOS渠道下有该字段
    yx_is_trial_period String 可选 SDK 订阅: 是否处于免费试用期 仅英雄国内iOS渠道下有该字段
    iap_sub_expire String 可选 SDK 订阅：过期时间 仅英雄国内iOS渠道、华为渠道下有该字段 示例 2021-07-18 18:39:58
    iap_sub String 可选 SDK 订阅：是否是订阅仅英雄国内渠道iOS、华为渠道下有该字段
    paytype String 可选 SDK 支付方式类型 仅英雄国内渠道、华为渠道下有该字段
    yx_sub_type String 可选 SDK 支付方式子类型 仅英雄国内渠道下有该字段
    dealAmount String 可选 SDK 使用了英雄SDK代金券实际支付的金额 仅英雄国内渠道、华为渠道下有该字段
    qkChannelId int 可选 SDK quicksdk的id
    quickChannelId int 可选 SDK quicksdk的id 等于 qkChannelId 值一样
    sandbox String 可选 SDK 是否是沙盒 等于 仅英雄(国内/全球)渠道、华为渠道下有该字段
    iapSub String 可选 SDK 订阅：是否是订阅仅英雄全球iOS渠道下有该字段
    iapSubExpire String 可选 SDK 订阅：订阅过期时间 仅英雄全球iOS渠道下有该字段
    currency String 可选 SDK 币种 仅英雄全球渠道下有该字段
    payType String 可选 SDK 支付方式类型 仅英雄全球渠道下有该字段

2.3 回调数据示例

示例

data=eyJhbW91bnQiOjEuMCwib3JkZXJObyI6IkhVQTEwMTg2MTY0NDEyIiwicGF5VGltZSI6IjIwMjEtMDctMDUgMTQ6NDI6MzMiLCJnb29kc0lkIjoiMSIsImNoYW5uZWxVaWQiOiIxMTg1OTEzMzk3OTAxMTM5Iiwic2VsZkRlZmluZSI6IumAj%2BS8oOWPguaVsCIsImNoYW5uZWwiOiJodWF3ZWkiLCJxdWlja0NoYW5uZWxJZCI6MjQsInFrQ2hhbm5lbElkIjoyNCwiZ2FtZU9yZGVyIjoiY3BPcmRlcklkXzE2MjU0Njc2MTIxMzAiLCJnb29kc05hbWUiOiLllYblk4FJROiHquWumuS5iea1i%2BivleWVhuWTgS0wMSIsImNoYW5uZWxJZCI6MTEsInN0YXR1cyI6MH0%3D&sign=1741120cdda4b3a50fe59224595da88f
1

data解密后的示例

{
  "amount": 1.0,
  "orderNo": "HUA10186164412",
  "payTime": "2021-07-05 14:42:33",
  "goodsId": "1",
  "channelUid": "1185913397901139",
  "selfDefine": "透传参数",
  "channel": "huawei",
  "quickChannelId": 24,
  "qkChannelId": 24,
  "gameOrder": "cpOrderId_1625467612130",
  "goodsName": "商品ID自定义测试商品-01",
  "isTest": 1,
  // 是否是测试，1是测试，只有值等于1的时候，才会有 isTest 字段
  "channelId": 11,
  "status": 0
  // 0代表成功，不为0代表失败
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

2.4 返回响应

  • SUCCESS
    • 注意，只有这7个字符，不要有空白或其它字符；
    • 纯文本、不是 JSON；
    • 表示支付结果正常受理，流程结束。
  • ABORT
    • 表示 支付结果受理但有异常，流程结束，SDK 服务端不再重试通知该订单的结果；
    • 也可以返回 ABORT:描述信息 来补充少量说明信息；
  • 其它情况均表示 支付结果受理异常，流程未结束，uSDK 会定时重试通知回调地址（见下文 回调重试策略）；
  • status
    • 响应为json对象,包含字段status, 0表示成功

2.5 回调重试策略

回调通知会在12小时内，每间隔10分钟通知一次，直至收到SUCCESS应答后停止。

苹果、谷歌、华为由于是小票机制校验，可能会存在小票延迟上报的情况. sdk会在用户打开游戏的时候检测是否有未核销小票，如果存在未核销小票，会自动进行重试.

2.6 发货条件（非常重要）

支付回调的成功响应只能确保玩家完成了支付行为，CP 需要独立校验该订单的合法性（cp 订单号与 amount 、goodId，userId 等是否匹配），确认无误后才可以发货，否则会有潜在的刷单风险。

需要 CP 独立校验的字段包括：

1、渠道id是否一致
2、用户信息是否一致
3、自定义信息是否正确
4、金额档位是否正确
5、订单号是否一致
6、其它 `根据实际游戏业务需要验证的字段进行判断`
1
2
3
4
5
6

# 3 支付退款

3.1 退款接口说明

  1. 在用户退款后，SDK服务器会将支付结果通知给游戏（CP）提供的回调地址。

  2. 退款支持渠道： 目前只支持 英雄互娱-iOS正版 (渠道id：56)

  3. 退款回调地址: 开始前请务必在【USDK管理后台 (opens new window) -游戏管理-游戏基础信息】中填写退款回调地址

  4. 请求方法: POST

3.2 退款回调参数

字段 名称 重要性 类型 说明
data String 必须 通知主要内容，需要解密。格式见下文
sign String 必须 签名

data各字段说明:

参数 类型 重要性 来源 描述
amount Double 必须 SDK 成交金额，单位元（CNY）， channel为全球渠道(iglobal和iheroglobal)时，单位为实际支付的币种，取currency字段
gameOrder Sring 必须 游戏 游戏订单号
orderNo String 必须 SDK 整合sdk订单号
status int 必须 SDK 交易状态，0表示成功
selfDefine String 可选 游戏 透传参数
channelUid String 必须 SDK 渠道的用户id
payTime String 必须 SDK 交易时间yyyy-MM-dd HH:mm:ss
channel String 必须 SDK 渠道类型
channelId int 必须 SDK 渠道ID
goodsId String 必须 SDK 渠道的档位ID
refund int 必须 SDK 退款状态，1表示退款订单
refund_time String 必须 SDK 用户退款时间

额外字段说明，是代金券、iOS订阅、其他需求可使用

参数 类型 重要性 来源 描述
iap_sub_expire String 必须 SDK 订阅：过期时间 仅英雄国内iOS渠道、华为渠道下有该字段
paytype String 必须 SDK 支付类型 仅英雄国内iOS渠道、华为渠道下有该字段
dealAmount String 可选 SDK 使用了英雄SDK代金券实际支付的金额 仅英雄国内渠道、华为渠道下有该字段

3.3 退款回调数据示例

data解密后的示例

{
  "iap_sub_expire": "",
  "amount": 30,
  "orderNo": "HUA10********",
  "payTime": "2020-06-28 18:26:14",
  "goodsId": "****",
  "channelUid": "*****",
  "selfDefine": "****",
  "channel": "ihero",
  "sandbox": "",
  "iap_sub": "",
  "qkChannelId": 0,
  "gameOrder": "****",
  "refund_time": "2020-06-29 02:34:20",
  "goodsName": "****",
  "channelId": 56,
  "status": 0,
  // 0代表成功，不为0代表失败
  "refund": 1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

3.4 退款回调返回响应

  1. SUCCESS (注意，只有这7个字符，不能有空白或其它字符）

  2. 通知的解密签名计算

3.5 退款回调重试策略 退款回调通知每间隔5分钟连续通知3次，在收到SUCCESS应答后即停止。

# 4 区服列表

4.1 接口说明

  1. 区服列表用于商城中的展示

  2. 区服列表地址: 接入完成后在【USDK管理后台 (opens new window) -游戏管理-游戏基础信息】中填写区服列表的地址

  3. 请求方法: POST

4.2 响应参数

参数 类型 重要性 描述
server_id String 必须 区服ID
server_name String 必须 区服名称
  • 响应示例
{
  "code": 0,
  "msg": "",
  "data": [
    {
      "server_id": "游戏区服id",
      "server_name": "游戏区服名"
    },
    {
      "server_id": "区服1",
      "server_name": "区服名1"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 5 角色校验

5.1 接口说明

  1. 角色校验用于商城或者其他校验场景

  2. 角色校验地址: 接入完成后在【USDK管理后台 (opens new window) -游戏管理-游戏基础信息】中填写角色校验地址

  3. 请求方法: POST

5.2 参数

字段 名称 重要性 说明
data String 必须 通知主要内容，需要解密。格式见下文
sign String 必须 签名

data各字段说明:

参数 类型 重要性 描述
server_id String 必须 区服ID
server_name String 必须 区服名称

5.3 响应参数

参数 类型 重要性 描述
role_name String 必须 游戏角色名
server_name String 必须 游戏服务区名
cpUid String 必须 cp用户唯一标识
cUid String 必须 usdk方渠道用户id
cid Int 必须 usdk方渠道id
  • 响应示例
{
  "code": 0,
  "msg": "",
  "data": {
    "role_name": "角色名称",
    "server_name": "区服名称",
    "cpUid": "cp唯一uid",
    "cUid": "usdk 渠道用户ID",
    "cid": "渠道ID"
  }
}
1
2
3
4
5
6
7
8
9
10
11

# 6 游戏下单

6.1 接口说明

  1. 游戏下单用于所有商城购买,如官方商城,抖音商城

  2. 游戏下单支持渠道： 仅支持官方渠道英雄互娱-官方安卓 (渠道id：18) 英雄互娱-iOS正版 (渠道id：56)

  3. 游戏下单地址: 接入完成后在【USDK管理后台 (opens new window) -游戏管理-游戏基础信息】中填写下单地址地址

  4. 请求方法: POST

6.2 下单参数

字段 名称 重要性 说明
data String 必须 通知主要内容，需要解密。格式见下文
sign String 必须 签名

data各字段说明:

参数 类型 重要性 描述
role_id String 必须 角色ID
server_id String 必须 区服ID
sku String 可选 cp方的档位,与skuList 二选一
skuList Array 可选 cp方的档位集合,用于批量下单,[{"sku":"123","num":1},{"sku":"234","num":2}]
cpExt String 必须 渠道的用户id
extra Json 可选 渠道的用户id

6.3 响应参数

参数 类型 重要性 描述
cpOrderNo String 必须 cp订单号
cpCustomMsg String 可选 订单透传信息
cpNotifyUrl String 可选 自定义的回调地址。不指定则采用USDK的回调地址
cpSku String 可选 中台的档位信息, 可为空, skuList 采用999999档位
  • 响应示例
{
  "code": 0,
  "msg": "",
  "data": {
    "cpOrderNo": "单号",
    "cpCustomMsg": "透传",
    "cpNotifyUrl": "通知地址",
    "cpSku": ""
  }
}
1
2
3
4
5
6
7
8
9
10

# 7 发货回调

7.1 接口说明

在收到 USDK 支付回调，并且校验订单合法性，将发货结果通知 USDK，以便 USDK 进行监控发货异常，**建议使用异步处理，以便不影响主流程业务。 **

7.2 请求地址

备注： 以下SDK请求地址都是正式环境，无测试环境，游戏测试时也使用SDK正式环境地址

  • 国内请求地址：

    • https://data-track.yingxiong.com/v1/track/server/data

  • 全球请求地址：

    • https://data-track-global.yingxiong.com/v1/track/server/data

7.3 请求参数

字段 必填 类型 字段说明
pcode 必填 String productId usdk产品ID
data 必填 String 加密后的值，加密前的参数值参考1.4.1 参数生成规则
timestamp 必填 String 时间戳，格式如：1626320008
sign 必填 String 签名 参数生成规则

7.3.1 data参数

字段 必填 类型 字段说明
eventType 必填 String 事件类型，该处固定为：sdk_order_callback
channel 必填 String 渠道码,hero、baidu、ysdk
channelId 必填 String 渠道ID
cUid 必填 String 渠道用户ID
cName 可选 String 渠道用户名称
orderNo 必填 String 聚合SDK订单号
cpOrderId 必填 String 游戏自己的订单号，与创建订单事件中该字段一致
goodsId 必填 String 商品ID，与创建订单事件中该字段一致
amount 必填 String 本次充值金额
unit 必填 String 货币单位：CNY(人民币)、USD(美元)、AUD(欧元)、JPY(日元)、HKD(港元)、GBP(英镑)等
payTime 必填 String 充值时间，Unix时间戳，格式如：1626320008
roleName 必填 String 角色名称
roleId 必填 String 角色ID
serverName 必填 String 区服名称
serverId 必填 String 区服ID
roleLevel 可选 String 角色等级
vipLevel 可选 String VIP等级
totalCharge 可选 String 玩家累计充值金额（加上本次充值的）
getTime 可选 String 到账时间，Unix时间戳，格式如：1626320008
extraGet1 可选 String 充值获得代币数量（不含赠送代币）
extraGet2 可选 String 充值获得赠送代币数量（充值获得赠送代币数量）
moneyType 可选 String 获得代币类型
paymentMethod 可选 String 付款方式：1（sdk支付：常规付款操作）、2（虚拟支付：测试使用，无真实消费）、3（英雄线下付款）
status 必填 String 状态，0（成功）、1（失败）
msg 可选 String 补充信息，例如失败原因等

7.4 请求示例 参数格式和登录鉴权一致。

curl http://data-track.yingxiong.com/v1/track/server/data -d 'data=eWJhbW91bnRiOiIzLjFiMDAwMCIsImNVayQiOiJkYzQjOTkxNzAwMTI0NzYyIiwiY3BPcmRlcklkIjoiSFVBMTAyNTI3NDM2ODMiLCJldmVudFR5cGUiOiJzZGtfb3JkZXJfY2FsbGJhY2siLCJnb29kc0lkIjoiMTEwIiwib3JkZXJObyI6IkhVQTEwMjUyNzQzNjgzIiwicGF5VGltZSI6IjE2NTM1MzU4MTMiLCJyb2xlSWQiOiIwNjc5LTAwLTIwMjIwNTI2LTEwMTg1NS0wMDAwMDIyIiwicm9sZU5hbWUiOiLljJfmtbfms7DkuJ0iLCJzZXJ2ZXJJZCI6IjY3OSIsInNlcnZlck5hbWUiOiI2NzkiLCJ1bml0IjoiQ05ZIn0%3D&pcode=10081&sign=9f92a8f1fb7be1c71e75ad9bf12543d1&timestamp=1681911701'
1

7.5 响应参数

字段 名称 重要性 类型 说明
code 状态 必填 int 业务状态
msg 描述 可选 String -

7.6 响应示例

{
   "code": 0, // 0代表成功，不为0代表失败
   "msg": "Success"
}
1
2
3
4

7.7 返回码

code 说明
0 成功
999 必传参数不齐[pcode, data, timestamp, sign]
998 sign校验不通过
997 data校验不通过
996 data不是正确的json字符串
995 缺失必传字段
500 服务端错误
其它 其它均为失败 具体错误，参考响应里的msg

# 恭喜你完成USDK服务端接入，现在开始正式测试吧～

本文档对解决你的问题有所帮助？
本页目录