Skip to content

Z
zw_game_sdk
提交 28f72ede 作者: 张梦磊
操作

新增存储数据接口

上级 aab71575
正在显示 包含 156 行增加 和 78 行删除
H5_SDK对接说明.md
# H5 SDK 对接文档-v1.0
# H5 SDK 对接文档-v1.0
......@@ -55,19 +55,20 @@
        返回参数
        请求示例
3.[H5 SDK接入](#sec3)
    3.1 [配置导入H5 SDK](#sec3.1)
3.[H5 SDK 接入](#sec3)
    3.1 [配置导入 H5 SDK](#sec3.1)
        说明
        SDK地址
        SDK 地址
        必要参数
        导入示例
    3.2 [H5 SDK初始化](#sec3.2)
    3.2 [H5 SDK 初始化](#sec3.2)
        说明
......@@ -101,7 +102,7 @@
        返回参数
        EVENT枚举
        EVENT 枚举
        示例
......@@ -129,38 +130,56 @@
        示例
    3.8 [SDK 设置存储数据](#sec3.8)
        接口说明
        调用方式
        请求参数
        返回参数
        示例
    3.9 [SDK 读取存储数据](#sec3.9)
        接口说明
        调用方式
        请求参数
        返回参数
        示例
## 1. 接入说明<a name="sec1"></a>
### 1.1 术语表<a name="sec1.1"></a>
> | 名称 | 说明 |
> | ---------- | ------------------------------------------------------------ |
> | ----------- | --------------------------------------------------------------------------------------------------- |
> | CP | 游戏研发商。 |
> | H5_SDK | 由平台方提供给游戏研发商，用于游戏客户端接入平台登录，支付。 |
> | SDK服务 | 由平台方开发，用于完成SDK的登录，支付流程，承接游戏服务端的数据。 |
> | SDK 服务 | 由平台方开发，用于完成 SDK 的登录，支付流程，承接游戏服务端的数据。 |
> | 游戏服务 | 游戏研发商开发，为游戏提供服务。 |
> | 游戏客户端 | 游戏研发方商开发的网页版游戏。 |
> | 支付服务 | 由平台方调用支付服务，包括微信支付，支付宝支付等 |
> | 游戏盒子 | 由平台方开发的游戏总入口，可以实现游戏登陆，支付，切换等；H5游戏以iframe的形式在游戏盒子中运行。 |
> | H5游戏入口 | 由CP方提供，进入H5游戏的入口链接。 |
> | 游戏盒子 | 由平台方开发的游戏总入口，可以实现游戏登陆，支付，切换等；H5 游戏以 iframe 的形式在游戏盒子中运行。 |
> | H5 游戏入口 | 由 CP 方提供，进入 H5 游戏的入口链接。 |
### 1.2 数据字典<a name="sec1.2"></a>
> | 名称 | 说明 |
> | ----------- | ---------------------------------- |
> | ----------- | -------------------------------------------------- |
> | player_id | 用户在平台的一个游戏中的唯一标识。 |
> | user_token | 用户在平台登录的会话标识。 |
> | game_id | 游戏在平台的唯一标识。 |
> | game_secret | 平台方提供，游戏签名秘钥。 |
> | cp_order_id | 游戏研发商订单唯一标识 |
> | order_id | 平台方订单唯一标识，与cp_order_id一一对应 |
> | h5_game_url | H5游戏入口,由CP方提供，进入H5游戏的入口链接。 |
> | order_id | 平台方订单唯一标识，与 cp_order_id 一一对应 |
> | h5_game_url | H5 游戏入口,由 CP 方提供，进入 H5 游戏的入口链接。 |
### 1.3 链接登录<a name="sec1.3"></a>
......@@ -175,7 +194,6 @@ sequenceDiagram
游戏服务-->游戏客户端:验证结果
```
### 1.4 主动登录<a name="sec1.4"></a>
```mermaid
......@@ -209,8 +227,6 @@ sequenceDiagram
游戏客户端-->>玩家:发货
```
## 2. 服务端接入<a name="sec2"></a>
### 2.1 接口规则<a name="sec2.1"></a>
......@@ -244,11 +260,11 @@ sequenceDiagram
> **签名秘钥**
>
> game_secret 为16位字符串，由 SDK 对接时提供，每一个小游戏单独提供一个 game_secret
> game_secret 为 16 位字符串，由 SDK 对接时提供，每一个小游戏单独提供一个 game_secret
> **签名串**
>
> 请求参数（去除sign）通过参数名作升序排序；如果参数值是一个对象，需要将该对象通过参数名升序排序后转换为json字符串；将排好序的参数与game_secret以一下格式进行字符串拼接(game_secret放在最后)
> 请求参数（去除 sign）通过参数名作升序排序；如果参数值是一个对象，需要将该对象通过参数名升序排序后转换为 json 字符串；将排好序的参数与 game_secret 以一下格式进行字符串拼接(game_secret 放在最后)
>
> key1=value1&key2=value2&key3=value3&game_secret=secret
......@@ -260,11 +276,9 @@ sequenceDiagram
> ##### 注意
>
> <u>如果参数值是一个对象，需要将该对象通过参数名升序排序后转换为json字符串；</u>
> <u>如果参数值是一个对象，需要将该对象通过参数名升序排序后转换为 json 字符串；</u>
>
> <u>转换json注意不要对中文进行转义</u>
> <u>转换 json 注意不要对中文进行转义</u>
##### 签名示例
......@@ -289,7 +303,7 @@ sequenceDiagram
##### 接口说明
> 小游戏通过 SDK 获得 用户user_token, 游戏服务端需要在用户登录游戏成功后调用登录验证接口，验证user_token是否为有效登录用户会话，SDK 服务端需要通过该接口判断用户是否登录游戏服务 。
> 小游戏通过 SDK 获得 用户 user_token, 游戏服务端需要在用户登录游戏成功后调用登录验证接口，验证 user_token 是否为有效登录用户会话，SDK 服务端需要通过该接口判断用户是否登录游戏服务 。
>
> 注意：该接口有调用频率限制，建议游戏服务端在完成用户登录后调用该接口；
>
......@@ -304,16 +318,16 @@ sequenceDiagram
> **Headers**:
>
> | 参数 | 必选 | 参数值 | 说明 |
> | ------------ | ---- | ---------------- | ----------------------------------- |
> | ------------ | ---- | ---------------- | ------------------------------------ |
> | Content-Type | true | application/json | |
> | User-Token | true | | 小游戏登录后由 SDK 返回的user_token |
> | User-Token | true | | 小游戏登录后由 SDK 返回的 user_token |
> **Body**:
>
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | --------- | ---- | ------ | ------ | ---------------------------------- |
> | game_id | true | Int | - | 游戏接入时分配的游戏ID(建议从user_token中取，#后面的数字即为game_id)|
> | player_id | true | Int | - | 小游戏登录后由 SDK 返回的player_id |
> | --------- | ---- | ------ | ------ | ------------------------------------------------------------------------ |
> | game_id | true | Int | - | 游戏接入时分配的游戏 ID(建议从 user_token 中取，#后面的数字即为 game_id) |
> | player_id | true | Int | - | 小游戏登录后由 SDK 返回的 player_id |
> | sign | true | String | - | 参数签名 |
##### 返回参数
......@@ -323,7 +337,6 @@ sequenceDiagram
> | status_code | true | Int | - | 状态码 |
> | msg | true | STRING | - | 返回信息 |
> | data | false | OBJECT | [] | 返回数据（空） |
>
##### 请求示例
......@@ -403,9 +416,9 @@ sequenceDiagram
> **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;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 | | 商品总价(分) |
......@@ -413,10 +426,9 @@ sequenceDiagram
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;product_cnt | true | String | - | 商品数量 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;pay_time | true | Timestamp | - | 支付时间（时间戳,到秒） |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ext | true | String | - | CP 自定义扩展字段，透传信息 |
> | game_id | true | String | - | 游戏接入时分配的游戏ID |
> | player_id | true | String | - | 游戏接入时分配的游戏ID |
> | sign | true | String | - | 签名（签名规则参照2.1签名规则，签名的key由SDK提供） |
>
> | game_id | true | String | - | 游戏接入时分配的游戏 ID |
> | player_id | true | String | - | 游戏接入时分配的游戏 ID |
> | sign | true | String | - | 签名（签名规则参照 2.1 签名规则，签名的 key 由 SDK 提供） |
##### 返回参数
......@@ -498,31 +510,28 @@ payNotify();
## 3. H5 SDK 接入<a name="sec3"></a>
### 3.1 配置导入H5 SDK<a name="sec3.1"></a>
### 3.1 配置导入 H5 SDK<a name="sec3.1"></a>
##### 说明
> 游戏客户端通过引入外部js的方式，导入H5 SDK
> 游戏客户端通过引入外部 js 的方式，导入 H5 SDK
##### SDK地址
##### SDK 地址
> https://sdk.zwnet.cn/h5_sdk.js?v=1.0
##### 必要参数
> | 参数 | 说明 |
> | ----------- | -------------------------------- |
> | ----------- | ---------------------------------- |
> | game_id | 游戏唯一标识，由平台方提供 |
> | h5_game_url | 需要由CP方提供进入游戏的入口链接 |
> | h5_game_url | 需要由 CP 方提供进入游戏的入口链接 |
##### 导入示例
> ```javascript
> <script src="https://sdk.zwnet.cn/h5_sdk.js?v=1.0"></script>
> <script src='https://sdk.zwnet.cn/h5_sdk.js?v=1.1'></script>
> ```
>
### 3.2 H5 SDK 初始化<a name="sec3.2"></a>
......@@ -530,7 +539,7 @@ payNotify();
##### 说明
> 游戏客户端需要在一开始初始化H5 SDK的对象，并注册角色上报(updateRole)、下单(createOrder)、订单查询（checkOrder）的回调通知；游戏客户端通过回调通知获得角色上报(updateRole)、下单(createOrder)、订单查询（checkOrder）的结果。
> 游戏客户端需要在一开始初始化 H5 SDK 的对象，并注册角色上报(updateRole)、下单(createOrder)、订单查询（checkOrder）的回调通知；游戏客户端通过回调通知获得角色上报(updateRole)、下单(createOrder)、订单查询（checkOrder）的结果。
##### 调用示例
......@@ -550,12 +559,15 @@ payNotify();
> },
> checkOrderCallBack: (e) => {
> //处理订单查询的结果
> },
> getLocalStorageCallBack: (e) => {
> //获取读取的结果
> },
> setLocalStorageCallBack: (e) => {
> //获取设置的结果
> }
> })
> ```
>
### 3.3 链接登录<a name="sec3.3"></a>
......@@ -566,17 +578,14 @@ payNotify();
##### 链接参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :--------- | :--- | :----- | :----- | :------------------------------------------ |
> | :--------- | :--- | :----- | :----- | :------------------------------------------- |
> | game_id | true | Int | - | 游戏在平台的唯一标识。 |
> | player_id | true | Int | - | 用户在平台的一个游戏中的唯一标识。 |
> | user_token | true | String | - | 用户登录后获取的token，用于验证用户是否登录 |
> | user_token | true | String | - | 用户登录后获取的 token，用于验证用户是否登录 |
##### 示例
> 假设由CP方提供的h5_game_url为https://xxx.game.com，携带参数后最终地址为https://xxx.game.com?game_id=108&player_id=19902&user_token=O4T8Ua47Y7TtIuwcY2jbM71rZnTcg457Y2MzZTU4MjU0OWE5ZGQxOTg3YmYO0O0O
> 假设由 CP 方提供的 h5_game_url 为https://xxx.game.com，携带参数后最终地址为https://xxx.game.com?game_id=108&player_id=19902&user_token=O4T8Ua47Y7TtIuwcY2jbM71rZnTcg457Y2MzZTU4MjU0OWE5ZGQxOTg3YmYO0O0O
### 3.4 主动登录<a name="sec3.3"></a>
......@@ -591,16 +600,12 @@ payNotify();
> ```javascript
> sdk.reLogin()
> ```
>
##### 示例
> ```javascript
> sdk.reLogin()
> ```
>
### 3.5 SDK 角色上报<a name="sec3.5"></a>
......@@ -619,16 +624,16 @@ sdk.updateRole(config:Object)
##### 请求参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :---------------------------------------------------------- | :---- | :----- | :----- | :----------- |
> | :---------------------------------------------------------- | :---- | :----- | :----- | :---------------------- |
> | role | true | Object | - | 角色信息 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;event | true | String | other | 事件类型 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;server_id | true | String | - | 区服ID |
> | &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;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;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 | 本次在线时长 |
......@@ -644,7 +649,7 @@ sdk.updateRole(config:Object)
> | status_code | true | Int | - | 状态码 |
> | msg | true | STRING | - | 返回信息 |
##### EVENT枚举
##### EVENT 枚举
> | EVENT | 说明 |
> | -------- | -------- |
......@@ -670,14 +675,11 @@ sdk.updateRole(config:Object)
> role_vip: '7',
> combat_num: '100',
> online_time: '10',
> reiki_num: '10',
> reiki_num: '10'
> }
> })
> //回调通知需要在初始化时注册
> ```
>
### 3.6 SDK 下单<a name="sec3.6"></a>
......@@ -685,7 +687,7 @@ sdk.updateRole(config:Object)
##### 接口说明
> 用户在充值后，游戏客户端需要调用sdk下单方法，需在登录成功后调用此方法；改方法会自动拉起支付。
> 用户在充值后，游戏客户端需要调用 sdk 下单方法，需在登录成功后调用此方法；改方法会自动拉起支付。
##### 调用方式
......@@ -696,7 +698,7 @@ zwsdk.createOrder(config:Object)
##### 请求参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :----------------------------------------------------------- | :---- | :----- | :------- | :----------------------------------------------------------- |
> | :------------------------------------------------------------ | :---- | :----- | :------- | :--------------------------------------------------------------------------------------------------- |
> | order | true | Object | - | 订单相关 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;cp_order_id | true | String | - | 游戏传入的外部订单号，服务器会根据这个订单号生成对应的平台订单号，请保证每笔订单传入的订单号的唯一性 |
> | &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;product_price | true | String | - | 商品价格（单价，单位：分） |
......@@ -720,7 +722,7 @@ zwsdk.createOrder(config:Object)
##### 返回参数
> | 参数 | 类型 | 说明 |
> | :----------------------------------------------------------- | :----- | :------------------------- |
> | :------------------------------------------------------------------------------------------------------- | :----- | :------------------------- |
> | status_code | String | 返回状态 |
> | msg | String | 返回信息 |
> | data | Object | 用户数据 |
......@@ -739,7 +741,7 @@ sdk.createOrder({
product_cnt: '1',
product_name: '元宝',
product_desc: '充值元宝',
ext: '',
ext: ''
},
role: {
server_id: '100001',
......@@ -751,7 +753,7 @@ sdk.createOrder({
combat_num: '100',
online_time: '10'
}
})
})
//回调通知需要在初始化时注册
```
......@@ -779,7 +781,7 @@ sdk.checkOrder(config:Object)
##### 返回参数
> | 参数 | 类型 | 说明 |
> | :----------------------------------------------------------- | :----- | :--------------------------------- |
> | :-------------------------------------------------------------------------------------------------------------- | :----- | :--------------------------------- |
> | status_code | String | 返回状态 |
> | msg | String | 返回信息 |
> | data | Object | 用户数据 |
......@@ -795,6 +797,82 @@ sdk.checkOrder({
order: {
order_id: 'g1635306419-9FA13A0B-EDA1-1D94'
}
})
})
//回调通知需要在初始化时注册
```
### 3.8 SDK 设置存储数据<a name="sec3.8"></a>
---
##### 说明
> 设置 localStorage ,结果在 setLocalStorageCallBack() 返回
##### 调用方式
```javascript
sdk.setLocalStorage(config:Object)
```
##### 请求参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :---- | :--- | :----- | :----- | :---- |
> | key | true | String | - | key |
> | value | true | String | - | value |
##### 返回参数
> | 参数 | 类型 | 说明 |
> | :---------- | :----- | :------- |
> | status_code | String | 返回状态 |
> | msg | String | 返回信息 |
##### 示例
```javascript
sdk.setLocalStorage({
key: 'testKey',
value: 'test'
})
//
```
### 3.9 SDK 读取存储数据<a name="sec3.9"></a>
---
##### 说明
> 读取 localStorage ,结果在 getLocalStorageCallBack() 返回
##### 调用方式
```javascript
sdk.getLocalStorage(config:Object)
```
##### 请求参数
> | 参数 | 必选 | 类型 | 默认值 | 说明 |
> | :--- | :--- | :----- | :----- | :--- |
> | key | true | String | - | key |
##### 返回参数
> | 参数 | 类型 | 说明 |
> | :---------- | :----- | :------- |
> | status_code | String | 返回状态 |
> | msg | String | 返回信息 |
> | value | String | value |
##### 示例
```javascript
sdk.getLocalStorage({
key: 'testKey'
})
//
```
Markdown 格式
0% 或
您添加了 0 人 到此讨论。请谨慎行事。
请先完成此评论的编辑！
请 注册 或者 后发表评论