游戏接入指南

AppId和商品档位可以参考渠道配置列表 :https://channels.begind.cn/

接口地址说明:

服务端接口地址区分环境,不同的AppId对应不同的地址,主要是域名不同,下文中使用{address}代替。

国内环境{address}

  • AppId(1-15): https://sgw.begindcc.com
  • AppId(16/17/20): https://sgw.xiayixing.com
  • AppId(18/21): https://sgw.simiaoyuexin.com
  • AppId(22): https://sgw.youpin7.com
  • AppId(23): https://sgw.huanyou7.com

海外环境{address}

  • 全部AppId: https://sgw.xiuzhenme.com

登录验证

说明

  • 客户端登录成功之后会响应userId、token等参数
  • 客户端需要将userId、token等参数告诉游戏服务器,游戏服务器拿着这些参数进行一次登录验证
  • 优先使用token算法验证,算法验证失败情况下再请求服务端URL进行验证

Token算法验证

Token格式

13003.T3.rQQzFFI7X9kjyiDEjbNnhRjXTKYjRPWerdwOkklmMXeMu1g85OHsZBtT3nxQtKknVwObtfmYoBTw_K661c5StQ

Token是一个长度小于255的字符串,中间用点(.)分隔成3个部分,依次是HeaderVersionPayload

  • Header 头部,值为渠道号
  • Version 版本号,当前版本号值为T3
  • Payload 负载,使用AES算法加密后Base64编码URLSafe的字符串

Payload内容定义

AES(channelId-userId-timestamp-channelUserId)
// 例如
AES(13003-24280710-1685709477-e7f779c82f804882ba18c5c38ed7cb4b)
  • channelId 当前登录的渠道ID
  • userId UFO用户ID
  • timestamp 时间戳(秒),表示token生成时间,用于校验token时效性(比如60分钟内有效)
  • channelUserId 第三方渠道的用户ID(仅供参考,游戏内可忽略)
密文 rQQzFFI7X9kjyiDEjbNnhRjXTKYjRPWerdwOkklmMXeMu1g85OHsZBtT3nxQtKknVwObtfmYoBTw_K661c5StQ
AES解密之后
明文 13003-24280710-1685709477-e7f779c82f804882ba18c5c38ed7cb4b

AES算法说明

  • AES加密模式:ECB
  • AES加密模式:PKCS5Padding
  • 密钥长度:256位
  • 密文编码:Base64 URLSafe
  • 字符编码:UTF-8
  • 解密Secret Key: 联系运营获取

解密工具AES Encryption and Decryption Online Toolopen in new window

Token示例

13003.T3.rQQzFFI7X9kjyiDEjbNnhRjXTKYjRPWerdwOkklmMXeMu1g85OHsZBtT3nxQtKknVwObtfmYoBTw_K661c5StQ
13108.T3.k_KWhzWMMY840voOlAH5dXd_6aERARR0F3GvQbXQd5rWPPfYv_lxmw8sxQN3OFDSCVP3qxfaBPloDbdwjKegvw
13301.T3.p98G7M7YnfCS9UxQ8vJapFEXmhXpYoPvSWK7c5wUIBOqNgBRYjUx3HTFlF5oA6aHwx7bNWa0T_CO2WSdVYztxbOIFSDm8oDp3IZn-SXmHn8
13303.T3.8befuFi8NzV9qZ9T9ATGtZxNgt4F8cPwv1XliedK0l-A0_NZR20WNatDHwhxgjzRdM78_BCdCbcK8yWe4CsqcQ
13306.T3.6rZvRXCEpXzCDXkuKkKQ2ziBVb_tYuveKWgqMIlRAYyL1DGtuBx4nlZBvmq0MHg4
13307.T3.ZyyVJtFqCtZ0dLEdUFnNtKseV8S43n2qANR_4aD_S8_V4R7Vg85JsAQDsIhERih9nDqfCM_WJBFK_8oiylN_Ew
13309.T3.ZkCLAJuGdetfcaiivsQu0Vj6gzlkmvkz3P4OLiYBFefUNE0PEXDStM6gMmaFKIT8

解密示例

解密示例

请求URL验证

  • {address}/ufo/api/{appId}/user/verify

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
tokenStringToken
channelIdint渠道ID
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
userIdString用户ID唯一,账号关联标识
channelUserIdString渠道用户ID与accountChannelId联合对应userId
channelIdint渠道号可用于区分服务器显示
accountChannelIdint账号渠道号同渠道号,游戏内无须关心
extensionString扩展字段 可为空
typeint账号类型0为普通用户,1为白名单用户

支付回调

说明

  • 当平台收到渠道SDK支付回调并处理成功时,会调用游戏服的支付回调地址,通知游戏服给玩家发货
  • 该回调地址,客户端在调用支付接口的时候,通过notifyUrl字段传入SDK
  • 游戏需通过cpOrderId,将游戏订单上的roleId/productId/money与回调信息进行对比校验
  • orderId(平台订单号)具有全局唯一性,游戏可对其唯一性进行校验

请求URL

  • 优先使用客户端调用支付接口时传入的notifyUrl
  • 当notifyUrl为空时使用游戏默认配置

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID补单时为补单渠道号
userIdString用户ID
orderIdString平台订单号
cpOrderIdString游戏订单号
productIdString商品ID
currencyString货币类型,默认CNY,ISO4217
moneyint充值金额,单位
serverIdString游戏服务器ID
roleIdString角色ID
extensionString透传字段,游戏自定义参数,原样返回
versionString接口版本号,固定值v2
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET
rechargeString补单标识,如果是补单则固定值为recharge
rechargeChannelIdint当订单为补单时,该值赋值为用户真实渠道号
orderTypeint0=内购,1=订阅,内购与首次订阅会有cpOrderId,续订cpOrderId会为空
subscriptionIdString订阅id,一组订阅订单的关系标识
subscriptionTypeint订阅类型,1=首次订阅,2=续订
isTestint是否是测试订单, 0:不是,1:是

响应格式

  • Content-Type: text/plain
  • 游戏服务器处理成功,直接返回一个"SUCCESS"字符串即可,失败返回一个"FAIL"字符串

访客ID-数数(可选)

请求URL

  • {address}/ufo/api/{appId}/thinking/getDistinctId

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
channelIdint渠道ID
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
userIdString用户ID唯一,账号关联标识
distinctIdString访客ID 用户在未登录状态下的ID

发送验证码(可选)

请求URL

  • {address}/ufo/api/{appId}/channel/sendCode

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
phoneString手机号
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息

绑定手机号(可选)

请求URL

  • {address}/ufo/api/{appId}/channel/bindPhone

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
phoneString手机号
codeString验证码
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
userIdString用户ID
phoneString成功绑定的手机号

换绑手机号(可选)

请求URL

  • {address}/ufo/api/{appId}/channel/changeBindPhone

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
phoneString手机号
codeString验证码
newPhoneString新手机号
newCodeString新手机号对应验证码
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
userIdString用户ID
phoneString成功换绑的手机号

校验验证码(可选)

请求URL

  • {address}/ufo/api/{appId}/channel/verifyCode

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏ID
userIdString用户ID
phoneString手机号
codeString验证码
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
userIdString用户ID
phoneString成功绑定的手机号

广告回调(可选)

说明

  • 当用户观看完激励视频广告后,平台会通知游戏服给玩家发货
  • 游戏服务器收到并验证通过后即应响应平台(不应等发货完成后再响应)

请求URL

  • 优先使用客户端在调用加载广告接口时传入的notifyUrl
  • 当notifyUrl为空时使用游戏默认配置

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID
userIdString用户ID
orderIdString平台订单号
cpOrderIdString游戏订单号
posIdString广告位ID
rewardNameString奖励名称
rewardAmountint奖励数量
serverIdString游戏服务器ID
roleIdString角色ID
extensionString透传字段,游戏自定义参数,原样返回
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: text/plain
  • 游戏服务器处理成功,直接返回一个"SUCCESS"字符串即可,失败返回一个"FAIL"字符串

创建红包(可选)

请求URL

  • {address}/ufo/api/{appId}/rebate

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID
userIdString用户ID
orderIdString平台订单号
cpOrderIdString游戏订单号,同一订单号只会返利一次
moneyint返利金额,单位
wishingString返利祝福语
rebateNameString返利活动名称
serverIdString游戏服务器ID
serverNameString游戏服务器名称
roleIdString角色ID
roleNameString角色名称
roleLevelint角色等级
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
channelOrderIdString渠道订单号,手Q使用H5页面拆红包需要传入订单号

模板消息(可选)

请求URL

  • {address}/ufo/api/{appId}/notice

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID
userIdString用户ID
templateIdString消息模板ID
pageint点击模板卡片后的跳转页面,仅限本小程序内的页面(示例page/index/index?foo=bar)
dataString模板内容,要求字段数量和模板本身的字段数量一致JSON文本
keywordString模板需要放大的关键词,不填则默认无放大
useOacboolen是否通过小程序绑定的公众号下发,需要提前配置公众号appid
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息

订阅消息(可选)

请求URL

  • {address}/ufo/api/{appId}/subscribe

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID
userIdString用户ID
templateIdString消息模板ID
pageint点击模板卡片后的跳转页面,仅限本小程序内的页面(示例page/index/index?foo=bar)
dataString模板内容,要求字段数量和模板本身的字段数量一致JSON文本
keywordString模板需要放大的关键词,不填则默认无放大
useOacboolen是否通过小程序绑定的公众号下发,需要提前配置公众号appid
useRobotboolen是否通过客服机器人下发
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息

返利回调(可选)

说明

  • 如果玩家充值触发渠道返利条件,则会通过该接口通知CP给玩家返利
  • 通知参数为触发返利订单的数据
  • 具体返利金额由CP决定,建议为5%-10%一级货币
  • 同一笔订单只会返利一次,CP必须要有处理重复通知的逻辑

请求URL

  • 游戏CP提供

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
channelIdint渠道ID
userIdString用户ID
orderIdString平台订单号
cpOrderIdString游戏订单号
productIdString商品ID
currencyString货币类型,默认CNY,ISO4217
moneyint充值金额,单位
serverIdString游戏服务器ID
roleIdString角色ID
extensionString透传字段,游戏自定义参数,原样返回
versionString接口版本号,固定值v2
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: text/plain
  • 游戏服务器处理成功,直接返回一个"SUCCESS"字符串即可,失败返回一个"FAIL"字符串

兑换码验证(可选)

流程及说明

  • 玩家通过渠道(抖音等)购买兑换码卡券,获取可兑换相应道具礼包的兑换码。
  • 兑换码由我方生成并给到用户,游戏只需要在兑换入口处获取到兑换码后,通过该接口调用给我方即可。
  • 我方验证通过后消码,并且通过发送邮件功能进行对应礼包道具发放。
  • 注:如果是限定角色只能使用一次的兑换码,在同一角色使用过后,后续使用会使用失败,具体失败原因会在响应消息体msg内进行说明

请求URL

  • {address}/coupon/api/verify

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
userIdString用户ID
couponIdString兑换码ID
serverIdString游戏服务器ID
serverNameString游戏服务器名称
roleIdString角色ID
roleNameString角色名称
versionString接口版本号,固定值v2
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息

小游戏AccessToken(可选)

说明

  • 小游戏需要调用小游戏官方API接口时,可以通过此接口获取小游戏accessTokenopenId
  • 小游戏AccessToken请求, 必传参数appIdchannelIduserId

请求URL

  • {address}/ufo/api/{appId}/user/accessToken

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏id
userIdString用户ID
channelIdint渠道ID
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
accessTokenString小游戏接口调用凭证
expiresInint凭证有效时间,单位:秒
openIdString小游戏的openId

用户Id(可选)

说明

  • 研发需要通过渠道用户Id反向获取用户Id

请求URL

  • {address}/ufo/api/{appId}/user/info

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏id
channelUserIdString渠道用户id
channelIdint渠道id
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
appIdint游戏id
userIdString用户id
channelIdint渠道id
channelUserIdString渠道用户id

活动信息回传(可选)

说明

  • 活动通用事件回传接口

请求URL

  • {address}/transfer/activity/record

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏id
userIdString用户ID
channelIdint渠道ID
activityIdint活动ID
pointString活动节点
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON

活动参与条件获取(可选)

说明

  • 游戏某些活动需要控制参与人数、角色等信息,此接口用来获取活动参与条件

请求URL

  • {address}/transfer/activity/config

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏id
idint活动id
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataList成功时响应数据List
  • data数据结构
参数类型描述
conditionString条件名称
contrastint对比类型
valueString
  • data数据结构示例
  • 角色等级>=100 且 角色vip等级>=1
[{"condition":"roleLevel", "contrast":5, "value":"100"}, {"condition":"roleVipLevel", "contrast":5, "value":"1"}]
  • condition数据枚举值
类型描述
roleLevelString角色等级
rolePowerString角色战力
mainLevelString主线关卡
dateActiveString当天活跃度(活跃度是游戏内每日任务的进度)
totalActiveString累计满活跃次数
drawCountString高招次数(高级招募次数)
dateAliveString当天在线时长(分钟)
chatCountString聊天发言次数
roleVipLevelStringvip等级
createDateString创角天数
totalPayString角色累充金额
  • contrast数据枚举值
类型描述
1int小于 >
2int小于等于 >=
3int等于 =
4int大于 <
5int大于等于 <=

获取用户可填写问卷列表(可选)

说明

  • 在游戏中,用户可能需要填写问卷以提供反馈或参与调查。此接口用于获取当前用户可填写的问卷列表。

请求URL

  • {address}/survey/user/form/available

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型必选描述
appIdint游戏ID
serverIdString服务器ID
roleIdString角色ID
roleNameString角色名称
userIdString用户ID
extraString拓展字段
apiVersionString接口版本号,固定值v2
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSONArray问卷表单列表
  • data数据结构
参数类型描述
appIdString游戏id
formKeyString问卷唯一标识
formUrlString问卷表单链接
formNameString问卷表单名称
formDescString问卷表单描述
expireTimelong问卷链接过期时间Unix时间戳
sortint问卷表单排序
  • data数据结构示例
{"code":1,"msg":"成功","data":[{"appId":13,"formUrl":"`{address}`/survey/s/u7EwmWqn?sign=8df74b54aa19b69af3ddfb67f61c90aa","formKey":"u7EwmWqn","formName":"用户调查问卷","formDesc":"用户调查问卷","expireTime":1738917458,"sort":1}]}

问卷完成回调

说明

  • 当用户完成问卷后,会调用游戏服的问卷回调地址,通知游戏服用户问卷已完成。

请求URL

  • 使用问卷后台配置的通知地址

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/json:charset=utf-8
参数类型必选描述
submitIdlong同一份问卷中的提交唯一ID
formKeyString问卷唯一标识
appIdint游戏ID
channelIdint渠道ID
serverIdString服务器ID
roleIdString角色ID
roleNameString角色名称
userIdString用户ID
extraString拓展字段
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET
apiVersionString接口版本号,固定值v2

响应格式

  • Content-Type: text/plain
  • 游戏服务器处理成功,直接返回一个"SUCCESS"字符串即可,失败返回一个"FAIL"字符串

查询用户是否添加企微(可选)

说明

  • 游戏内判断用户是否添加了企微,根据响应给用户发放奖励。

请求URL

  • {address}/push/api/{appId}/qw/user/exist

请求格式

  • 请求方式: HTTP GET
  • Content-Type: application/x-www-form-urlencode
参数类型必选描述
userIdString用户Id
appIdint游戏id
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
  • data数据结构
参数类型描述
existUserIdboolean是否添加企微
  • data数据结构示例
{"code":1,"msg":"Success","data":{"existUserId":false}}
Last Updated:
Contributors: xieliang, 谢梁