Gameroom

WINGSDK_Gameroom使用指南(v1.0)

wapublisher No Comments

一、简介

1.1 用户模块

用户模块提供用户登录接口,支持匿名登录和Facebook登录。

1.2 支付模块

支付模块提供支付充值接口,集成简单,无需理会复杂的支付流程,轻松完成商品的购买(充值)。

1.3 数据收集模块

数据收集模块提供了数据收集的接口,多渠道灵活调用。数据收集包含了丰富的应用内的事件类型,还支持用户自定义事件类型。

二、快速集成

2.1 环境配置要求

需要使用 Unity 5.0 的基本版 SDK;

下载并安装包含 Facebook 构建支持的 Unity(可用的最低版本为 5.6):访问Unity商店即可下载

更多详细要求请参考Facebook Gameroom游戏开发要求

说明:
1)SDK内部已经包含Facebook SDK,版本:7.10.1

2.2 集成SDK到项目

新建或打开游戏工程项目,在菜单中打开File→Build Settings选项,在Platform中选中”PC,Mac & Linux Standalone”,然后点击下方的“Switch Platform”按钮切换到该平台。
gameroom-集成SDK到项目

打开菜单Assets→Import Package→Custom Package…,浏览选中WASdk Unity的package,导入到项目,导入时请将所有文件勾选。
gameroom-集成SDK到项目

gameroom-集成SDK到项目
到这已经完成了WINGSDK的集成。

提示:
1)导入unitypackage之后Unity编辑器如果没有显示WINGSDK菜单,请重启Unity编辑器。

2.3 SDK配置及初始化

2.3.1 SDK配置

导入SDK到项目后,在菜单栏上有一个“WASdk”的菜单项,点击在下拉菜单中选中“Edit Settings”,在Inspector面板上显示SDK的配置项,在“WA Settings”配置WINGSDK的相关参数,勾选“Enable facebook”启用Facebook渠道(Gameroom必须启用Facebook渠道),并配置Facebook App Id。
gameroom-SDK配置

说明:
1)WINGSDK ApiUrl:https://api.wingsdk.com/sdkapi
2)WINGSDK TrackUrl:https://api.wingsdk.com/data

2.3.2 SDK初始化

调用下面接口对SDK进行初始化:

WACoreProxy.Initialize ();

注意:SDK初始化必须在第一个Scene脚本中调用,强烈建议在UI线程中调用,可以在Awake()或者Start()中进行。

2.4 登录

2.4.1使用接口登录

使用登录接口登录,调用以下接口:
WAUserProxy.Login(string platform, string extInfo, WAOnResult<WALoginResult> onLoginResult)

参数说明:

参数名 类型 必填 说明 备注
platform string Y 登录账户的渠道类型 在WAChannelType类中定义,Gameroom中要求不能使用匿名登录,所以只能使用FACEBOOK渠道
extInfo string N
onLoginResult WAOnResult<WALoginResult> N 返回登录结果的委托,包含一个WALoginResult类型参数,delegate(WALoginResult) 2.4.2 处理登录结果

2.4.2 处理登录结果

登录结果通过传入的回调返回,数据封装在WALoginResult类中。

WALoginResult字段说明

字段名 类型 说明 备注
Code int 登录结果码 4.1.1 状态码说明
Msg string 登录结果消息
WaUserId string WINGSDK用户id
WaToken string WINGSDK用户token
PlatformUserId string 平台用户id
PlatformToken string 平台用户token
Platform string 平台类型 当前登录的平台名称

2.4.3 用户登出

退出游戏的时候,必须执行登出操作。用户登出调用以下接口:

WAUserProxy.LogOut();

注意:调用Logout接口后,serverId、gameUseId、level字段值会被重置,如果需要保持相应字段的值不重置,需要重新设置相应字段的值,参考3.1 公共参数设置

2.5 支付

WINGSDK支付大致流程如下所示:
gameroom-支付流程图

2.5.1 初始化支付

初始化支付,SDK会对所有已经支持的支付平台做初始化,初始化调用接口

WAPayProxy.Initialize(WAOnResult<WAResultBase> onResult);

参数说明:

参数名 类型 必填 说明 备注
onResult WAOnResult<WAResultBase> N 返回初始化结果的委托,包含一个WAResultBase类型参数,delegate(WAResultBase) 初始化成功才能使用支付

WAResultBase实体类说明:

字段 返回值类型 不为空 说明 备注
Code int Y 结果码
Msg string Y 结果描述

调用支付前必须进行支付初始化,初始化成功才能使用支付功能。

2.5.2 查询商品列表

通过查询商品列表,可以获取所有可以购买的商品,查询商品列表调用接口

WAPayProxy.QueryInventory(WAOnResult<WAProductResult> onResult);

注意:这里返回的商品信息是WINGSDK平台的商品信息,并非第三方平台的商品信息。

参数说明:

参数名 类型 必填 说明 备注
onResult WAOnResult<WAProductResult> N 返回初始化结果的委托,包含一个WAProductResult类型参数,delegate(WAProductResult) 返回的商品信息是WINGSDK平台的商品信息

WAProductResult实体类说明:

字段 返回值类型 不为空 说明 备注
Code int Y 结果码
Msg string Y 结果描述
Products List<WAProduct> Y 商品列表

WAProduct实体类说明:

字段 返回值类型 不为空 说明 备注
ProductId string Y 库存商品id
ProductName string N 商品名称
ProductDesc string N 商品描述
GameCurrencyAmount long Y 虚拟货币数

2.5.3 购买商品

购买指定商品,调用以下接口发起支付:

WAPayProxy.Pay(string waProductId, string extInfo, WAOnResult<WAPayResult> onResult);

参数说明:

参数名 类型 必填 说明 备注
waProductId string Y WINGSDK 商品的id 必须WINGSDK 平台的商品id
extInfo string N 额外信息,该信息会在支付成功后原样通知到CP服务器,CP用于检验 CP 扩展信息字段,限长512(JSON格式),WING服务器到CP服务器发货通知时原样返回给CP。
如果CP的通知发货地址是动态变化的(比如每个服务区的地址都不一致),可以通过此字段设置:参数格式为标准JSON,参数名为 deliverUrl,参考格式
{
“deliverUrl”:” http://game.com/deliver.do”,
“otherInfo”:”otherInfo”,
“merId”:””
}
merId字段(选填),收款商户ID,使用场景:同一个支付渠道下有多个不同的收款验证信息(或收款帐号)。
如果是 APPLE支付渠道,merId使用客户端bundleId
onResult WAOnResult<WAPayResult> N 返回支付结果的委托,包含一个WAPayResult类型参数,delegate(WAPayResult)

WAPayResult实体类说明:

字段名 返回值类型 不为空 说明 备注
Platform string Y 支付平台
WAProductId string Y WINGSDK商品id
ProductName string N 额外数据 支付的时候CP传入的
OrderId string N WINGSDK订单号 部分支付方式没有
PlatformProductId string N 第三方平台商品id
PriceCurrencyCode string N 本地货币类型
PriceAmountMicros long N 本地货币数量 微分,1元=1000000
DefaultCurrency string N 基准货币类型
DefaultAmountMicro long N 基准货币数量 微分,1元=1000000
VirtualCurrency string N 虚拟货币类型
VirtualCoinAmount long Y 虚拟货币数量
ExtInfo string N 额外数据

2.5.4 资源释放

不再使用支付时需要对资源进行释放,可以清理所有支付渠道所占用的资源,调用接口:

WAPayProxy.Destroy();

2.6 数据收集

使用WINGSDK数据收集接口配合大数据平台,可以轻松统计玩家习惯以及充值等行为,为游戏的市场营销提供数据依据。WINGSDK数据收集使用在游戏的过程中打点的方式,如图所示:
gameroom-数据收集

以上流程图中涉及到的几个接口:SetServerId、SetGameUserId、SetLevel、ghw_user_import事件、ghw_user_create事件是有时序要求的,其它的事件如ghw_initiated_purchase、ghw_purchase、ghw_level_achieved、ghw_user_info_update、ghw_gold_update和ghw_task_update事件则需要在事件发生的对应时机调用接口发送。

2.6.1 发送数据

2.6.1.1 构建WAEvent对象

使用WAEvent.Builder构建一个WAEvent类对象,并设置数据收集的相关参数:

2.6.1.2 发送数据

调用第一步创建WAEvent对象的Track()方法发送数据

waEvent.Track();

或者调用以下接口发送:

WATrackProxy.TrackEvent(WAEvent waEvent)

2.6.1.3 WAEvent.Builder方法介绍

  • 设置默认的事件名称

public Builder SetDefaultEventName(string eventName)

参数:
eventName事件名称

  • 设置渠道自定义事件名称,针对某个渠道需要设置特定的事件名称

public Builder SetChannelEventName(string eventChannel, string eventName)

参数:
eventChannel 渠道名称
eventName 事件名称

注意:
1)如果不进行设置,所有的渠道将采用设置的默认值。

  • 设置默认累加值

public Builder SetDefaultValue(float value)

参数:
value 累加统计的数值

  • 设置渠道自定义累加值,针对某个渠道需要设定特定的累加值

public Builder SetChannelValue(string eventChannel, float value)

参数:
eventChannel 渠道名称
value累加统计的数值

注意:
1)如果不进行设置,所有的渠道将采用设置的默认值。

  • 设置事件默认的参数/值,每次可添加多个

public Builder SetDefaultEventValues(Dictionary<string, object> eventValues)

参数:
eventValues 参数/值Dictionary

  • 添加一个事件默认的参数/值,每次添加一个

public Builder AddDefaultEventValue(string paramName, object paramValue)

参数:
paramName 参数名称
paramValue 参数值

  • 设置事件渠道自定义的参数/值,每次可添加多个,针对某个渠道需要设定特定的参数或者值

public Builder SetChannelEventValues(string eventChannel, Dictionary<string, object> eventValues)

参数:
eventChannel 渠道名称
eventValues参数/值Dictionary

注意:
1)如果不进行设置,所有的渠道将采用设置的默认值。

  • 设置事件渠道自定义的参数/值,每次添加一个,针对某个渠道需要设定特定的参数或者值

public Builder AddChannelEventValue(string eventChannel,string paramName, object paramValue)

参数:
eventChannel 渠道名称
paramName参数名
paramValue参数值

注意:
1)如果不进行设置,所有的渠道将采用设置的默认值。

  • 禁用渠道,禁用后的渠道不会发送数据

public Builder DisableChannel(string eventChannel)

参数:
eventChannel 渠道名称

注意:
1)默认情况下是所有启用的渠道都发送
2)该接口只是针对当前事件禁用发送到某个渠道

2.6.2 SDK预定义事件

WINGSDK包括了以下预定义事件。

建议参数属性:(参数对应的静态变量名请看4.2.2 SDK预定义参数名

2.6.2.1 ghw_initiated_purchase点击购买(虚拟货币)

说明:点击购买的时候调用(用于游戏内部虚拟交易统计)。

2.6.2.2 ghw_purchase购买完成(虚拟货币)

说明:购买完成的时候调用(用于游戏内部虚拟交易统计)。

参数名 类型 说明 必填 备注
itemName string 游戏内虚拟物品的名称/ID Y
itemAmount int 交易的数量 Y
price float 交易的总价 Y

2.6.2.3 ghw_level_achieved 等级增长事件

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

参数名 类型 说明 必填 备注
score int 账户分数 N
fighting int 战斗力 N

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

2.6.2.4 ghw_user_create 创建角色

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

参数名 类型 说明 必填 备注
roleType string 角色类型 N
nickname string 角色名(昵称) Y
gender int 角色性别 N 0 女
1 男
2 未知
registerTime long 创建时间 Y 注册时间戳,单位为毫秒(1970以后)
vip int 等级 N
bindGameGold int 绑定钻石 N
gameGold int 用户钻石数 N
fighting int 战斗力 N
status int 状态 N 状态标识,-1: 锁定,1:未锁定

2.6.2.5 ghw_user_info_update更新用户信息

说明:更新用户资料

参数名 类型 说明 必填 备注
roleType int 角色类型 N
nickname string 昵称 N
vip int 等级 N
status int 状态 N 状态标识,-1: 锁定,1:未锁定

2.6.2.6 ghw_gold_update货币状况更新

说明:玩家货币状况变更统计

参数名 类型 说明 必填 备注
approach string 变更途径 Y 开通VIP、任务获得、公会贡献、解锁背包等
goldType int 货币类型 Y 钻石,绑定钻石,金币,军魂等。
预定义有1和2:
1→游戏货币;
2→游戏绑定货币
amount int 变更货币数 Y 消耗用负数表示,获取用正数表示
currentAmount int 用户变更以后该种货币的数量 N

2.6.2.7 ghw_task_update玩家任务统计

说明:玩家任务信息统计

参数名 类型 说明 必填 备注
taskId string 任务Id Y
taskName string 任务名称 Y
taskType string 任务类型 Y
taskStatus int 任务状态 Y 状态标识:
1→领取任务,
2→开始任务,
3→待领奖(任务完成)
4→已领奖

2.6.2.8 ghw_user_import导入用户事件

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

参数名 类型 说明 必填 备注
isFirstEnter int 是否第一次进服 Y 0→否;
1→是;
默认为0

注意:发送ghw_user_import事件前需调用3.1.1 设置服务器ID接口更新服务器id

2.6.3 自定义事件

说明:支持自定义事件的统计

三、高级功能

3.1 公共参数设置

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

3.1.1 设置服务器ID

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

WACoreProxy.SetServerId(string serverId)

注意:设置服务器id的操作在每次选服后都需要进行,必须在调用其他接口前设置。

3.1.2 设置gameUserId

当gameUserId发生改变时,需要调用设置gameUserId接口设置新的gameUserId,例如成功登录账号后、切换账号成功后。

WACoreProxy.SetGameUserId(string gameUserId)

注意:必须在调用其他接口前设置。

3.1.3 设置用户等级Level

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

WACoreProxy.SetLevel(int level)

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

四、附录

4.1 代码说明

4.1.1 状态码说明

SDK中的状态码统一以静态变量方式封装在WAStatusCode类里面,如果使用到状态码,强烈建议采用静态变量的方式调用,不要直接使用数值。

名称 取值 说明
CODE_SUCCESS 200 成功
CODE_ERROR 400 错误
CODE_UNAUTHERIZED 401 请求未认证:访问受限资源是缺少认证信息,或者认证未通过
CODE_FORBIDEN 403 禁止访问:由于应用上下文原因或请求端上下文的原因被禁止访问资源,例如IP限制等
CODE_NOT_FOUND 404 找不到被访问资源:接口不存在、页面不存在或对应的业务实体找不到
CODE_SERVER_ERROR 500 服务器内部故障
CODE_API_INVALID 501 所请求接口或页面未实现
CODE_SDK_APPID_INVALID 4010 无效appId: appId不存在或未开启
CODE_SIGN_ERROR 4011 无效osign:osign校验失败
CODE_REQUEST_TIME_OUT 4012 请求已过期:ots校验失败
CODE_PLATFORM_VERIFY_ERROR 4013 第三方平台验证失败
CODE_ACCOUNT_VERIFY_ERROR 4014 访客登录验证失败,登录验证失败
CODE_PLATFORM_BOUND_ALREADY 4015 用户已经绑定了这个平台的其他账户
CODE_PRE_PLATFORM_VERIFY_ERROR 4016 prePlatform验证失败
CODE_USER_NOT_FOUND 4017 用户不存在(没有找到)
CODE_ACCOUNT_BOUND_BY_OTHERS 4018 账户已经被其他用户绑定
CODE_ORDER_ID_INVALID 4019 无效orderId
CODE_ORDER_VERIFY_ERROR 4020 订单验证失败
CODE_REWARD_NOT_FOUND 4021 FB邀请奖励事件未找到奖励政策
CODE_REPEAT_CRASH_REPORT 4022 闪退发送报告重复
CODE_CHENNEL_NOT_FOUND 4023 未找到渠道信息
CODE_UNABLE_DISBAND 4024 不可以执行解绑操作
CODE_PAY_PLATFORM_CLOSED 4026 支付渠道已关闭
CODE_LOGIN_PLATFORM_CLOSED 4029 登录渠道已关闭
CODE_CANCELED -100 取消操作
CODE_FILE_NOT_FOUND -101 文件找不到
CODE_API_NOT_SUPPORTED -102 API不支持
CODE_SDK_UNINITIALIZED -200 SDK没有初始化
CODE_CONTENT_CAN_NOT_BE_SHARED -201 内容不可分享,一般是传入的内容为空,或者其他
CODE_NOT_LOGIN -202 没有登录
CODE_LOGIN_FAILURE -203 登录失败
CODE_NO_PERMISSION -204 登录没有获取到相应的权限
CODE_EXCEPTION -205 Facebook内部定义的错误,异常信息
CODE_FILE_SIZE_LIMIT -206 文件大小超出限制
CODE_NOT_LOGIN_WITH_PLATFORM -207 没有以平台登录
CODE_SERVER_ID_NOT_FOUND -208 ServerId没有设置
CODE_ACCOUNT_NOT_FOUND -209 账户不存在
CODE_ACCOUNT_NOT_ALLOW_UNBIND -210 账户不允许解绑
CODE_PLATFORM_ACCOUNT_NOT_MATCH -211 登录的平台账户和当前用户不匹配
CODE_GAME_USER_ID_NOT_FOUND -212 Game user id没有设置
CODE_DEVICE_NO_SUPPORTED -401 设备不支持
CODE_NETWORK_UNAVAILABLE -402 网络不可用
CODE_PAY_SERVICE_DISCONNECTED -501 支付:服务连接中断
CODE_PAY_SERVICE_UNUSABLE -502 支付:服务不可用
CODE_PAY_ITEM_UNAVAILABLE -503 支付: 商品不可用
CODE_PAY_DEVELOPER_ERROR -504 支付:开发者错误
CODE_PAY_ITEM_ALREADY_OWNED -505 支付:已经拥有该商品(没有消耗)
CODE_PAY_ITEM_NOT_OWNED -506 支付:没有拥有该商品
CODE_PAY_WITHOUT_REPORT -507 支付:支付成功但是没有上报或者上报失败了
CODE_PAY_CHECKING_FAILED -508 支付:支付成功,但是通知后台的时候校验失败了
CODE_PAY_REORDER_TIME_LIMIT -509 支付:订单时间间隔限制(在特定的时间内重复下订单)

4.1.2 平台取值

名称 取值 备注
CHANNEL_WA WINGA WINGSDK平台,分匿名登录和应用内登录
CHANNEL_FACEBOOK FACEBOOK Facebook平台

4.2 事件说明

4.2.1 SDK预定义事件名

在WAEventType接口中定义

静态变量名称 事件名称 说明
INITIATED_PURCHASE ghw_initiated_purchase 点击购买
COMPLETE_PURCHASE ghw_purchase 购买完成
USER_CREATED ghw_user_create 创建角色
USER_INFO_UPDATE ghw_user_info_update 更新用户信息
IMPORT_USER ghw_user_import 导入用户
GOLD_UPDATE ghw_gold_update 消耗游戏币
TASK_UPDATE ghw_task_update 玩家任务统计
LEVEL_ACHIEVED ghw_level_achieved 等级或分数

4.2.2 SDK预定义参数名

在WAEventParameterName接口中定义

静态变量名称 参数名称 数据类型 说明
ACCOUNT_TYPE accountType string 账户类型
GENDER gender int 性别
AGE age int 年龄
SUCCESS success boolean 是否成功
TRANSACTION_ID transactionId string 交易的流水号
PAYMENT_TYPE paymentType string 支付类型
CURRENCY_TYPE currencyType string 货币类型
CURRENCY_AMOUNT currencyAmount float 现金额
VERTUAL_COIN_AMOUNT virtualCoinAmount int 虚拟货币数量
VERTUAL_COIN_CURRENCY virtualCurrency string 虚拟货币类型
IAP_ID iapId string 道具ID
IAP_NAME iapName string 道具名称
IAP_AMOUNT iapAmount int 道具数量
ITEM_NAME itemName string 游戏内虚拟物品的名称/ID
ITEM_AMOUNT itemAmount int 交易的数量
SCORE score int 得分数
PRICE price float 价格
CONTENT_TYPE contentType string 内容类型
CONTENT_ID contentId string 内容ID
QUANTITY quantity int 数量
SEARCH_STRING searchString string 搜索关键字
DESCRIPTION description string 描述
NICKNAME nickname string 昵称
VIP vip int 等级
ROLE_TYPE roleType string 角色类型
BINDED_GAME_GOLD bindGameGold int 绑定钻石
GAME_GOLD gameGold int 用户钻石数
FIGHTING fighting int 战斗力
REGISTER_TIME registerTime long 注册时间
TASK_ID taskId string 任务Id
TASK_NAME taskName string 任务名称
TASK_TYPE taskType string 任务类型
TASK_STATUS taskStatus int 任务状态
状态标识:1→领取任务,
2→开始任务,
3→待领奖(任务完成),
4→已领奖
GOLD_TYPE goldType int 货币类型
AMOUNT amount int 变更货币数
APPROACH approach string 变更途径
IS_FIRST_ENTER isFirstEnter int 是否第一次导入用户,默认为0, 是为1
STATUS status int 状态