Skip to content

Z
zw_game_sdk
提交 1817f38f 作者: yyc
操作

服务端接口文档

上级 7562a255
正在显示 包含 400 行增加 和 0 行删除
overseas/服务端接口说明.md 0 → 100644
# 服务端接口说明-v1.0.0
# 服务端接口说明-v1.0.0
### 目录
1.[接入说明](#sec1)
    1.1 [术语表](#sec1.1)
    1.2 [数据字典](#sec1.2)
2.[服务端接口](#sec1)
    2.1 [接口规则](#sec2.1)
        请求域名
        请求方式
        请求格式
        返回格式
        状态说明
        签名规则
        签名示例
    2.2 [角色上报](#sec2.2)
        接口说明
        接口地址
        请求参数
        返回参数
        请求示例
    2.3 [支付通知](#sec2.3)
        接口说明
        接口地址
        请求参数
        返回参数
        请求示例
## 1. 接入说明<a name="sec1"></a>
### 1.1 术语表<a name="sec1.1"></a>
> | 名称 | 说明 |
> | ---------- | ------------------------------------------------------------ |
> | CP | 游戏研发商。 |
> | SDK | 由平台方提供给游戏研发商，用于游戏接入平台登录，支付。 |
> | SDK 服务 | 由平台方开发，用于完成 SDK 的登录，支付流程，承接游戏服务端的数据。 |
> | 游戏服务 | 游戏研发商开发，为游戏提供服务。 |
> | 安卓游戏 | 游戏研发方商开发的安卓游戏。 |
> | iOS游戏 | 游戏研发商开发的iOS游戏一般情况系与安卓同游同服 |
> | 支付服务 | 由平台方调用支付服务，包括google apple 支付等 |
### 1.2 数据字典<a name="sec1.2"></a>
> | 名称 | 说明 |
> | ----------- | ------------------------------------------------- |
> | player_id | 用户在平台的一个游戏中的唯一标识。 |
> | user_token | 用户在平台登录的会话标识。 |
> | main_game_id| 游戏在平台的父级唯一标识。 |
> | game_id | 游戏在平台的子级唯一标识。 |
> | game_secret | 平台方提供，游戏签名秘钥。 |
> | cp_order_id | 游戏研发商订单唯一标识 |
> | order_id | 平台方提供，订单唯一标识，与 cp_order_id 一一对应 |
## 2. 服务端接入<a name="sec2"></a>
### 2.1 接口规则<a name="sec2.1"></a>
##### 请求域名
> 【HTTPS】zyou.wozhangwan.com/api
##### 请求方式
> 【POST】
##### 请求格式
> 【JSON】
##### 返回格式
> 【JSON】
##### 状态说明
| 状态码 | 说明 |
| ------ | -------- |
| 1 | 成功 |
| -1 | 错误 |
| -100 | 未登录 |
| -422 | 参数错误 |
##### 签名规则
> **签名秘钥**
>
> game_secret 为 16 位字符串，由 SDK 对接时提供，每一个游戏单独提供一个 game_secret
> **签名串**
>
> 请求参数（去除 sign）通过参数名作升序排序；如果参数值是一个对象，需要将该队形通过参数名升序排序后转换为 json 字符串；将排好序的参数与 game_secret 以一下格式进行字符串拼接(game_secret 放在最后)
>
> key1=value1&key2=value2&key3=value3&game_secret=secret
> **签名算法**
>
> 【md5】
>
> sign = md5（签名串）
> ##### 注意
>
> <u>如果参数值是一个对象，需要将该对象通过参数名升序排序后转换为 json 字符串；</u>
>
> <u>转换 json 注意不要对中文进行转义</u>
##### 签名示例
```php
<php?
$gameSecret = "game_secret";
$params = ["player_id" => 1245, "game_id" => 14];
$signStr = '';
ksort($params, SORT_REGULAR);
foreach ($params as $key => $val) {
if (is_array($val)) {
ksrot($val, SORT_REGULAR); //对对象参数进行排序
$val = json_encode($val, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
$signStr .= $key . '=' . $val . '&';
}
$signStr .= 'game_secret=' . $gameSecret;
$sign = md5($signStr);
```
### 2.2 角色上报<a name="sec2.2"></a>
##### 接口说明
> 游戏方通过服务端上报游戏角色信息到 SDK 服务器；
>
> 接口需要进行签名，签名方法详见[接口规则](#sec2.1)
##### 接口地址
> 【POST】/server/role/report
##### 请求参数
> **Headers**:
>
> | 参数 | 必选 | 参数值 | 说明 |
> | ------------ | ---- | ---------------- | ---- |
> | Content-Type | true | application/json | |
> **Body:**
>
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :----------------------------------------------------------- | :---- | :----- | :----- | :--------------------------------------------------------- |
> | main_game_id | true | Int | - | 掌游提供的父级唯一标识 |
> | player_id | true | Int | - | 游戏登录后由 SDK 返回的player_id |
> | os | false | String | - | 操作系统 |
> | sign | true | String | - | 签名 |
> | role | true | Object | - | 角色信息 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;event | true | String | - | 事件类型 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;server_id | true | String | - | 区服ID |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;server_name | true | String | - | 区服名称 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cp_role_id | true | String | - | 游戏方角色ID |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;role_name | true | String | - | 游戏角色名称 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;role_level | true | Int | - | 角色等级 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cp_account | false | String | - | cp账号 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;role_vip | false | Int | 0 | 角色VIP等级 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;combat_num | false | Int | 0 | 角色战力 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;reiki_num | false | Int | 0 | 角色灵符值 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;online_time | false | Int | 0 | 本次在线时长 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;attack | false | Int | 0 | 攻击力 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;profession | false | String | - | 职业 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gang_name | false | String | - | 帮会(行会)名称 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;trans_level | false | Int | 0 | 转生等级 |
> | device_brand | false | String | - | 设备品牌 |
> | device_number | false | String | - | 设备型号 |
> | deviceId | false | String | - | 设备id |
##### 返回参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | ----------- | ---- | ------ | ------ | -------- |
> | status_code | true | Int | - | 状态码 |
> | msg | true | STRING | - | 返回信息 |
> | data | | | | |
##### EVENT枚举
> | EVENT | 说明 |
> | -------- | -------- |
> | create | 创建角色 |
> | online | 角色上线 |
> | offline | 角色下线 |
> | level_up | 角色升级 |
> | delete | 删除角色 |
> | recharge | 角色充值 |
> | other | 其他 |
##### 请求示例
```php
<php?
public function report(){
$host = 'https://zyou.wozhangwan.com/api';
$checkLoginUrl = '/mini_sdk/role/severReport';
$url = $host.$checkLoginUrl;
$gameSecret = "game_secret";
$body = ["game_id" => 121, //角色当前SDK方游戏ID
"player_id" => 1245,//游戏登录后由 SDK 返回的player_id
"type" => 1,//游戏角色操作环境，1：H5网页端，2：小游戏端，3：android游戏
"os" => "windows",//游戏操作系统：windows,android,ios
"role" =>[
"event" => 1,//角色事件类型
"server_id" =>1,//游戏区服ID
"server_name" => "区服一",//游戏区服名称
"cp_role_id" => "roleId",//游戏中角色唯一ID
"role_name" => "角色名称",//游戏角色名称
"role_level" => "11",//角色等级
"role_vip" => "0",//角色vip等级
"combat_num" => "0",//角色战力值
"online_time" => "0"//角色在线时长，单位为秒
]
];
$body["sign"] = makeSign($body, $gameSecret);
$headers = ["Content-Type:application/json"];
$response = curl_post($url, $body, $hearders);
}
public function makeSign($params,$gameSecret){
$signStr = '';
ksort($params, SORT_REGULAR);
foreach ($params as $key => $val) {
if (is_array($val)) {
ksrot($val, SORT_REGULAR); //数组对象参数进行排序
$val = json_encode($val, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR);
}
$signStr .= $key . '=' . $val . '&';
}
$signStr .= 'game_secret=' . $gameSecret;
return md5($signStr);
}
public function curl_post($url, $body, $headers){
//初始化
$curl = curl_init ( ) ;
//设置抓取的url
curl_setopt ( $curl , CURLOPT_URL , $url) ;
//设置头文件的信息作为数据流输出
curl_setopt ( $curl , CURLOPT_HEADER , 1 ) ;
//设置获取的信息以文件流的形式返回，而不是直接输出。
curl_setopt ( $curl , CURLOPT_RETURNTRANSFER , 1 ) ;
//设置post方式提交
curl_setopt ( $curl , CURLOPT_POST , 1 ) ;
//设置post参数
curl_setopt ( $curl , CURLOPT_POSTFIELDS , json_encode($body) ) ;
//设置请求头
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
//执行命令
$data = curl_exec ( $curl ) ;
//关闭URL请求
curl_close ( $curl ) ;
//显示获得的数据
return json_decode($data, true);
}
```
### 2.3 支付通知<a name="sec2.3"></a>
##### 接口说明
> 需要游戏服务端完成该接口，接收平台充值成功的信息。
##### 接口地址
> 【POST】充值结果通知地址，由 CP 方提供
##### 通知参数
> **Headers**:
>
> | 参数 | 必选 | 参数值 | 说明 |
> | ------------ | ---- | ---------------- | ---- |
> | Content-Type | true | application/json | |
> | User-Token | | | |
> **Body:**
>
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :------------------------------------------------------------ | :--- | :----- | :----- | :------------------------------------------------------------------------------------------------------- |
> | order | true | Object | - | 订单相关 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;order_id | true | String | - | 平台订单 ID |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cp_order_id | true | String | - | 游戏传入的外部订单号，服务器会根据这个订单号生成对应的平台订单号，<br>请保证每笔订单传入的订单号的唯一性 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;product_price | true | String | - | 商品单价(分) |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;amount | true | String | | 商品总价(分) |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;product_id | true | String | - | 商品 ID |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;product_cnt | true | String | - | 商品数量 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pay_time | true | String | - | 支付时间（时间戳,到秒） |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ext | true | String | - | CP 自定义参数，透传信息 |
> | game_id | true | String | - | 游戏接入时分配的游戏 ID 【子级唯一】 |
> | player_id | true | String | - | 游戏接入登录返回的用户唯一标识 |
> | sign | true | String | - | 签名（签名规则参照 2.1 签名规则，签名的 key 由 SDK 提供） |
##### 返回参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | ----------- | ---- | ------ | ------ | -------- |
> | status_code | true | Int | - | 状态码 |
> | msg | true | STRING | - | 返回信息 |
> | data | | | | |
##### 注意
> 通知使用的参数格式均为字符串（String） 返回status_code = 1 为成功， 否则会重复通知三次
##### 请求示例
```php
function makeSign($params,$gameSecret){
$signStr = '';
ksort($params, SORT_REGULAR);
foreach ($params as $key => $val) {
if (is_array($val)) {
ksort($val, SORT_REGULAR);
$val = json_encode($val, JSON_UNESCAPED_UNICODE);
}
$signStr .= $key . '=' . $val . '&';
}
$signStr .= 'game_secret=' . $gameSecret;
return md5($signStr);
}
function curl_post($url, $body, $headers){
//初始化
$curl = curl_init ( );
//设置抓取的url
curl_setopt ( $curl, CURLOPT_URL , $url);
//设置头文件的信息作为数据流输出
curl_setopt ( $curl, CURLOPT_HEADER , 0 );
//设置获取的信息以文件流的形式返回，而不是直接输出。
curl_setopt ( $curl, CURLOPT_RETURNTRANSFER , 1 );
//设置post方式提交
curl_setopt ( $curl, CURLOPT_POST , 1 );
//设置post参数
curl_setopt ( $curl, CURLOPT_POSTFIELDS , json_encode($body) );
//设置请求头
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
//执行命令
$data = curl_exec ( $curl );
//关闭URL请求
curl_close ( $curl );
//显示获得的数据
return json_decode($data, true);
}
function payNotify(){
$payNotifyUrl = 'CP 方充值成功回调地址';
$gameSecret = "#替换为SDK方参数game_secret#";
$body = [
"player_id" => 990218,
"game_id" => 138,
"order"=>["amount"=>"800",
"cp_order_id"=>"1333066913427335168_101_990218_1",
"ext"=>"1333066913424879617",
"order_id"=>"g1641507637-CA7714D0-064D-D4BA",
"pay_time"=>"1641507647",
"product_cnt"=>"1",
"product_id"=>"101",
"product_price"=>"800"
]
];
$body["sign"] = makeSign($body, $gameSecret);
$headers = ["Content-Type:application/json"];
$response = curl_post($payNotifyUrl, $body, $headers);
print_r($response);
}
payNotify();
```
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论