安卓接入文档
SDK接入说明
iOS接入文档
SDK接入说明
WebSdk接入文档
WebSDK接入 PC端SDK接入
服务端接入文档
SDK服务端接入 GM功能接入说明 附录-错误码表 附录-基础码表
数据接入文档
SDK打点接入 服务端打点接入 游戏快照接入

SDK服务端接入说明文档

1 接入必读

  • 接口协议:HTTP
  • HTTP method:POST
  • content-type:application/json;
  • 数据格式:JSON格式（UTF-8编码）

2 校验码规则

  • 未特殊说明时，所有接口都需要按照如下校验码规则进行相关Header预置和校验
  • 校验码 Header 介绍
    注意：platform-auth-version和content-encrypt-type都需要写
    1. platform-auth-version:固定写死 v3  (旧版标识)
    2. content-encrypt-type:固定写死 v3 （新版标识）
    3. platform-auth-timestamp:服务器时间戳，毫秒数
    4. platform-auth-key-id:秘钥keyId，第三方平台由GSC平台统一进行分配； 游戏产品接入以平台的productId+localeId进行替代（如GMT接入、登录校验及充值发货等）；
    5. platform-auth-checksum:请求数据计算后的校验码
  • 校验码原理及作用
    校验码即 platform-auth-checksum 是为了防止双方通信过程中交换的数据被篡改的一种通用校验方式。 由交换数据双方按照某种规则组装生成请求明文数据， 然后追加上当前时间戳和双方协商好的秘钥[需要线下获取] ，生成校验码明文， 再通过对明文进行散列值计算获取到数据指纹即校验码， 请求方把时间戳、校验码版本号、秘钥ID以及校验码放到Header头中发送给服务方，服务方获取后再次按照相同进行计算数据指纹， 通过比较自己生成和请求方传递过来得数据指纹是否一致来确定数据是否合法。
  • 校验码明文
    本次请求body体中的数据
  • 散列值计算
    校验码散列值算法：MD5， 注意取32位md5，并转小写。
  • 示例
    请求body中的json如下
  1. {"productId":"20000099","localeId":"01"}

假设平台分配的产品和发行地域为20000099和01， 当前的毫秒时间戳为:1600422195516, key(秘钥)为:eea2e42511c3294d47b4d2deaf4ea33c
组装后的校验码明文串如下（注意原始数据和时间戳以及密码key之间通过&符号连接）： 

  1. {"productId":"20000099","localeId":"01"}&1600422195516&eea2e42511c3294d47b4d2deaf4ea33c

生成校验码如下

  1. 203a8da1b841c19673518b5cc3419ab6

注意：此时该请求的header头的四个校验码相关的header值如下

  1. platform-auth-version:v3
  2. content-encrypt-type:v3
  3. platform-auth-timestamp:1600422195516
  4. platform-auth-key-id:2000009901
  5. platform-auth-checksum:203a8da1b841c19673518b5cc3419ab6

3 登录

3.1 登录验证接口

基本信息

Path： /api/v2/server/user/auth
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

游戏服务端登录验证，注意：header中需要增加platform-auth-token

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/auth

响应内码介绍：

reset 描述
40099999 未知错误； 判定为非法请求
40010000 sessionId或token失效
50199999 其他错误；
50126001 该token未登录

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是
platform-auth-token 是 3f6f7c2a6e39cd006cf7c8747df045f9 通过SDK获取的token

Body

名称类型是否必须默认值备注其他信息
productIdstring必须当前产品ID
localeIdstring必须当前产品发行地域

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息
dataobject必须验证返回的用户数据
├─userIdstring必须平台用户ID，需要研发与客户端获得的userId进行验证，避免伪造数据
├─userIdV1string必须旧版本用户ID；如果没有传空串
├─nickNamestring必须根据使用不用的授权方式登录该值有所不同，同客户端SDK返回的昵称属性；账密登录：账号；邮箱登录：邮箱；手机号登录：手机号；三方登录：显示通过三方获取的昵称
├─userNamestring必须平台用户名，注意：如果用户未绑定账密账号，该值返回用户ID
├─phonestring必须用户绑定的手机号，可能为空
├─emailstring必须用户绑定的邮箱，可能为空
├─loginTypestring必须当前登录方式；speedy：快登用户common：用户名密码用户phone：手机号用户email:邮箱用户thirdHidden：三方授权用户accessToken：token登录
├─originalUserTypestring必须首登时的授权用户方式；speedy：快登用户common：用户名密码用户phone：手机号用户email:邮箱用户thirdHidden：三方授权用户
├─bindChannelIdsstring[]必须绑定渠道列表

item类型:string

├─非必须渠道标识；
三方绑定返回绑定的三方用户系统ID,如Facebook:0231; Google:0494 Apple: 0493
官方账号返回官方用户系统ID+绑定类型,如0001-phone：标识绑定了手机号；0001-email:绑定了邮箱；0001-common绑定了账密；
├─rechargeLimitobject必须用户充值限制配置信息
├─preTimeCoststring必须用户每次限额，-1代表不限额，单位：分
├─monthTotalCoststring必须用户每月限额，-1代表不限额，单位：分

返回示例：

3.2 获取当前登录用户绑定列表接口

基本信息

Path： /api/v2/server/user/bind/list
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

游戏服务端登录验证，注意：header中需要增加platform-auth-token

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/bind/list

响应内码介绍：

reset 描述
40099999 未知错误； 判定为非法请求
40010000 sessionId或token失效
50199999 其他错误；
50126001 该token未登录

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是
platform-auth-token 是 3f6f7c2a6e39cd006cf7c8747df045f9 通过SDK获取的token

Body

名称类型是否必须默认值备注其他信息
productIdstring必须当前产品ID
localeIdstring必须当前产品发行地域

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息
dataobject必须验证返回的用户数据
├─userIdstring必须平台用户ID，需要研发与客户端获得的userId进行验证，避免伪造数据
├─bindChannelIdsstring[]必须绑定渠道列表

item类型:string

├─非必须渠道标识；
三方绑定返回绑定的三方用户系统ID,如Facebook:0231 Google:0494 Apple:0493 ;
官方账号返回官方用户系统ID+绑定类型,如0001-phone：标识绑定了手机号；0001-email:绑定了邮箱；0001-common绑定了账密；

返回示例：

4 发货

4.1 充值发货接口

基本信息

  • Path: 游戏服发货地址?service=recharge.notify&server=游戏服ID
    Method： POST
    接口描述：
    SDK平台服务端 -> 游戏服务端
    该接口由游戏按规范提供，王牌运营技术平台通过该接口实现游戏充值发货功能

  • 安全验证
    游戏需验证订单金额(chargePrice)和游戏内该商品价格是否相等，如果不相等，应该不予发货，返回“商品异常”即可；
    为了保证数据安全性，建议游戏服务器对平台的请求IP地址做鉴权处理，需要认证的IP详见附录；
    游戏发货时要判断下单价格和商品ID相匹配，才能发货，否则不发货。比如6480钻石的价格是648元人民币，商品ID是com.shangpin.rmb648，当通知游戏发货的价格变为1元，商品ID不变的时候，应拒绝发货返回“商品异常”，不能仅判断商品ID去发货。
    游戏发货时需要判断用户ID[userId]和角色ID[roleId]是否匹配（即判断该角色ID是否属于该用户ID），防止出现跨平台作弊充值的情况；若出现该情况请返回指定的响应码（1006）

  • 重试机制
    因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知，需要运营人员手动在GSC上进行手动“通知发货”；因涉及重新通知，因此需要研发确保相同平台侧的订单号(orderId)若已经正常发货则不可重复发货，此时返回0002即可。

  • actualPrice 实际支付金额，默认和下单金额相同，当在王牌计费平台进行打折时，才会与下单金额不同；

  • callbackPrice 计费商回调计费金额，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的金额； 可能为空，如无特殊需求，研发侧可以忽略该字段。
  • callbackCurrencyType 计费商回调计费货币，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的货币； 可能为空，如无特殊需求，研发侧可以忽略该字段。

响应内码介绍：

reset 描述
0001 发货成功（status为0，下面的其他码status为1）
0002 该订单已经正常发货
1001 用户异常
1002 角色异常
1003 逻辑服异常
1004 商品异常
1005 发货失败
1006 用户ID与角色ID不匹配
1007 限购商品，不允许发货
1008 非法请求IP

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是

Body

名称类型是否必须默认值备注其他信息
servicestring必须固定为:recharge.notify
orderIdstring必须平台订单号
orderTypestring必须订单类型；1：消耗型；2；首次订阅；3；订购续订；
orderSourcestring必须下单来源；1：游戏内；2：页充；3：后台代充；4：模拟充值；
testOrderstring必须是否沙盒订单；0：不是；1：是
serviceIdstring必须产品平台ID
channelIdstring必须推广渠道ID
deviceGroupIdstring必须0000：安卓；0002：IOS;0024:windows；0025：H5
localeIdstring必须发行地域；
userIdstring必须平台用户ID
serverIdstring必须区服ID
roleIdstring必须角色ID
propIdstring必须商品ID
payChannelIdstring必须支付方式ID，若有需要根据支付方式做相关业务，请找平台技术支持提取支付方式对应关系
chargePricestring必须下单金额
actualPricestring必须支付金额；默认同下单金额；当出现在王牌计费平台打折时，才与下单金额不相等；
callbackPricestring选填计费商回调金额；可能为空
callbackCurrencyTypestring选填计费商回调支付货币；可能为空
extendParamsstring必须下单时透传的扩展参数；
rechargeRebateobject必须
├─rebateTypestring必须返利类型GOODSID：按照商品ID返利；PRICE：按照充值金额进行返利
├─pricestring必须返利金额;返利类型为PRICE时使用；
├─goodsIdstring必须返利商品ID；返利类型为GOODSID时使用；
expirationTimestring可选订阅商品时，订阅截止时间，时间戳，精确到毫秒；非订阅商品传null；示例：1705386062054

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息

请求示例：

  1. {
  2. "orderId": "0992023100811105979700",
  3. "orderType": "1",
  4. "orderSource": "1",
  5. "testOrder": "0",
  6. "serviceId": "2000003431014300000",
  7. "channelId": "3101430031014300",
  8. "deviceGroupId": "0000",
  9. "localeId": "01",
  10. "userId": "90099910335DD23341995A944A112D5ACAA329E2",
  11. "serverId": "10002",
  12. "roleId": "1",
  13. "propId": "1001",
  14. "payChannelId": "210339000014000051014300",
  15. "chargePrice": "64800",
  16. "actualPrice": "64800",
  17. "currencyType": "1",
  18. "extendParams": "{\"innerOrder\":\"ddddddd\",\"GGGGG\":\"ggggg\"}",
  19. "rechargeRebate": null
  20. }

4.2 退费通知接口

基本信息

  • Path: 游戏服发货地址?service=refund.notify&server=游戏服ID
    Method： POST
    接口描述：
    SDK平台服务端 -> 游戏服务端
    该接口由游戏按规范提供，王牌运营技术平台通过该接口实现游戏退费通知

  • 重试机制
    因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知，需要运营人员手动在GSC上进行手动“通知发货”；因涉及重新通知，因此需要研发确保相同平台侧的订单号(orderId)若已经正常发货则不可重复发货，此时返回0002即可。

  • actualPrice 实际支付金额，默认和下单金额相同，当在王牌计费平台进行打折时，才会与下单金额不同；

  • callbackPrice 计费商回调计费金额，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的金额； 可能为空，如无特殊需求，研发侧可以忽略该字段。
  • callbackCurrencyType 计费商回调计费货币，个别计费通道如：xsolla，支付完成时可以获取到用户实际付款的货币； 可能为空，如无特殊需求，研发侧可以忽略该字段。

响应内码介绍：

reset 描述
0001 接收成功（status为0，下面的其他码status为1）
1003 逻辑服异常
1008 非法请求IP

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是

Body

名称类型是否必须默认值备注其他信息
servicestring必须固定为:refund.notify
orderIdstring必须平台订单号
orderTypestring必须订单类型；1：消耗型；2；首次订阅；3；订购续订；
orderSourcestring必须下单来源；1：游戏内；2：页充；3：后台代充；4：模拟充值；
testOrderstring必须是否沙盒订单；0：不是；1：是
serviceIdstring必须产品平台ID
channelIdstring必须推广渠道ID
deviceGroupIdstring必须0000：安卓；0002：IOS;0024:windows；0025：H5
localeIdstring必须发行地域；
userIdstring必须平台用户ID
serverIdstring必须区服ID
roleIdstring必须角色ID
propIdstring必须商品ID
payChannelIdstring必须支付方式ID，若有需要根据支付方式做相关业务，请找平台技术支持提取支付方式对应关系
chargePricestring必须下单金额
actualPricestring必须支付金额；默认同下单金额；当出现在王牌计费平台打折时，才与下单金额不相等；
callbackPricestring选填计费商回调金额；可能为空
callbackCurrencyTypestring选填计费商回调支付货币；可能为空
extendParamsstring必须下单时透传的扩展参数；
rechargeRebateobject必须
├─rebateTypestring必须返利类型GOODSID：按照商品ID返利；PRICE：按照充值金额进行返利
├─pricestring必须返利金额;返利类型为PRICE时使用；
├─goodsIdstring必须返利商品ID；返利类型为GOODSID时使用；
expirationTimestring可选订阅商品时，订阅截止时间，时间戳，精确到毫秒；非订阅商品传null；示例：1705386062054

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息

请求示例：

  1. {
  2. "orderId": "0992023100811105979700",
  3. "orderType": "1",
  4. "orderSource": "1",
  5. "testOrder": "0",
  6. "serviceId": "2000003431014300000",
  7. "channelId": "3101430031014300",
  8. "deviceGroupId": "0000",
  9. "localeId": "01",
  10. "userId": "90099910335DD23341995A944A112D5ACAA329E2",
  11. "serverId": "10002",
  12. "roleId": "1",
  13. "propId": "1001",
  14. "payChannelId": "210339000014000051014300",
  15. "chargePrice": "64800",
  16. "actualPrice": "64800",
  17. "currencyType": "1",
  18. "extendParams": "{\"innerOrder\":\"ddddddd\",\"GGGGG\":\"ggggg\"}",
  19. "rechargeRebate": null
  20. }

4.3 礼包码发货接口

基本信息

  • Path: 游戏服发货地址?service=giftcode.notify&server=游戏服ID
    Method： POST
    接口描述：
    SDK平台服务端 -> 游戏服务端
    该接口由游戏按规范提供，王牌运营技术平台通过该接口实现礼包兑换发货功能；
  • 安全验证
    游戏需验证每个角色每个礼包码24小时内最多只能发一次货，防止重试机制导致多次发货；
    为了保证数据安全性，建议游戏服务器对平台的请求IP地址做鉴权处理，需要认证的IP详见附录；
    游戏发货时需要判断用户ID[userId]和角色ID[roleId]是否匹配（即判断该角色ID是否属于该用户ID），防止出现跨平台作弊充值的情况；若出现该情况请返回指定的响应码（1006）
  • 重试机制
    因网络抖动请求超时、游戏服务器维护导致请求网络异常或返回1003，平台会在第2、10、60、180分钟后重新进行通知，第四次（180分钟）如果还是通知失败，则不再进行重新通知；因涉及重新通知，有可能研发侧已经给玩家发过该礼包，需要给平台返回对应的状态码0002。 注意：需要游戏方面对礼包发放进行判断。同一个角色+同一个礼包码，24小时内最多能领取一次，不能重复发。避免在特殊情况下可能会给玩家重复发礼包。

响应内码介绍：

reset 描述
0001 发货成功（status为0，下面的其他码status为1）
0002 该订单已经正常发货
1001 用户异常
1002 角色异常
1003 逻辑服异常
1004 商品异常
1005 发货失败
1006 用户ID与角色ID不匹配
1007 限购商品，不允许发货
1008 非法请求IP

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是

Body

名称类型是否必须默认值备注其他信息
servicestring必须固定为:giftcode.notify
serviceIdstring必须产品平台ID
channelIdstring必须推广渠道ID
deviceGroupIdstring必须0000：安卓；0002：IOS;0024:windows；0025：H5
localeIdstring必须发行地域；
userIdstring必须平台用户ID
serverIdstring必须区服ID
roleIdstring必须角色ID
gameCodestring必须用户输入的礼包码
deliverInfoobject必须发货信息
├─typestring必须区分发放游戏内礼包还是物品列表；gamePackageId：标识按游戏内礼包ID发放；goodsList：按物品列表发放
├─gamePackageIdstring必须type为gamePackageId时标记游戏内礼包ID，其他时为空
├─goodsListobject[]必须type为goodsList时标记为发放的物品列表，其他时为空

item类型:object

├─goodsIdstring必须游戏内物品ID
├─goodsNumstring必须游戏内物品数量
├─goodsExtendInfostring必须单个物品的自定义参数
extendParamsstring必须SDK透传自定义参数

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息

返回示例：

5 预约

5.1 预约渠道查询

基本信息

Path： /api/v2/server/user/appintment/query
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

若游戏需要用户是否是预约用户，以及为预约用户发奖，需要调用该接口；
是否是预约用户的状态，平台侧从OB开始默认保留45天，45天后预约状态将返回空数组，若45天后还需要获取用户预约状态需要线下联系平台技术支持进行数据导出；

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/appintment/query

响应内码介绍：

reset 描述
40099999 未知错误； 判定为非法请求
40010000 sessionId或token失效
50199999 其他错误；
50126001 该token未登录

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是
platform-auth-token 是 3f6f7c2a6e39cd006cf7c8747df045f9 通过SDK获取的token

Body

名称类型是否必须默认值备注其他信息
productIdstring必须当前产品ID
localeIdstring必须当前产品发行地域

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息
dataobject必须验证返回的用户数据
├─userIdstring必须平台用户ID，需要研发与客户端获得的userId进行验证，避免伪造数据
├─userIdV1string必须旧版本用户ID；可能和userId相同
├─channelListobject[]必须预约渠道列表；若用户是不预约用户则返回空数组

item类型:object

├─channelstring必须预约渠道标识：google标识谷歌渠道，appstore标识苹果预约，phone标识官网手机号预约
├─statusstring必须是否领取过奖励；0：未领取；1：已领取

返回示例：

5.2 预约用户发奖

基本信息

Path： /api/v2/server/user/appintment/deliver
Method： POST
接口描述：
游戏服务端 -> SDK平台服务端

该接口由王牌运营技术平台提供，游戏服务端进行调用， 目的是实现对预约用户发放预约礼包；
注意：该接口在完成发送前校验后，会调用礼包码发货接口进行发货，请确认已经接入了平台的礼包码发货接口

接口域名：
全球区域：https://global-user.aceux.net/api/v2/server/user/appintment/deliver

响应内码介绍：

reset 描述
40099999 未知错误； 判定为非法请求
40010000 sessionId或token失效
50199999 其他错误；
50126001 该token未登录

请求参数

Headers

参数名称 参数值 是否必须 示例 备注
Content-Type application/json 是
platform-auth-token 是 3f6f7c2a6e39cd006cf7c8747df045f9 通过SDK获取的token

Body

名称类型是否必须默认值备注其他信息
productIdstring必须当前产品ID
localeIdstring必须当前产品发行地域
userIdstring必须用户ID
gameServerIdstring必须游戏服ID
roleIdstring必须角色ID
roleLevelstring必须角色等级
roleNamestring必须角色名称
roleVipLevelstring必须角色VIP等级
channelstring必须预约渠道，注意不是游戏包的渠道，对应用户预约渠道查询返回的channel；google标识谷歌渠道，appstore标识苹果预约，phone标识官网手机号预约

返回数据

名称类型是否必须默认值备注其他信息
statusstring必须0:成功；1：失败
resetstring必须详细内码
descstring必须描述信息

返回示例：

附录一 货币类型

货币ID 货币名称 货币单位
1 人民币 分
2 美元 美分
3 日元 円
4 港币 分
5 英镑 便士
6 新加坡币 分
7 越南盾 盾
8 台币 元
9 韩元 元
10 泰铢 萨当

附录二 IP鉴权

为了保证数据安全性，游戏服务器必须要对平台的请求IP地址做鉴权处理，需要认证的IP请联系技术支持获取

Copyright ©2020- 北京王牌互娱技术有限公司 版权所有

京ICP备20009004号

公司地址：北京市朝阳区北三环东路28号易亨大厦9层902