SDK服务器对接文档

登录验证


游戏服务器端访问下面的连接

https://auth.17995api.net/rest/v1/auth

HTTP 增加请求头 "Authorization: JWT参数"
jwt参数 由客户端请求SDK登录成功后获得, 查看“登录通行证”

请求成功返回
{"code":0, "uid":通行证UID(32位整形数)} 	// e.g. {"code":0, "uid":20000000}

请求失败返回
{"code":非0错误代码, "error": "错误信息"}	// e.g. {"code":1, "error": "凭证过期,请重新登录"}

请注意: code返回非0的情况,游戏服务器需要 禁止客户端继续登录, 客户端需要 退出游戏 或者 执行SDK “切换账号” 操作

充值平台服务器回调

需要游戏开发方提供游戏服务器充值的接口.


充值平台向游戏服务器充值接口发起 POST 请求

http://游戏服务器域名/充值接口

POST 通知数据 JSON 类型

data    	通知数据，字符串类型
sign         	请求验证串

实例: {"data": "{\"productid\":\"......\"}","sign":"......"}

sign 充值票据验证算法


算法生成的哈希值(小写)
md5(data + "_" + AppKey)

data数据结构

data 字符串进行 json_decode 可获得以下数据

productid

产品标识,作为充值依据

字符串

uid

玩家的唯一标识

整形数

order

本次充值在平台上的订单号

字符串

transactionid

商店订单号(由Apple, Google, Alipay, 微信等平台提供)

字符串

srvid

游戏服务器ID

字符串

nonce

充值透传参数(可选)

字符串

paytype

支付方式

apple	iOS充值
googleplay	Google商店充值
alipay	支付宝
wechat	微信
web	其它第三方充值
benefits	内部福利
betareturns	返利(仅赠送玩家未真实充值)

字符串

expires_date_ms

订阅过期时间戳(毫秒) 仅续订充值项有效

整形数

is_free_trial

是否免费试用 仅续订充值项有效

布尔型

游戏服务器充值接口返回值协议

POST 请求收到非 HTTP response status code 200 返回,判定为请求失败. 响应body中可返回任意信息

注意

对于充值失败的订单服务器有重跑机制，一般每5分钟会对充值状态为待充的订单进行重新请求，处理为成功状态，若超过5分钟订单还未执行成功请与运营同学联系。

CURL 回调实例

此CURL测试用 APPKEY: d5678067743c88ad707566749d3171cb


curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"data":"{\"srvid\":\"1\",\"uid\":1329632,\"order\":\"S_A17186305243341197795\",\"productid\":\"com.playcomet.pnsdk.demo.sku.01\",\"nonce\":\"\",\"paytype\":\"apple\",\"transactionid\":\"2000000630508478\",\"is_sandbox\":true,\"is_autofill\":false,\"price\":100,\"currency\":\"USD\",\"user_ip\":\"103.100.176.109\",\"quantity\":1}","sign":"d86579567ef970e5f057fb3b5ec85371"}' http://游戏服务器域名/充值接口


md5('{"srvid":"1","uid":1329632,"order":"S_A17186305243341197795","productid":"com.playcomet.pnsdk.demo.sku.01","nonce":"","paytype":"apple","transactionid":"2000000630508478","is_sandbox":true,"is_autofill":false,"price":100,"currency":"USD","user_ip":"103.100.176.109","quantity":1}_d5678067743c88ad707566749d3171cb') = d86579567ef970e5f057fb3b5ec85371

由于SDK无法进行准确的在线数据统计，这里提供服务端在线数据统计接口。游戏服务端可以每隔4分钟自行统计在线人数，通过接口发送到SDK服务器，平台进行数据汇总和展现。


    接口：        https://se.17995api.net/rest/v2/online

    方法：        POST
    格式：        json
    必须头信息：   Content-Type: application/json

请求内容：

参数名	参数类型	参数说明
identifier	string	在线统计Key,参数可以在提供的对接说明文档中找到
online	整形数	在线人数
timestamp	整形数	当前统计数据的时间戳(秒)，会按照自然1分钟进行数据对齐

示例


{
	"identifier":"aabbcc123",
	"online":123,
	"timestamp":1489739590
}

成功判断：返回的HTTP Code为200认为发送成功，否则认为失败

充值平台订阅通知

仅游戏存在订阅充值项的情况下,需要游戏服务器提供此订阅通知接口.


充值平台向游戏服务器订阅通知接口发起 POST 请求

http://游戏服务器域名/通知接口

POST 通知数据 JSON 类型

data    	通知数据，字符串类型
sign         	请求验证串

实例: {"data": "{\"productid\":\"......\"}","sign":"......"}

sign 数据验证算法


算法生成的哈希值(小写)
md5(data + "_" + AppKey)

data数据结构

data 字符串进行 json_decode 可获得以下数据

productid	产品标识	字符串
uid	玩家的唯一标识	整形数
srvid	游戏服务器ID	字符串
order	首次订阅原始平台订单号	字符串
nonce	首次订阅原始订单透传参数	字符串
expires_date_ms	订阅过期时间戳(毫秒)	整形数

返回值协议

POST 请求收到非 HTTP response status code 200 返回,判定为请求失败. 响应body中可返回任意信息

注意

请求失败时,在每间隔1小时回调一次订阅通知,最多尝试3次

此功能非必须,请与我方营运沟通确认

游戏服务器可以通过此接口,向全体用户或者指定用户发送消息推送.



接口：        https://push.17995api.net/firebase/notify?sign=[请求验证串]
方法：        POST
格式：        json
必须头信息：   Content-Type: text/plain

POST请求内容：

参数名	参数类型	参数说明
appid	string	SDK APPID
title	string	消息标题,可为空字符串必须为UTF-8
body	string	消息内容,不可为空字符串必须为UTF-8
image	string	展示图片网络地址,可为空字符串
ts	int	当前时间戳误差不得超过10分钟
to	array/string	推送目标参数值为 "ALL" 时,对全体用户推送信息为用户ID数组时 [uid1, uid2, ...] ,对特定用户发送信息注意:一次最多500个用户
label	string	分析标签，格式为：^[a-zA-Z0-9-_.~%]{1,50}$

GET请求参数：

sign 验证算法


    算法生成的哈希值(小写)
    md5(POST 内容 + AppKey)

示例


https://push.17995api.net/firebase/notify?sign=4deda4c253999d03b41587ac7d8040a3

POST 内容
{"title":"消息标题","body":"消息内容","image":"","appid":2000001,"to":[300095288,300095289],"ts":1616062391}

sign算法
md5(`{"title":"消息标题","body":"消息内容","image":"","appid":2000001,"to":[300095288,300095289],"ts":1616062391}` + `c4f66848841b1c5af83ae12f6f3273a9`) = 4deda4c253999d03b41587ac7d8040a3

使用场景示例

行为	发送方	接收方
好友召回	玩家游戏内点击好友召回按钮,即向3日未上线的好友发送召回推送	您的好友[某某]邀请您回到游戏,快来和小伙伴一起并肩作战.
团战提醒	会长在游戏内提醒成员参加团战	会长[某某]提醒您,今日[20:00]准时参加团战.
成员召回	公会盟主在游戏内召回公会成员,即向3日未上线的公会成员发送召回推送	你的盟主（盟友）[某某]邀请你一起并肩作战.

以上为示例文本,具体需求和多语言文本由我方营运提供详细文档

退款通知

通知游戏玩家退款


充值平台向游戏服务器接口发起 GET 请求

http://游戏服务器域名/退款通知接口

GET 参数

orderid          订单号
serverid         游戏服务器ID
nonce            充值创建订单时的nonce参数
notify_type      固定值 REFUND
sign             签名 md5('REFUND_' + orderid + '_' + serverid + '_' + nonce + appkey)

接口返回值协议

收到非 HTTP response status code 200 返回,判定为请求失败. 响应body中可返回任意信息

游戏角色查询（单服查询）

需要游戏开发方提供游戏角色查询的接口.


充值平台向游戏服务器接口发起 GET 请求

http://游戏服务器域名/角色查询接口

GET 参数

uid          玩家的唯一标识
srvid        游戏服务器ID
sign         请求验证串

sign 充值票据验证算法


算法生成的哈希值(小写)
md5(uid + "_" srvid + "_" + AppKey)

返回JSON数据格式


    {
        "code":0,
        "msg": "成功",
        "data":[{
            "roleid":"1001",
            "rolename":"abc",
            "level":1
        },
        {
            "roleid":"1002",
            "rolename":"abc2",
            "level":1
        }]
    }

游戏角色查询（滚服查询）

需要游戏开发方提供游戏角色查询的接口，一次性返回用户所有服务器和角色列表


充值平台向游戏服务器接口发起 GET 请求

http://游戏服务器域名/角色查询接口

GET 参数

uid          玩家的唯一标识
sign         请求验证串

sign 充值票据验证算法


算法生成的哈希值(小写)
md5(uid + "_"  + AppKey)

返回JSON数据格式


    {
        "code":0,
        "msg": "成功",
        "data":[
        {
            "srvid":"1",
            "roleid":"1001",
            "rolename":"abc",
            "level":1
        },
        {
            "srvid":"2",
            "roleid":"2001",
            "rolename":"abc2",
            "level":1
        }]
    }

查询商品列表

网页充值专用接口，需要游戏开发方提供游戏玩家可以购买的所有商品列表（包括常规道具和限时礼包, 不能购买的商品不要返回）


充值平台向游戏服务器接口发起 GET 请求

http://游戏服务器域名/查询商品列表接口

GET 参数

uid          玩家的唯一标识
roleid       角色id
srvid        游戏服务器ID

返回JSON数据格式


    // 查询成功返回
    {
        "code":0,
        "msg": "成功",
        "data":[
        {
            "productID":"1001",   // 产品项id
            "nonce":"abc"         // 透传信息(可选)，如果需要可以通过充值回调接口透传给游戏服务器
        }]
    }
    // 查询失败返回
    // 1. 服务器停服维护 (必须跟客户端拦截保持一致)
    {
        "code":101,
        "msg": "服务器停服维护"
    }

生成充值透传参数

网页第三方充值专用，网页充值独立在游戏外，如果游戏充值必须使用透传参数，就需要提供生成充值透传参数接口，充值平台调用获取透传参数以后传递给游戏


充值平台向游戏服务器接口发起 POST 请求

http://游戏服务器域名/生成充值透传参数接口

POST 请求数据 JSON 类型

data    	请求数据，字符串类型
sign         	请求验证串

实例: {"data": "{\"productid\":\"......\"}","sign":"......"}

sign 数据验证算法


算法生成的哈希值(小写)
md5(data + "_" + AppKey)

data数据结构

data 字符串进行 json_decode 可获得以下数据

productid	产品标识	字符串
uid	玩家的唯一标识	整形数
srvid	游戏服务器ID	字符串
roleid	角色id	字符串
product_nonce	产品项透传参数（通过查询产品列表获取），可选值	字符串

返回值协议

成功返回： {"code":0, "nonce": 充值透传参数, 充值回调游戏服务器需要带上这个参数}

失败返回： {"code":-1, "msg": ""}

SDK服务器对接手册

国内版本

服务器对接

登录验证

充值平台服务器回调

sign 充值票据验证算法

data数据结构

游戏服务器充值接口返回值协议

注意

CURL 回调实例

在线数据统计接口

请求内容：

示例

充值平台订阅通知

sign 数据验证算法

data数据结构

返回值协议

注意

推送接口

POST请求内容：

GET请求参数：

示例

使用场景示例

退款通知

接口返回值协议

游戏角色查询（单服查询）

sign 充值票据验证算法

返回JSON数据格式

游戏角色查询（滚服查询）

sign 充值票据验证算法

返回JSON数据格式

查询商品列表

返回JSON数据格式

生成充值透传参数

sign 数据验证算法

data数据结构

返回值协议