WING H5 SDK使用指南(v1.0)

WING H5 SDK使用指南(v1.0)

wapublisher No Comment
H5 SDK 对接文档

一.简介

WING H5 SDK主要是为满足HTML5类型游戏需要,为此类游戏提供登录、支付、数据收集等通用功能。该SDK适用于pc端与移动端的浏览器,facebook的gameroom,以及移动端应用程序的webview等HTML5运行环境。

二.功能简介

2.1.登录

SDK提供了有界面登录方式和无界面登录方式。有界面方式内置所有已经集成的登录方式,无需编写登录界面就可以集成多种登录方式。而无界面方式则需要CP提供相对应的登录界面来调用具体登录方式。
目前WING H5 SDK 支持的登录方式有Guest,Facebook,应用内登录。

2.2.支付

支付包括Facebook支付以及Web支付,其中Web支付又包括了多种支付方式比如Paypal、MOL、Xsolla等。

2.3.数据收集

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

2.4.调试模式

调试模式提供窗口查看日志,帮助开发者更快的集成SDK与定位相关的开发问题。

三.集成WING H5 SDK

3.1.适用范围

该SDK适用于HTML5类型的游戏或应用,特别是在Facebook上线的页游。为这些游戏提供登录、支付、数据收集等基础功能,同时提供调试窗口,满足游戏能顺利运行的基本功能需求,更多的功能目前还在持续开发中。

3.2.如何集成

WING H5 SDK推荐使用标签方式引入JS,同时也支持AMD、CommonJS等方式引入。

3.3.接口说明

以下是WING H5 SDK各个接口的具体使用说明。

3.3.1.初始化

初始化方法:wing.init(paramObj);

初始化sdk库,在调用其他方法前,必须先调用此方法。

参数说明:

参数名 类型 必填 说明
appId String Y 应用ID
appKey String Y 应用秘钥
sdkType String N sdk类型:html5或者fbinstant(facebook小游戏),默认为’html5’
platform String N 使用平台:html5,gameroom,fbinstant,默认为’html5’
debug Boolean N 调试模式开关,true|false,默认是关闭false,打开后会显示log按钮悬浮窗,上线时请关闭或者不设置

示例:

3.3.2.登录

3.3.2.1.获取登录方式

方法:wing.user.getLoginWay();

返回结果参数说明:

参数名 类型 必填 说明
code Number Y 见代码说明
msg String Y 结果描述
size Number Y 登录方式数量
data JSON Y 见下表

data数据结构:

参数名 类型 必填 说明
platform String Y 见代码说明
logoUrl String Y Logo地址

示例:

3.3.2.2.用户登录

方法:wing.user.login(paramObj);

参数说明:

参数名 类型 必填 说明
platform String N 见代码说明
FB Boolean N Facebook内嵌游戏(页游)需要设置为true
success Object N 成功回调方法
fail Object N 失败回调方法
cancel Object N 取消回调方法

示例:

返回结果参数说明:

参数名 类型 必填 说明
code Number Y 见代码说明
msg String Y 结果描述
platform String Y 见代码说明
userId Number Y 用户ID
token String Y 用户token
puserId String N 平台用户ID

注:
1:platform 字段不传入时,将获取该应用可用的登录方式,用窗口展示给用户选择;
2:platform字段传入具体平台值时,不再弹出登录方式选择框,直接跳到对应的登录方式
3:Facebook内嵌游戏应当同时传入platform=FACEBOOK,FB=true。

3.3.3.支付

3.3.3.1.获取商品列表

方法:wing.pay.getProducts();

示例:

3.3.3.2.购买商品

方法:wing.pay.payUI(params);

参数说明:

参数名 类型 必填 说明
channel String N 见代码说明
productId String Y 产品ID
success Object N 支付回调

示例:

注:
1:对于网页支付方式如Paypal等,支付后在弹出窗口关闭时回调,result不返回数据
2:对于Facebook支付,支付完成后,result返回Facebook所有数据
如:

3:channel字段为可选字段,传入该值则直接使用对应支付方式,否则弹出所有支付方式选择窗口

3.3.4.公共参数设置

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

3.3.4.1.设置游戏用户id

wing.setGameUserId()

参数说明:

参数名 类型 必填 说明 备注
gameUserId String Y 游戏玩家ID

示例:

3.3.4.2.设置服务器id

wing.setServerId()

参数说明:

参数名 类型 必填 说明 备注
serverId String Y 区服ID

示例:

3.3.4.3.设置等级

wing.setLevel()

参数说明:

参数名 类型 必填 说明 备注
level Number Y 等级

示例:

3.3.5.数据收集

使用SDK数据收集接口配合大数据平台,可以轻松统计玩家习惯以及充值等行为,为游戏的市场营销提供数据依据。
目前数据收集支持以下平台: WING SDK 后台、 Facebook 后台
WINGSDK数据收集使用在游戏的过程中打点的方式,如图所示:
图片5

以上流程图中涉及到的几个接口: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事件则需要在事件发生的对应时机调用接口发送。

SDK内部集成多个数据收集渠道,对于同一个事件,不同的渠道对应的事件名称和参数值可能不尽相同,可以使用下面数据发送接口应对此类需求。

3.3.5.1.数据发送

方法:wing.trackEvent(WAEvent);

参数说明:

参数名 类型 必填 说明
WAEvent SDK内置对象WAEvent Y 详细查看事件对象事件对象

示例:

示例说明:setDefaultEventName方法用于设置发送事件的名称,GHW_PURCHASE为SDK定义的购买事件名称,所有SDK预定义的事件名称可以在下文的3.3.7.1.事件常量章节查看。setDefaultValue为设置事件默认价值,addDefaultEventValue为设置默认事件参数/值,其中SDK定义参数在下文3.3.7.2.参数常量章节可查看。setChannelEventName为设置渠道自定义事件名称,用于发往第三方平台时更改事件命名。setChannelEventValues为事件渠道自定义的参数/值,用于发往第三方平台时,替换默认事件参数。

下面是WAEvent对象的具体说明。

3.3.5.2.事件对象

全局对象:wing.WAEvent

实例化
方法:builder()

参数:无

示例:

WAEvent对象是SDK提供的帮助类,用于封装需要SDK追踪的数据,可以使用链式调用的方式使用该对象。在使用前必须调用初始化方法builder()才能使用。下列是WAEvent剩余的所有方法,点击链接跳转到具体的方法查看说明。

序号 方法 必须 说明
1 setDefaultEventName Y 设置默认事件名称
2 setDefaultValue N 设置默认事件值
3 addDefaultEventValue N 设置一个事件参数
4 addAllDefaultEventValue N 设置多个事件参数
5 setChannelEventName N 设置渠道自定义事件名称
6 setChannelEventValues N 设置事件渠道自定义的参数/值
7 disableChannel N 禁用渠道
8 disableAllChannel N 禁用所有第三方渠道
9 getDisableChannels N 获取禁用渠道列表
10 getDefaultEventName N 获取默认事件名称
11 getDefaultValue N 获取默认事件价值
12 getDefaultEventValues N 获取默认事件参数对象
13 getChannelEventNames N 获取渠道事件名称列表(渠道-事件名称键值对)
14 getChannelEventValues N 获取渠道事件对象
15 getIsDisableAllChannel N 判断是否禁用所有其他渠道事件发送

1)设置默认事件名称
方法:setDefaultEventName(eventName)
此方法为所有渠道的单个事件设置默认事件名称,如果渠道没有单独设置则使用此默认值。

参数:

参数名 类型 必填 说明
eventName WA_EVENT_TYPE Y 事件名称

示例:

2)设置默认事件值
方法:setDefaultValue(val)
此方法为所有渠道的单个事件设置默认事件值,如果渠道没有单独设置则使用此默认值。

参数:

参数名 类型 必填 说明
val Number Y 事件值,如商品价格

示例:

3)设置一个事件参数
方法:addDefaultEventValue(paramName, val)
此方法为所有渠道的单个事件设置事件参数,如果渠道没有单独设置则使用此默认参数。每次添加一个,可调用多次。

参数:

参数名 类型 必填 说明
paramName String Y 具体参数名
val all Y 具体参数值

示例:

设置多个事件参数
方法:addAllDefaultEventValue(obj)
此方法为所有渠道的单个事件设置事件参数,如果渠道没有单独设置则使用此默认参数。每次可添加多个,只可调用一次。

参数:

参数名 类型 必填 说明
obj JSON Y 事件内容

示例:

5)设置渠道自定义事件名称,针对渠道需要设置特定的事件名称
说明:使用该方法单独为某一渠道设置事件名称,该事件名称将替换掉setDefaultEventName设置的事件名称。

方法:setChannelEventName(channelName, eventName)

参数:

参数名 类型 必填 说明
channelName String Y 平台名称
eventName String Y 事件名称

示例:

6)设置事件渠道自定义的参数/值
说明:使用该方法单独为某一渠道的某个事件设置参数值,如果不设置则使用addDefaultEventValue或addAllDefaultEventValue方法设置的默认参数。

方法:setChannelEventValues(channelName, obj)

参数:

参数名 类型 必填 说明
channelName String Y 平台名称
obj String Y 参数对象

示例:

7)禁用渠道
说明:发送某事件时,不发送该事件到指定渠道。

方法:disableChannel(channelName)

参数:

参数名 类型 必填 说明
channelName String Y 平台名称

示例:

8)禁用所有第三方渠道
说明:发送某事件时,不发送该事件到所有第三方渠道。

方法:disableAllChannel()

参数:无

示例:

9)获取事件信息方法列表
说明:使用下面方法可以获取前面方法设置的参数值。

方法 说明
getDisableChannels() 获取禁用渠道列表
getDefaultEventName() 获取默认事件名称
getDefaultValue() 获取默认事件价值
getDefaultEventValues() 获取默认事件参数对象
getChannelEventNames() 获取渠道事件名称列表(渠道-事件名称键值对)
getChannelEventValues() 获取渠道事件对象
getIsDisableAllChannel() 判断是否禁用所有其他渠道事件发送

示例:

3.3.6.调试

SDK提供了调试模式供开发者使用,具体打开方式如下:

在初始化时设置debug=true,开发时浏览器打开开发者模式,在控制台即可看到相关操作日志,开发者可以根据日志快速排查问题,提高效率。

3.3.7.常量

以下是SDK内部预定义常量。

3.3.7.1.事件常量

以下是SDK预定义事件。

事件对象:wing.WAEvent.WA_EVENT_TYPE

事件名称对应常量:

事件名称 说明 备注
GHW_INITIATED_PURCHASE 点击购买 发送该事件前必须调用wing.setLevel方法设置等级
GHW_PURCHASE 购买完成 发送该事件必须要设置ITEM_NAME、ITEM_AMOUNT、PRICE、LEVEL参数或调用wing.setLevel方法
GHW_USER_CREATE 创建角色 必须要设置NICKNAME、REGISTER_TIME参数,可以有选择的设置ROLE_TYPE、GENDER、VIP、STATUS、BIND_GAME_GOLD、GAME_GOLD、FIGHTING等以上参数
GHW_USER_INFO_UPDATE 更新用户信息 可以有选择的设置ROLE_TYPE、NICKNAME参数
GHW_USER_IMPORT 导入用户 必须要设置IS_FIRST_ENTER
GHW_GOLD_UPDATE 消耗游戏币 必须要设置GOLD_TYPE、APPROACH、AMOUNT可以有选择的设置CURRENT_AMOUNT参数
GHW_TASK_UPDATE 玩家任务统计 必须要设置TASK_ID、TASK_NAME、TASK_TYPE、TASK_STATUS 参数
GHW_LEVEL_ACHIEVED 等级或分数 必须要提前调用wing.setLevel方法必须要设置SCORE、FIGHTING参数
GHW_SELF_ 用于自定义事件 事件名称可以为 GHW_SELF_ + 自定义字符串

3.3.7.2.参数常量

以下是SDK预定义事件的参数定义
参数对象:wing.WAEvent.WA_EVENT_PARAMETER_NAME

参数常量:

参数名称 说明 备注
ITEM_NAME String 游戏内虚拟物品的名称/ID
ITEM_AMOUNT Number 交易的数量
TASK_ID String 任务ID
TASK_NAME String 任务名称
LEVEL Number 级别或分数
GENDER Number 性别, 0 女 1 男 2 未知
NICKNAME String 昵称
VIP Number 等级
STATUS Number 状态标识.-1: 锁定,1:未锁定
BIND_GAME_GOLD Number 绑定钻石
GAME_GOLD Number 用户钻石数
FIGHTING Number 战斗力
PRICE Number 价格
REGISTER_TIME Number 注册时间戳,单位为毫秒(1970以后)
ROLE_TYPE String 角色类型
IS_FIRST_ENTER Number 是否第一次导入用户,0:否, 1:是 默认为0
GOLD_TYPE Number 货币类型钻石,绑定钻石,金币,军魂等。预定义有1和2:1→游戏货币;2→游戏绑定货币
APPROACH String 变更途径,开通VIP、任务获得、公会贡献、解锁背包等
AMOUNT Number 变更货币数, 消耗用负数表示,获取用正数表示
CURRENT_AMOUNT Number 用户变更以后该种货币的数量
TASK_TYPE String 任务类型
TASK_STATUS Number 任务状态:状态标识:1→领取任务,2→开始任务,3→待领奖(任务完成),4→已领奖
SCORE Number 得分数

3.3.7.3.第三方平台常量

参数对象:wing.WAEvent.TRACKING_CHANNEL

参数常量:

事件名称 说明
FB Facebook数据收集平台

四.代码说明

4.1.登录类型对照表:

平台类型 说明
GUEST 游客登录
FACEBOOK FACEBOOK平台
GOOGLE GOOGLE 平台
APPSELF 应用内登录

4.2.支付类型对照表:

支付类型 说明
FACEBOOK Facebook支付
PAYMENTWALL Paymentwall支付
BOACOMPRA Boacompra支付
MOL Mol支付
MOL_VC Mol点卡支付
XSOLLA Xsolla支付
XSOLLA_VC Xsolla 点卡支付
IPAYLINKS Ipaylinks支付
CODAPAY Codapay支付
UNIPIN UniPin支付
SAFECHARGE SafeCharge支付
GUDANGVOUCHER GudanGvoucher支付
ALIPAY 支付宝
UNIONPAY 银联
YEEPAY 易宝
PAYPAL PayPal支付

4.3.状态码

状态码 说明
200 操作成功
400 操作失败
500 操作错误

Leave a Reply