游戏接入指南

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): https://sgw.simiaoyuexin.com
  • AppId(21): https://sgw.xinyou7.com
  • AppId(22): https://sgw.youpin7.com
  • AppId(23): https://sgw.huanyou7.com
  • AppId(24): https://sgw.lejiawenhua.com
  • AppId(25): https://sgw.cangmaonet.com

海外环境{address}

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

登录验证

说明

  • 客户端登录成功之后会响应userId、token等参数
  • 客户端需要将userId、token等参数告诉游戏服务器,游戏服务器拿着这些参数进行一次登录验证
  • 可优先使用本地token算法验证减少网络请求,参考 token验证

请求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:是。仅在测试环境下生效:测试订单默认不发货,仅当 userId 加入研发白名单时才会发货。

响应格式

  • 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页面拆红包需要传入订单号

返利回调(可选)

说明

  • 如果玩家充值触发渠道返利条件,则会通过该接口通知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接口时,可以通过此接口获取小游戏accessToken
  • 小游戏AccessToken请求, 必传参数appIdchannelId

请求URL

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

请求格式

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

响应格式

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

小游戏订阅消息接口(可选)

说明

请求URL

  • {address}/mp/api/{appId}/send/subscribe

请求格式

  • 请求方式: HTTP GET/POST
  • Content-Type: application/x-www-form-urlencoded
参数类型描述
appIdint游戏id
channelIdint渠道ID
userIdlong用户ID
templateIdString所需下发的订阅模板 id
pageString点击模板卡片后的跳转页面,仅限本小程序内的页面。
dataString模板内容,请参照各家小游戏的格式要求进行填写。
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

data格式

小游戏平台格式
微信小游戏"{\"key1\":{\"value\":\"any\"},\"key2\":{\"value\":\"any\"}}"
抖音小游戏"{\"key1\":\"any\",\"key2\":\"any\"}"

响应格式

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

小游戏批量订阅消息接口(可选)

说明

请求URL

  • {address}/mp/api/{appId}/send/subscribe/batch

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/json:charset=utf-8
参数类型描述
appIdint游戏id
channelIdint渠道ID
templateIdString所需下发的订阅模板 id
pageString点击模板卡片后的跳转页面,仅限本小程序内的页面。
dataString批量订阅内容,默认处理100个,格式形如 [{ "userId": "", "userData": "{}" }]
tslongUnix时间戳
signString签名值参考签名算法,密钥使用APP_SECRET

data格式

参数类型描述
userIdlong用户ID
userDataString模板内容,请参照各家小游戏的格式要求进行填写。

userData格式

小游戏平台格式
微信小游戏"{\"key1\":{\"value\":\"any\"},\"key2\":{\"value\":\"any\"}}"
抖音小游戏"{\"key1\":\"any\",\"key2\":\"any\"}"

响应格式

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

用户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

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

请求格式

  • 请求方式: 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}}

添加企微完成回调

说明

  • 当用户完成添加企微客服后,会调用游戏服的添加企微完成回调地址,通知游戏服用户已成功添加企微客服。

请求URL

  • 使用游戏服务端提供的添加企微完成通知地址

请求格式

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

响应格式

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

通知栏消息推送-单条

说明

  • 通过用户Id给用户发送手机通知栏消息,当前支持的渠道有(oppo,vivo,华为,鸿蒙,荣耀,小米,苹果)
  • 异步请求,研发无需关注推送结果,只需要认状态码

请求URL

  • {address}/push/api/{appId}/send/single/message

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/json:charset=utf-8
参数类型必选描述
appIdint游戏ID
userIdstring用户ID
serverIdstring服务器ID
roleIdstring角色ID
titleString标题(长度限制在50个字符串以内)
contentString内容(长度限制在100个字符串以内)
actionTypeint行为类型(0:点击),不填默认点击
actionConfigString行为内容(包名或url),默认打开游戏
tslongUnix时间戳
apiVersionstring接口版本号,固定值v2
signString签名值参考签名算法,密钥使用APP_SECRET

响应格式

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

通知栏消息推送-批量

说明

  • 通过用户Id列表给多个用户发送手机通知栏消息,当前支持的渠道有(oppo,vivo,华为,鸿蒙,荣耀,小米,苹果)。
  • 异步请求,研发无需关注推送结果,只需要认状态码

请求URL

  • {address}/push/api/{appId}/send/batch/message

请求格式

  • 请求方式: HTTP POST
  • Content-Type: application/json:charset=utf-8
参数类型必选描述
appIdint游戏ID
userListString用户的JSON数组经过URL编码后的字符串。(条数上限制500)
titleString标题(长度限制在50个字符串以内)
contentString内容(长度限制在100个字符串以内)
actionTypeint行为类型(0:点击),不填默认点击
actionConfigString行为内容(包名或url),默认打开游戏
tslongUnix时间戳
apiVersionstring接口版本号,固定值v2
signString签名值参考签名算法,密钥使用APP_SECRET
  • userList数据结构
参数类型描述
userListJsonArray推送用户列表
  • user数据结构
参数类型描述
userIdString用户ID
serverIdString区服ID
roleIdString角色Id
  • userList数据结构示例
[{"userId":"306","serverId":"1060414","roleId":"2258080578840"},{"userId":"310","serverId":"1050913","roleId":"2238216355084"}]

响应格式

  • Content-Type: application/json:charset=utf-8
参数类型描述
codeint状态码
msgString提示信息
dataJSON成功时响应数据JSON
Last Updated:
Contributors: zjl, jishuqin, 纪树勤