WINGPLUS H5 SDK使用指南(v3.10.0)

WINGPLUS H5 SDK使用指南(v3.10.0)

wapublisher No Comment
WINGPLUS H5 SDK对接文档

一.简介

WINGPLUS H5 SDK主要是为满足HTML5类型游戏以及微端游戏需要,为此类游戏提供登录、支付、数据收集等通用功能。该SDK同时封装了H5SDK以及微端js SDK,不但适用于pc端与移动端的浏览器,facebook的gameroom,同样适用于客户端如android和iOS中的webview调用原生功能。只需对接一套SDK,无需判断运行环境,SDK内部已做处理。
注:本文所提到的H5端是指运行在pc端或移动端的H5类型的游戏或应用,而微端是指在android或iOS客户端中的webview里面运行的H5类型的游戏或应用。

二.功能简介

2.1.登录

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

端类型 功能 支持渠道
H5端 无界面登录与有界面登录方式 Guest、Facebook、Google、应用内登录
微端(android) 同上 Google、Guest、Facebook
微端(iOS) 同上 Apple、Guest、Facebook

2.2.支付

各端支持的支付情况如下表所示:

端类型 功能 支持渠道
H5端 支付:支付是否可用,获取商品列表、购买商品等 Facebook、Web支付(Paypal、MOL、Xsolla等)
微端(android) 同上 Google
微端(iOS) 同上 Apple

2.4.数据收集

数据收集模块提供了数据收集的接口,多渠道灵活调用。数据收集包含了丰富的应用内的事件类型,还支持用户自定义事件类型。
各端支持的数据收集情况如下表所示:

端类型 功能 支持渠道
H5端 发送预定义事件及自定义事件 WING、Facebook
微端(android) 同上 WING、Appsflyer
微端(iOS) 同上 WING、Appsflyer

2.5.调试模式

调试模式提供窗口查看日志,帮助开发者更快的集成SDK与定位相关的开发问题。
各端支持的调试模式情况如下表所示:

端类型 开启调试模式方法
H5端 在WINGSDK后台添加测试设备
微端(android) 调用本文档的setDebugMode接口
微端(iOS) 调用本文档的setDebugMode接口

2.6 隐私政策

为了遵守欧盟近日发布的用户隐私政策,WINGSDK在用户首次登录时会显示用户隐私政策相关说明,用户需要同意才能进行下一步操作,在首次登录之后不会再出现此页面。此功能由WINGSDK内部处理,CP无需对接任何接口。

三.集成WINGPLUS H5 SDK

3.1.适用范围

WINGPLUS H5 SDK适用于HTML5类型的游戏或应用,比如在Facebook上线的页游,或者是同时拥有页游又有微端,而页游与微端功能有些功能不大相同但代码只有一套的游戏(比如支付,微端比H5端多了google/apple支付;而数据收集,微端比H5端多了appsflyer等渠道)。
WINGPLUS H5 SDK为这些游戏提供登录、支付、数据收集等基础功能,同时提供调试窗口,满足游戏能顺利运行的基本功能需求,更多的功能目前还在持续开发中。

3.2.如何集成

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

3.3.接口说明

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

3.3.1.初始化

初始化方法:

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

参数说明:

参数名 类型 必填 说明
appId string Y 应用ID
appKey string Y 应用秘钥
sdkType string N sdk类型:html5

示例:

3.3.2.登录

3.3.2.1.用户登录

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

说明:该方法分为不弹出窗口(明确指定了platform)和弹出窗口方式(platform不传值则弹出登录方式选择框)

参数说明:

参数名 类型 必填 说明
platform string N 见代码说明
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 Canvas游戏,sdk内部会根据游戏(Facebook后台的配置,参考第三方后台配置文档)链接中的from=fbcanvas参数来判断是否是Facebook Canvas游戏,调用方不需要设置platform参数

3.3.2.4.用户登出

方法:wingplus.user.logout();
说明:该方法是用来登出wingsdk的,此操作会删除sdk内部的一些缓存、登出第三方账号(如果可用)等。
参数:无
返回结果:无

3.3.3.支付

3.3.3.1.判断支付是否可用

方法:wingplus.pay.isPayServiceAvailable(callback);
参数说明:

参数名 类型 必填 说明
callback Object Y 回调函数,返回boolean结果

3.3.3.2.获取商品列表

方法:wingplus.pay.getProducts();

参数说明:

参数名 类型 必填 说明
success Object Y 成功回调函数
fail Object N 失败回调函数
cancel Object N 取消回调函数

返回结果参数说明:

参数名 类型 必填 说明
code number Y 见代码说明
msg string Y 结果描述
productList Object N 数组对象,获取到商品列表时不为空,包含以下属性
productId string Y 商品Id,购买时需要用到
productName number Y 商品名称
productDesc string N 商品描述
gameCurrencyAmount number N 该商品对应的游戏币数量(目前iOS不可用)

示例:

3.3.3.3.购买商品

方法:wingplus.pay.pay(params);

参数说明:

参数名 类型 必填 说明
channel string N 见支付类型对照表,目前仅H5端有效。channel字段为可选字段,传入该值则直接使用对应支付方式,不弹出支付方式选择窗口,否则弹出所有支付方式选择窗口。目前Facebook Cavas(Facebook页游)中有自动检测机制,可以不传该值,会默认直接使用Facebook支付,不弹出支付方式选择窗口
productId string Y 产品ID
extInfo string N CP 扩展信息字段,限长512(JSON格式),WING服务器到CP服务器发货通知时原样返回给CP。如果CP的通知发货地址是动态变化的(比如每个服务区的地址都不一致),可以通过此字段设置:参数格式为标准JSON,参数名为 deliverUrl,参考格式{ “deliverUrl”:” http://game.com/deliver.do”, “otherInfo”:”otherInfo”,“merId”:””}merId字段(选填),收款商户ID,使用场景:同一个支付渠道下有多个不同的收款验证信息(或收款帐号)。如果是 APPLE支付渠道,merId使用客户端bundleId
success Object Y 必选,支付成功回调函数
fail Object N 可选,支付失败回调函数
cancel Object N 可选,支付取消回调函数

返回结果参数说明:

参数名 类型 必填 说明
code number Y 见代码说明
msg string Y 结果描述
amount string Y 不为空,商品ID,支付金额
currency string Y 不为空,支付币种
quantity number Y 不为空,购买数量,目前一般都是1
platform string N 可能为空,只适用于微端,支付渠道
orderId string N 可能为空,只适用于微端,订单Id
productId string N 可能为空,只适用于微端,商品Id
payment_id string N 可能为空,只适用于H5端的FACEBOOK支付渠道
request_id string N 可能为空,只适用于H5端的FACEBOOK支付渠道
signed_request string N 可能为空,只适用于H5端的FACEBOOK支付渠道
status string N 可能为空,只适用于H5端的FACEBOOK支付渠道

示例:

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

3.3.5.公共参数设置

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

3.3.5.1.设置游戏用户id

wingplus.core.setGameUserId()

参数说明:

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

示例:

3.3.5.2.设置服务器id

wingplus.core.setServerId()

参数说明:

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

示例:

3.3.5.3.设置等级

wingplus.core.setLevel()

参数说明:

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

示例:

3.3.5.4.设置玩家昵称)

wingplus.core.setNickname()

参数说明:

参数名 类型 必填 说明 备注
nickname string Y 昵称

示例:

3.3.5.5.展示收藏指引页(目前仅chipsgames平台中mobile端可用)

wingplus.user.showCollectGuide()

示例:

3.3.6.数据收集

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

1. 以上流程图中涉及到的几个接口是有时序要求的,请参考流程图中的逻辑步骤进行设置:setServerId、setGameUserId、setLevel、ghw_user_import事件、ghw_user_create事件
2. 其它的事件如ghw_level_achieved、ghw_self_tutorial_completed等请根据对应业务逻辑,在对应业务发生时调用接口发送。

序号 事件(接口)名称 事件描述 事件作用 建议触发点 备注
1 setServerId 设置服务器ID 标记玩家当前所在的服务器,后台根据该字段统计每个服务器的数据 登录游戏服成功后
2 setGameUserId 设置玩家角色ID 标记玩家当前的游戏角色ID,后台根据该字段统计玩家的数据 登录游戏服成功后
3 setLevel 设置玩家当前等级 标记玩家当前的游戏角色等级 玩家等级发生变更后,如登录游戏服成功后、玩家完成升级后
4 setNickname 设置玩家昵称 标记玩家当前的游戏昵称 玩家设置昵称后
5 ghw_user_import 玩家登录游戏服 记录玩家登录游戏服的动作,后台根据该事件统计导入数、登录数、导入留存等数据 玩家登录游戏服成功后 需要先调用setServerId、setGameUserId、setLevel接口
6 ghw_user_create 玩家创建角色 记录玩家创建角色的动作,后台根据该事件统计创角数 玩家创建角色成功后 需要先调用setServerId、setGameUserId、setLevel接口
7 ghw_self_lv_x 更新关键等级 更新关键等级 关键等级到达时
8 ghw_level_achieved 更新玩家等级 更新玩家等级,后台根据此字段更新玩家等级 玩家达到新的等级时 需要先调用setLevel接口更新玩家等级
9 ghw_self_tutorial_completed 完成新手任务 完成新手任务 完成新手任务时

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

3.3.6.1.数据发送

方法:wingplus.track.trackEvent(WAEvent);

参数说明:

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

示例:

示例说明:setDefaultEventName方法用于设置发送事件的名称,GHW_PURCHASE为SDK定义的购买事件名称,所有SDK预定义的事件名称可以在下文的<事件常量>章节查看。

setDefaultValue为设置事件默认价值,
addDefaultEventValue为设置默认事件参数/值,其中SDK定义参数在下文<参数常量>章节可查看。
setChannelEventName为设置渠道自定义事件名称,用于发往第三方平台时更改事件命名。
setChannelEventValues为事件渠道自定义的参数/值,用于发往第三方平台时,替换默认事件参数。

3.3.6.2.预定义事件

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

3.3.6.2.1. ghw_initiated_purchase点击购买(虚拟货币)

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

3.3.6.2.2. ghw_purchase购买完成(虚拟货币)

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

参数名 类型 说明 必填 备注
itemName string 游戏内虚拟物品的名称/ID Y
itemAmount number 交易的数量 Y
price number 交易的总价 Y
3.3.6.2.3. ghw_level_achieved 等级增长事件

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

参数名 类型 说明 必填 备注
score number 账户分数 N
fighting number 战斗力 N
3.3.6.2.4. ghw_user_create 创建角色

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

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

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

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

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

3.3.6.2.6. ghw_self_tutorial_completed完成新手任务

说明:完成新手任务时

参数 无

3.3.6.2.7. ghw_self_lv_x 到达关键等级时

说明:到达关键等级时,如ghw_self_lv_1、ghw_self_lv_3、ghw_self_lv_10

参数 无

3.3.6.3.自定义事件

自定义事件目前只支持事件名和累加值,见示例。

示例:

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

3.3.6.4.事件对象

全局对象:wingplus.track.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 具体参数值

示例:

4)设置多个事件参数
方法: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.7.调试

3.3.7.1 H5端调试模式

H5端的调试模式具体打开方式如下:
在WING SDK 管理后台 设置》测试设备 中添加设备 Client ID 到测试设备列表(如下图所示),可打开LOG 日志窗口。

添加测试设备

添加测试设备后,开发时浏览器打开开发者模式(一般浏览器快捷方式为F12),在控制台即可看到相关操作日志,开发者可以根据日志快速排查问题,提高效率。

3.3.7.2 微端调试模式

方法:wingplus.core.setDebugMode(boolean);
说明:开启/关闭微端的调试模式 (默认是关闭的)。
参数:boolean 是否为调试模式,true为调试模式,false非调试模式(默认)
返回结果:无

3.3.8.常量

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

3.3.8.1.事件常量

以下是SDK预定义事件。

事件对象:wingplus.track.WAEvent.WA_EVENT_TYPE

事件名称对应常量:

事件名称 说明 备注
GHW_INITIATED_PURCHASE 点击购买 发送该事件前必须调用wingplus.track.setLevel方法设置等级
GHW_PURCHASE 购买完成 发送该事件必须要设置ITEM_NAME、ITEM_AMOUNT、PRICE、LEVEL参数或调用wingplus.track.setLevel方法
GHW_USER_CREATE 创建角色 必须要设置NICKNAME、REGISTER_TIME参数,可以有选择的设置ROLE_TYPE、GENDER、VIP、STATUS、BIND_GAME_GOLD、GAME_GOLD、FIGHTING等以上参数
GHW_USER_IMPORT 导入用户 必须要设置IS_FIRST_ENTER
GHW_LEVEL_ACHIEVED 等级或分数 必须要提前调用wingplus.track.setLevel方法必须要设置SCORE、FIGHTING参数
GHW_SELF_ 用于自定义事件 事件名称可以为 GHW_SELF_ + 自定义字符串。如:wingplus.track.WAEvent.WA_EVENT_TYPE. GHW_SELF_+”custom_event_name”

3.3.8.2.参数常量

以下是SDK预定义事件的参数定义
参数对象:wingplus.track.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.8.3.第三方平台常量

参数对象:wingplus.track.WAEvent.TRACKING_CHANNEL

参数常量:

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

四.代码说明

4.1.登录类型对照表:

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

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 失败
401 请求未认证:访问受限资源是缺少认证信息,或者认证未通过
403 禁止访问:由于应用上下文原因或请求端上下文的原因被禁止访问资源,例如IP限制等
404 找不到被访问资源:接口不存在、页面不存在或对应的业务实体找不到
500 服务器内部故障
501 所请求接口或页面未实现
4010 无效appId: appId不存在或未开启
4011 无效osign:osign校验失败
4012 请求已过期:ots校验失败
4013 第三方平台验证失败
4014 访客登录验证失败,登录验证失败
4016 prePlatform验证失败
4017 用户不存在(没有找到)
4018 账户已经被其他用户绑定
4019 无效orderId
4020 订单验证失败
4022 闪退发送报告重复
4023 未找到渠道信息
4024 不可以执行解绑操作
4025 汇率转换失败
4026 支付渠道已关闭
4029 登录渠道已关闭
5001 切换到匿名
5002 facebook的objectType不能为空
5004 facebook token为空
5005 该设备不能支付或者不允许支付
5006 支付过程中出错
-100 取消操作
-200 SDK没有初始化
-202 没有登录
-203 登录失败
-204 登录没有获取到相应的权限
-211 登录的平台账户和当前用户不匹配
-401 设备不支持
-402 网络不可用
-509 支付:订单时间间隔限制(在特定的时间内重复下订单)

Leave a Reply