一、简介

此文档描述了使用SDK的CP（内容提供商）用到的与WINGSDK后台交付的所有接口的详细定义。
接口分两种：
1、WINGSDK后台实现，CP后台调用。
2、CP后台实现，WINGSDK后台调用。

名词说明：

二、登录

注：实线表示请求的发起，虚线表示请求的返回

登录流程说明：
1）SDK客户端封装了其它不同第三方登录平台，用户登录后，SDK会返回后台验证的参数
2）客户端去WINGSDK服务端获取在线token，服务端先去第三方登录平台验证accessToken，获取第三方用户信息，并返回对应的WINGSDK用户ID和token给客户端
3）客户端通过SDK API 获取token，userId，puserId,platform等用户信息，然后向游戏后台发送登录请求
4）游戏后台调用WINGSDK提供的接口验证用户登录，请求参数见下
5）如果是应用内登录，以上登录流程图可以将第三方登录平台当成CP服务端，CP需要提供验证用户帐号的接口供WINGSDK后台调用。

2.1 CP验证用户登录接口

接口说明：

输入参数说明：

返回格式

请求示例：

$ curl -s -XPOST -H ‘content-type:application/x-www-form-urlencoded’ ‘https://api.wingsdk.com/cpapi/v2/user/authorize.do’ -d ‘appId=39a59e6182b911eebb5a02c85f0429f5&osign=2df4b4da628ff9e9da8ade02d5f9bd94&token=30_o1hgud5ogc9CSlgwul4AEaFr8jS0g3sD’

2.2 WINGSDK后台验证CP用户登录信息接口（应用内登录）

登录验证流程图：

接口说明：

输入参数说明：

返回格式

三、支付流程

3.1 概述

要使用Wingsdk的支付功能，首先要在SDK后台添加商品列表以及要使用的第三方支付平台信息。每个支付平台的商品列表都是可以单独配置的。
Wingsdk支付过程中，对第三方支付平台的信息都做了屏蔽，也就是说，所有第三方支付平台以及对应的配置信息对CP来说都是透明的。CP在客户端使用的商品列表是wingsdk平台独有的商品Id，和第三方支付后台的商品Id的不一样，但是有映射关系（运营人员在SDK管理后台维护），即wingsdk商品Id+支付渠道标识可以确认一个第三方商品Id，用户选择某一个商品进行购买后，需要选择第三方支付渠道（google、apple等），wingsdk首先会使用wingsdk平台的商品id下订单，之后会使用对应的第三方商品id到第三方（google，apple等）进行支付。支付成功，Wingsdk通知CP发货也是使用Wingsdk的商品Id。

3.2 CP发货通知接口

该接口由移动平台定义，CP负责实现
发货接口调用说明
1.WINGSDK服务端系统订单在支付完成之后将实时通知到 CP 发货接口。

2.WINGSDK服务端系统通知 CP 发货时，若未接收到 CP 接口成功回复，该笔订单将重复通知 3次。

3.WINGSDK服务端系统在重复 3 次通知 CP 发货的过程中，若都未收到 CP 的成功回复，订单将进入后台轮询通知发货。每次轮询将有 3 次的通知；第一次轮询为订单新建之后的 15 分钟；之后每小时轮询通知一次； 24 小时之后隔日通知一次。

4.WINGSDK服务端系统收到 CP 接口返回 code=200 时将不再对该笔订单做重复通知。

5.WINGSDK服务端系统若对某笔订单重复通知，则 CP 需自行判断是否已经发货，若已发货则接
口直接返回 code=200，当作成功处理。

6.WINGSDK回调服务器的 IP 地址为 xx.xx.xx.xx，CP 可以考虑在回调接口中做该 IP 的白名单匹
配（可选）。不过 IP 地址可能存在变更，如有变更，将在SDK管理后台上另行通知

URL：http://****/deliver.do
支持Http Method：POST
返回信息格式：Json

输入参数说明：

返回结果说明:

3.3 发货结果异步回调接口（可选）

接口说明：

输入参数说明：

返回结果说明:

3.4 退款通知接口（可选）

该接口由移动平台定义，CP负责实现
退款通知接口调用说明
1.WINGSDK服务端每天定时任务查询第三方支付平台退款订单列表，目前只支持Google play

2.用于Google支付渠道的服务邮箱账号需拥有查看财务的权限。

3.WINGSDK服务端系统通知 CP退款订单时，若未接收到 CP 接口成功回复，该笔退款订单将重复通知5次。每隔30分钟通知一次

4.WINGSDK服务端系统收到 CP 接口返回 code=200 时将不再对该笔退款订单做重复通知。

5.WINGSDK服务端系统若对某笔退款订单重复通知，则 CP 需自行判断是否已经处理，若已处理则接口直接返回 code=200，当作成功处理。

6.WINGSDK回调服务器的 IP 地址为 xx.xx.xx.xx，CP可以考虑在回调接口中做该 IP 的白名单匹配（可选）。不过 IP 地址可能存在变更，如有变更，将在SDK管理后台上另行通知

URL：http://****/refund_notify.do
支持Http Method：POST
返回信息格式：Json

输入参数说明:

返回结果说明:

四、奖励通知

4.1 邀请奖励通知接口定义

输入参数说明：

返回结果说明:

4.2 视频广告奖励通知接口定义

接口说明：

输入参数说明：

返回结果说明(JSON格式):
失败返回错误码，请参照附录1的状态码说明表；

4.3 admob激励广告奖励通知接口定义

接口说明：

接口调用说明
连续通知3次，都失败则不再通知。

输入参数说明：

返回结果说明(JSON格式):
失败返回错误码，请参照附录1的状态码说明表；

4.4 礼包通知接口定义

接口说明：

输入参数说明：

返回结果说明(JSON格式):
失败返回错误码，请参照附录1的状态码说明表；

五、数据查询接口

5.1 通过第三方OPEN_ID获取WINGSDK平台用户ID

接口说明：

输入参数说明：

返回结果说明(JSON格式):
失败返回错误码，请参照状态码说明表；

5.2 查询区服角色信息

该接口由移动平台定义，CP负责实现
查询区服信息接口调用说明
1、WA服务端系统通过WA的userId来查询用户已经玩过的区服角色以及最近玩过的区服角色。
2、Url：https://****/serverinfo.do

接口说明：

输入参数说明：

返回结果说明(JSON格式):
失败返回错误码，请参照状态码说明表；

示例：

六、消息推送

6.1 消息推送接口

接口说明：

请求报文头：

body说明：

返回格式：

调用实例：

附录1：返回状态码说明

通用返回状态码说明（参考了Http状态码设计）：

平台自定义状态码说明

版本号	4.2.0	4.3.0	4.4.0	4.5.0	4.6.0	4.7.0	4.8.0
发布日期	20240923	20240927	20250318	20250702	20250723	20250911	20280928
iOS系统适配更新		iOS18
Apple模块
Firebase模块			常规升级	常规升级		常规升级
FACEBOOK			常规升级			常规升级
Appsflyer模块			常规升级	常规升级		常规升级
AiHelp			升级sdk版本，支持红点展示未读消息	常规升级		常规升级
欧盟Consent弹窗		升级	常规升级	常规升级		常规升级
AdMob					支持iOS互推	常规升级
重点提示		建议升级，按照Didomi的要求必须升级Didomi版本，否则10月4日后会影响Consent弹窗功能
建议升级的WingSDK版本	所有版本(有接入Consent弹窗功能的游戏)
升级指引	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可	直接获取WingSDK最新版本替换即可
已接入游戏数量	4	3	5	6	7	3	0

简介

WingSteamExeSDK主要是为满足PC端Steam平台Windows的游戏需要，为此类游戏提供基于Steam平台的登录、支付、数据收集等通用功能。以下文档中会把WingSteamExeSDK简称为SDK。

1.cp接入流程

相关步骤指引：

1.第一步，安装和接受邀请，参考《第5.1章 成为steam应用测试者》
2.第二步，集成和接入，参考《第2章 集成》以及之后的章节进行接入
3.第三步，本地调试，参考《第5.2章 本地开发测试》和《第5.3章 日志调试与沙盒支付》

2.集成

2.1.SDK库选择

SDK提供了多个版本的库文件，可以根据项目需求使用。

MT编译版本：已经内置VC运行库内容，不依赖于外部VC运行库。
普通(MD)编译版本：该版本会使用附带的vcruntime140.dll，msvcp140.dll，vcruntime140_1.dll这几个文件。

对应的dll版本:

2.2.项目集成

以VisualStudio项目工程为例

1.下载最新版本SDK压缩包，并解压
2.SDK头文件引入
1)复制include文件夹及其内容到项目中，主要包含wing目录下的wing_api.h头文件
2)右键项目->属性->C/C++->常规->附加包含目录，填入include文件夹路径，例如include文件夹是复制到项目根目录下，则路径可以填写：$(ProjectDir)include

3.SDK库文件引入
1)复制lib文件夹及其内容到项目中，并在项目属性页->链接器->常规->附加库目录，中填入lib文件夹路径，例如lib文件夹是复制到项目根目录下，则路径可以填写：$(ProjectDir)lib
2)在项目属性页->链接器->输入->附加依赖项中填入sdk的lib文件，如果是x86编译，则填入wingsdk.lib，如果是x64编译，则填入wingsdk64.lib，如果使用mt版本，则选择对应带mt后缀lib文件。

4.SDK的Api使用
1)在项目中引入。以前面步骤的配置路径作为示例，那么引入的路径为 #include “wing/wing_api.h”
2)在项目中使用。wing_api.h的接口为命名空间+方法的使用方式，例如：sdk的初始化方法使用，WingProxy::Init(“appId”,“appKey”,[](int code,string msg,string data){});

5.项目编译后，需要把sdk用到的dll文件复制到编译后的exe程序目录中，否则项目无法正常运行。具体版本对应的dll文件，参考前面dll版本文件对应表。例如x86的dll内容如下图：

6.运行程序

2.3.三方库版本

3.接口说明

3.1.使用方式

sdk的api采用命名空间+方法的形式定义的，WingProxy是所有sdk接口的命名空间，以支付是否可用方法为例，使用方式：

3.2.回调函数

sdk接口的参数中，除了一些常见类型参数，在wing_api.h中还声明了WingCallback回调函数，参数说明如下：

4.SDK接口

4.1.初始化

调用下面接口对SDK进行初始化，建议在程序开始时首先调用，确保后续其他sdk接口可以正常使用

参数说明：

代码示例：

4.2.退出程序

调用下面接口对SDK内资源进行释放，必须在程序退出前调用。

4.3.登录

使用下面接口进行登录

参数说明：

WingCallback的data内容字段说明：

代码示例：

4.4.退出登录

调用下面接口退出账号

4.5.检查支付是否可用

进行支付之前，需要先判断支付是否可用

返回值为bool类型，true 表示支付可用，false表示支付不可用。

4.6.购买商品

进行支付之前，需要先判断支付是否可用

参数说明：

WingCallback的data内容字段说明：

代码示例：

4.7.游戏必要参数设置

WINGSDK包括serverId等游戏参数，这些参数主要用于数据跟踪和统计。
该部分参数必须严格按照文档进行设置，在后续的接口中会使用到这些参数，没有按照要求配置会导致部分接口调用失败。

参数设置时机除了按照说明设置，另外需要特别注意在游戏启动时的设置时机，具体参考 流程要求

4.7.1 设置服务器ID

当用户的服务器ID发生改变时，需要调用设置服务器ID接口设置新的服务器ID，例如每次进入服务

注意：设置服务器id的操作在每次选服后都需要进行，必须在调用其他事件前设置

4.7.2.设置GameUserId

当游戏角色ID发生改变时，需要调用设置接口设置新的gameUserId，例如成功登录账号后、切换账号成功后

注意：
1.必须在调用其他事件前设置。
2.游戏角色ID是游戏角色在游戏中的ID，不是WINGSDK自身的UserId。
3.若未创角前拿不到游戏角色ID，可以先设置-1，创角后再设置一次正确的角色ID

4.7.3.设置用户等级Level

当用户角色等级发生改变时，需要调用设置等级接口设置新的等级，例如开始进入游戏、等级提升等。

注意：第一次进服获取玩家等级或玩家等级变更后，需要及时调用这个接口设置玩家等级，必须在调用其他事件前设置。

4.7.4.设置玩家游戏昵称

设置游戏玩家的昵称，调用接口:

注意：
1.当玩家登录、登出游戏，或修改昵称时，需要及时调用这个接口设置玩家昵称。
2.调用该接口设置昵称后，玩家进行购买时会自动记录昵称到订单信息中。

4.8.数据收集

4.8.1.流程要求

WINGSDK数据收集使用在游戏的过程中打点的方式，如图所示:

注意：

1.以上流程图中涉及到的几个接口是有时序要求的，请参考流程图中的逻辑步骤进行设置：WingProxy::SetServerId()、WingProxy::SetGameUserId()、WingProxy::SetLevel()、WingProxy::SetNickName()、ghw_user_import事件、ghw_user_create事件。

2.其它的事件如ghw_level_achieved、ghw_self_tutorial_completed等请根据对应业务逻辑，在对应业务发生时调用接口发送。

4.8.2.发送事件

使用下面接口发送事件

参数说明：

代码示例：

4.8.3.预定义事件

4.8.3.1.ghw_user_import导入用户事件(进服)

说明:导入用户事件，玩家第一次进某个服时调用

注意：发送ghw_user_import事件前需调用设置服务器ID接口更新服务器id、设置gameUserId接口更新游戏用户id
代码示例：

4.8.3.2.ghw_user_create 创建角色

说明:创建游戏角色，游戏角色创建时调用

代码示例

4.8.3.3.ghw_user_info_update 更新用户信息

代码示例

4.8.3.4.ghw_level_achieved 等级增长事件

说明:统计玩家等级增长事件，达到等级时调用。

注意：发送ghw_level_achieved事件前需调用设置用户等级level接口更新用户等级信息。

4.8.4.自定义事件

如果发送的事件不属于预定义事件范围，事件发送时会自动补上ghw_self_前缀，例如关键等级5的事件名称传入，lv_5，最终发送的事件名称为ghw_self_lv_5。

4.8.4.1.ghw_self_lv_x关键等级事件

代码示例：

4.6.4.2.ghw_self_tutorial_completed完成新手任务

5.本地开发调试

5.1.成为Steam应用测试者

在应用上线前，成为Steam应用测试者，可以以测试者的身份在steam客户端中拥有该游戏，并进行测试。
步骤：
1.研发提供steam账号邮箱给运营
2.运营在steam后台邀请该账号成为测试者
3.steam账号邮箱会接收到邀请邮件，需要点击接受邀请

4.运营在steam后台确认后，把该steam账号添加到对应游戏组，即可拥有该游戏权限
5.研发重新登录steam账号后查看是否已拥有目标游戏

5.2 本地开发测试

5.2.1 本地测试方式一

在应用未上线时，如果需要在本地进行开发测试，可以在本地exe的同级目录，增加一个steam_appid.txt，内容为steam应用的apppid(appid向运营获取)，如steam的appid为3141480，则内容如下图：

完成steam_appid.txt添加后，运行steam客户端，此时就可以直接运行本地exe进行SDK相关api的接入测试了。

注意：开发完成后打包时，需要移除steam_appid.txt

5.2.2 本地测试方式二

cp打个exe包(此时可以不接sdk)，然后让运营上传到steam后台，cp从steam上下载此游戏，然后通过游戏设置-管理-浏览本地文件，找到游戏下载路径。cp可以使用本地开发调试包进行替换，然后从steam上启动此游戏进行测试。

5.3 日志调试与沙盒支付

SDK的日志默认是关闭状态的，开启日志后会在程序目录下生成winglog.log日志文件，可以查看SDK的日志信息。

开启SDK调试日志：
1.SDK日志的开启需要提供设备的ClientId，在用户的隐藏目录AppData下找到SharedConf配置文件，以文本的形式查看文件可以得到ClientId值。
具体路径：C:\Users\用户名\AppData\Local\WingSteamExeSdk\SharedConf
文本内容参考：{“ClientId”:”5c56b3400000000000000e0a76c72″}
2.把ClientId的值提供给运营，运营在后台操作加入测试设备
3.重启已接入SDK的程序，进行SDK相关操作，即可在winlog.log查看SDK输出的相关日志信息。

沙盒支付：
同上面一样，加入测试设备后，重启已接入SDK的程序，即可进行沙盒支付进行支付相关测试

6.状态码说明

1.简介

WingSteamExeSDK主要是为满足PC端Steam平台Windows的游戏需要，为此类游戏提供基于Steam平台的登录、支付、数据收集等通用功能。以下文档中会把WingSteamExeSDK简称为SDK。

2.集成

2.1.SDK库选择

SDK提供了多个版本的库文件，可以根据项目需求使用。

MT编译版本：已经内置VC运行库内容，不依赖于外部VC运行库。
普通(MD)编译版本：该版本会使用附带的vcruntime140.dll，msvcp140.dll，vcruntime140_1.dll这几个文件。

对应的dll版本:

2.2.项目集成

以VisualStudio项目工程为例

1.下载最新版本SDK压缩包，并解压
2.SDK头文件引入
1)复制include文件夹及其内容到项目中，主要包含wing目录下的wing_api.h头文件
2)右键项目->属性->C/C++->常规->附加包含目录，填入include文件夹路径，例如include文件夹是复制到项目根目录下，则路径可以填写：$(ProjectDir)include

3.SDK库文件引入
1)复制lib文件夹及其内容到项目中，并在项目属性页->链接器->常规->附加库目录，中填入lib文件夹路径，例如lib文件夹是复制到项目根目录下，则路径可以填写：$(ProjectDir)lib
2)在项目属性页->链接器->输入->附加依赖项中填入sdk的lib文件，如果是x86编译，则填入wingsdk.lib，如果是x64编译，则填入wingsdk64.lib，如果使用mt版本，则选择对应带mt后缀lib文件。

4.SDK的Api使用
1)在项目中引入。以前面步骤的配置路径作为示例，那么引入的路径为 #include “wing/wing_api.h”
2)在项目中使用。wing_api.h的接口为命名空间+方法的使用方式，例如：sdk的初始化方法使用，WingProxy::Init(“appId”,“appKey”,[](int code,string msg,string data){});

5.项目编译后，需要把sdk用到的dll文件复制到编译后的exe程序目录中，否则项目无法正常运行。具体版本对应的dll文件，参考前面dll版本文件对应表。例如x86的dll内容如下图：

6.运行程序

2.3.三方库版本

3.接口说明

3.1.使用方式

sdk的api采用命名空间+方法的形式定义的，WingProxy是所有sdk接口的命名空间，以支付是否可用方法为例，使用方式：

3.2.回调函数

sdk接口的参数中，除了一些常见类型参数，在wing_api.h中还声明了WingCallback回调函数，参数说明如下：

4.SDK接口

4.1.初始化

调用下面接口对SDK进行初始化，建议在程序开始时首先调用，确保后续其他sdk接口可以正常使用

参数说明：

代码示例：

4.2.退出程序

调用下面接口对SDK内资源进行释放，必须在程序退出前调用。

4.3.登录

使用下面接口进行登录

参数说明：

WingCallback的data内容字段说明：

代码示例：

4.4.退出登录

调用下面接口退出账号

4.5.检查支付是否可用

进行支付之前，需要先判断支付是否可用

返回值为bool类型，true 表示支付可用，false表示支付不可用。

4.6.购买商品

进行支付之前，需要先判断支付是否可用

参数说明：

WingCallback的data内容字段说明：

代码示例：

4.7.游戏必要参数设置

WINGSDK包括serverId等游戏参数，这些参数主要用于数据跟踪和统计。
该部分参数必须严格按照文档进行设置，在后续的接口中会使用到这些参数，没有按照要求配置会导致部分接口调用失败。

参数设置时机除了按照说明设置，另外需要特别注意在游戏启动时的设置时机，具体参考 流程要求

4.7.1 设置服务器ID

当用户的服务器ID发生改变时，需要调用设置服务器ID接口设置新的服务器ID，例如每次进入服务

注意：设置服务器id的操作在每次选服后都需要进行，必须在调用其他事件前设置

4.7.2.设置GameUserId

当游戏角色ID发生改变时，需要调用设置接口设置新的gameUserId，例如成功登录账号后、切换账号成功后

注意：
1.必须在调用其他事件前设置。
2.游戏角色ID是游戏角色在游戏中的ID，不是WINGSDK自身的UserId。
3.若未创角前拿不到游戏角色ID，可以先设置-1，创角后再设置一次正确的角色ID

4.7.3.设置用户等级Level

当用户角色等级发生改变时，需要调用设置等级接口设置新的等级，例如开始进入游戏、等级提升等。

注意：第一次进服获取玩家等级或玩家等级变更后，需要及时调用这个接口设置玩家等级，必须在调用其他事件前设置。

4.7.4.设置玩家游戏昵称

设置游戏玩家的昵称，调用接口:

注意：
1.当玩家登录、登出游戏，或修改昵称时，需要及时调用这个接口设置玩家昵称。
2.调用该接口设置昵称后，玩家进行购买时会自动记录昵称到订单信息中。

4.8.数据收集

4.8.1.流程要求

WINGSDK数据收集使用在游戏的过程中打点的方式，如图所示:

注意：

1.以上流程图中涉及到的几个接口是有时序要求的，请参考流程图中的逻辑步骤进行设置：WingProxy::SetServerId()、WingProxy::SetGameUserId()、WingProxy::SetLevel()、WingProxy::SetNickName()、ghw_user_import事件、ghw_user_create事件。

2.其它的事件如ghw_level_achieved、ghw_self_tutorial_completed等请根据对应业务逻辑，在对应业务发生时调用接口发送。

4.8.2.发送事件

使用下面接口发送事件

参数说明：

代码示例：

4.8.3.预定义事件

4.8.3.1.ghw_user_import导入用户事件(进服)

说明:导入用户事件，玩家第一次进某个服时调用

注意：发送ghw_user_import事件前需调用设置服务器ID接口更新服务器id、设置gameUserId接口更新游戏用户id
代码示例：

4.8.3.2.ghw_user_create 创建角色

说明:创建游戏角色，游戏角色创建时调用

代码示例

4.8.3.3.ghw_user_info_update 更新用户信息

代码示例

4.8.3.4.ghw_level_achieved 等级增长事件

说明:统计玩家等级增长事件，达到等级时调用。

注意：发送ghw_level_achieved事件前需调用设置用户等级level接口更新用户等级信息。

4.8.4.自定义事件

如果发送的事件不属于预定义事件范围，事件发送时会自动补上ghw_self_前缀，例如关键等级5的事件名称传入，lv_5，最终发送的事件名称为ghw_self_lv_5。

4.8.4.1.ghw_self_lv_x关键等级事件

代码示例：

4.6.4.2.ghw_self_tutorial_completed完成新手任务

5.调试日志

SDK的日志默认是关闭状态的，开启日志后会在程序目录下生成winglog.log日志文件，可以查看SDK的日志信息。

开启SDK调试日志：
1.SDK日志的开启需要提供设备的ClientId，在用户的隐藏目录AppData下找到SharedConf配置文件，以文本的形式查看文件可以得到ClientId值。
具体路径：C:\Users\用户名\AppData\Local\WingSteamExeSdk\SharedConf
文本内容参考：{“ClientId”:”5c56b3400000000000000e0a76c72″}
2.把ClientId的值提供给运营，运营在后台操作加入测试设备
3.重启已接入SDK的程序，进行SDK相关操作，即可在winlog.log查看SDK输出的相关日志信息。

6.状态码说明