WINGSDK_Android使用指南(v3.5.1)

WINGSDK_Android使用指南(v3.5.1)

wapublisher No Comment
Android对接文档

一、集成SDK到项目

WINGSDK进行了抽象层与实现层的分离,整体流程如下图所示:
android-集成SDK到项目

1.1 Eclipse项目集成方法

1、打开Eclipse项目;
2、将android-support-v4.jar(必须23及以上版本)包添加到libs目录;
3、将android-support-v13.jar(必须23及以上版本)包添加到libs目录;
4、将wa_sdk_interface_vXX.jar包添加到libs目录;
5、导入support-v7-appcompat库(必须23及以上版本),并关联到项目;
6、导入support-v7- cardview库(必须23及以上版本),并关联到项目
7、拷贝资源文件“wa_sdk_intf_config.xml”到根目录的assets文件夹(没有则新建)下面;
8、编译,调用接口开发。

Eclipse关联库项目的方法如下:

第一步:打开eclipse
第二步:菜单栏>File>Import…,导入库项目到workspaces
第三步:选中自己的Android项目,菜单栏→Project(或者右键)→Properties→在打开的对话框中选中“Android”选项卡→在Library项中点击添加→在弹出窗中选择库项目→Ok→Ok,这样就将SDK导入到了自己的项目中了。
android-集成SDK到项目2

1.2 Android Studio项目集成方法

1、将wa_sdk_interface_vXX.jar添加到项目程序Module的libs目录下;
2、配置依赖,在build.gradle文件的dependences内增加依赖配置;

3、拷贝资源文件“wa_sdk_intf_config.xml”到根目录的assets文件夹(没有则新建)下面。
4、编译,调用接口开发。

1.3 WINGSDK配置

1.3.1 WINGSDK基本配置

在AndroidManifest.xml中添加以下声明:
在不同的应用配置的参数值不相同,需要申请相应资源。

注:WINGSDK中使用到的权限如下(可以不配置,打包工具会自动添加):

1.3.2 Google相关配置

如果不需要Google渠道,请忽略此章节
在value/string.xml中添加公钥字符串资源:

获取Google public key

第一步:打开Google Play的Developer Console并进行登录。确认你登录的账号是已经或者将要发布应用的账号
第二步:在Application Details页面,点击 Services and APIs 链接
第三步:在Services and APIs 页面的Licensing and In-App Billing部分,就可以找到你的public key

Google后台配置参考(定义包名及获取SHA-1指纹):Google后台应用配置
如果需要使用Google Game Service服务,还需要在value/string.xml中添加加以下字符串资源:
如果不需要使用Google Game Service,可以忽略此章节

说明:字符资源的值是Google Game Service的APP ID,需要Google开发者控制台创建游戏服务获得。

1.3.3 Facebook相关配置

如果不需要Facebook渠道,请忽略此章节
使用打包工具打包过程中需要配置Facebook App id。

Facebook 后台配置参考Facebook第三方后台配置

1.3.4 AppsFlyer相关配置

如果不需要AppsFlyer渠道,请忽略此章节
在AndroidManifest.xml中添加以下声明

1.3.5 Chartboost相关配置

如果不需要Chartboost渠道,请忽略此章节
在AndroidManifest.xml中添加声明

特别提醒:以上所有配置的android:name字段值都必须和文档一致,android:vlaue值由各应用申请的资源而定。

1.3.6 VK相关配置

在value/string.xml中添加加以下字符串资源:
如果不需要使用VK渠道功能,可以忽略此章节

说明:APP_ID需要在VK的开发者管理后台创建应用后获得。

1.4 代码混淆配置

打包apk混淆代码配置中增加以下配置
-keep class com.wa.sdk.** { *; }

二、WINGSDK使用

2.1 SDK初始化

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

注意:使用SDK之前必须调用这个接口进行初始化,且必须在第一个Activity的onCreate()方法中调用

2.2 开启/关闭调试模式

WINGSDK默认是关闭调试模式的,开启调试模式可以在IDE的Logcat中查看到程序的Log信息,方便调试和测试。开启/关闭调试模式调用以下接口。

2.3、公共参数配置

公共参数必须严格按照文档进行配置,在后续的接口中会使用到这些公共的参数,没有按照要求配置会导致部分接口调用失败。

2.3.1 设置用户id

用户在登录之后将用户id设置到SDK中,如果使用了用户模块进行登录,这个接口不需要手动调用。

用户在选择服务器并且登录之后将用户gameUserId设置到SDK中以便于跟踪。

2.3.2 设置服务器ID

用户登录选服后,调用接口设置服务器id

注意:设置服务器ID的操作在每次选服后都需要进行。

2.3.3 设置用户等级level

设置游戏玩家的角色等级,调用接口:

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

2.3.4 设置ClientId

设置自定义的ClientId,调用接口:

注意:
1、clientId不是必设参数
2、一旦调用这个接口进行修改ClientId,以后SDK的ClientId将会保持这个不变。

clientId的作用:clientId用于跟踪设备,通过一套算法计算,可以看成是一个设备的唯一标识。CP可能会有自己的唯一标识,通过设置clientId,来达到WINGSDK后台和游戏后台唯一标识的统一。如不设置,SDK内部会自动通过算法算出。

三、公共模块功能

3.1调试Logcat工具使用

WINGSDK提供了调试信息显示的Logcat工具,使用这个工具测试人员不需要IDE环境就可以查看调试信息,工具可以看到应用的调试Log信息(不包含系统打印)。使用前必须确保手机的安全软件没有拦截该程序的悬浮窗口权限,使用调用以下接口:

3.1.1 显示Logcat工具入口悬浮按钮

3.1.2 隐藏Logcat工具入口悬浮按钮

注意:
1)Logcat工具入口悬浮按钮的生命周期依赖显示它的Activity,多个Activity中显示,需要在每个Activity中都调用一次显示悬浮按钮接口;
2)在Activity创建后只需要显示一次,Activity销毁后自动销毁在当前Activity创建的悬浮按钮,但其他Activity中显示的悬浮按钮不会消失。

3.1.3 向Logcat工具中增加一条日志

通过以下接口,可以向Logcat工具中增加一条日志,日志会在Log标签中显示

3.1.4 向Lgocat工具中增加一条事件日志

通过以下接口,可以向Logcat工具中增加一条事件日志,日志会在Event标签中显示

四、用户模块功能

用户模块的接口通过WAUserProxy类调用,使用用户模块接口需要在调用接口口的Activity的onActivityResult方法中添加如下代码:

4.1 登录功能使用

4.1.1设置登陆流程接口:

设置登录流接口可以设置在登录账号的时候,是否将登录的账号与该设备重新绑定,如果将该账号与设备进行了绑定,那么在当前设备可以通过匿名登录登录该账号。

登录流程有两种模式,在WAConstants类中定义,取值如下表:

名称 取值 备注
LOGIN_FLOW_TYPE_DEFAULT 1 登录的时候不会重新绑定设备
LOGIN_FLOW_TYPE_REBIND 2 登录时重新将新账号与当前设备绑定,如在游戏中切换账户,切换以后的匿名登录是以切换后的账户的身份进行登录。

4.1.2 用户登录接口

用户登录调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用接口的Activity
platform String Y 登录账户的平台类型 在WAConstants类中定义,详情请看下方登录平台取值
callback WACallback<WAloginResult> N 回调,用来返回登录结果 4.1.4 登录结果返回
extInfo extInfo N 额外信息 附表4.2:登录extInfo字段说明

登录平台取值:

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

4.1.3 登录对话框

SDK内置了一个包含所有支持的登录方式的一个对话框,通过调用以下接口打开对话框:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用接口的Activity
enableCache boolean Y 是否启用登录缓存,true为启用,false为关闭 如果开启登录缓存,那么调用这个接口的时候会看是否有登录记录,如果有,不会显示登录方式选择对话框,直接使用上一次的登录方式登录。
callback WACallback<WAloginResult> N 回调,用来返回登录结果

4.1.4 登录结果返回

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

WALoginResult字段说明

字段名 类型 说明 备注
code int 登录结果码 状态码说明
message String 登录结果消息
userId String WINGSDK用户id
token String WINGSDK用户token
platformUserId String 平台用户id
platformToken String 平台用户token
platform String 平台类型 当前登录的平台名称

4.1.5 用户登出

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

4.1.6 清除登录对话框登录方式缓存

使用内置的登录窗口进行登录,如果启用了缓存,SDK会缓存当前登录方式,下一次在启用缓存的前提下调用接口,会自动使用上一次登录方式登录,不再弹出登录窗口。这个接口可以清除掉缓存,重新弹出登录窗口,清除登录缓存,调用以下接口:

4.2 账户管理的使用

4.2.1 绑定第三方平台账户

绑定第三方平台账户后,可以使用第三方平台账户登录,防止账户信息丢失,绑定第三方平台账户,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用接口的Activity
platform String Y 绑定第三方平台账号的平台类型
extInfo String N 额外信息 预留字段
callback WABindCallback N 回调,用来返回绑定结果

4.2.2 查询已经绑定的第三方平台账户

通过以下接口,可以查询当前的账户已经绑定的第三方平台账户:

WAAccountResult字段说明:

字段名 类型 说明 备注
code int 结果码 状态码说明
message String 结果消息
platform String 绑定的平台类型
platformUserId String 平台用户id
accessToken String 平台用户token

4.2.3 解绑第三方平台在账户

通过以下接口,可以解绑已经绑定的第三方平台账户:

有以下情况之一者,不可解绑:
1.解绑的账户为WINGSDK平台的;
2.用户没有绑定的第三方平台账户的;
3.用户只绑定一个第三方平台账户,且用户没有与当前设备绑定的。

4.2.4 切换账户

使用以下接口可以快速切换登录的账户

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y
platform String Y 需要切换的账号类型 取值请看登录平台取值
callback WACallback<WALoginResult> N 回调 用来返回结果,4.1.4 登录结果返回

4.2.5 新建账户

新建账户后,新的账户会跟当前设备绑定,如果之前的账户没有绑定第三方平台账户,数据将会丢失。

4.2.6 使用账户管理页面

SDK内置了账户管理页面,打开这个内置的页面之前必须先登录,通过这个页面可以对账户进行管理操作,包括账号绑定、解绑、切换账户、新建账户。
参数说明:

参数名 类型 必填 说明 备注
activity Activity Y Activity对象
callback WAAccountCallback N 回调 onLoginAccountChanged(WALoginResult currentAccount)回调方法,在新建账号、账号切换时会回调这个方法,返回当前登录的账号信息。
onBoundAccountChanged(boolean binding, WABindResult result)回调方法,在绑定账户信息发生变更时会回调这个方法,每次变更都调用一次,CP可根据需要实现相应功能。

4.2.7 获取账户信息

SDK提供了获取指定平台的账户信息,可以通过以下接口获取:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台名称
callback WACallback<WAUser> N 回调 结果中包含平台用户的id,名称,头像等信息

附表4.1:Facebook登录权限对照表

权限 WAConstants中定义 类型 权限取值 说明
读取用户配置 FB_PERMISSION_PUBLIC_PROFILE read public_profile
读取好友列表 FB_PERMISSION_USER_FRIENDS read user_friends
发布权限 FB_PERMISSION_PUBLISH_ACTIONS write publish_actions 通过api层分享需要这个权限

附表4.2:登录extInfo字段说明

平台 格式 说明
FACEBOOK {
“permissionType”: “read”,
“permissions”: [
“public_profile”,
“user_friends”
]
}
1、Facebook登录需要自定义登录获取权限的时候extInfo传值;
2、permissionType分为read和write;
3、附表4.1:Facebook登录权限对照表
WINGSDK {
“appSelfLogin”: true,
“appUserId”: “12345”,
“appToken”: “o1akkfjia81FMvFSO8kxC96TgQYlhEEr”,
“extInfo”: “extInfo String”
}
1、WINGSDK平台应用内登录,所谓的应用内登录,是指应用本身有登录系统,应用登录自己的后台后拿到用户信息后登录WA后台,创建WA用户的过程,可选,默认匿名登录
2、字段说明:
appSelfLogin: 是否应用内登录(boolean)
appUserId: 应用userId(String)
appToken: 应用Token(String)
extInfo: 额外数据(String),这个数据WA后台在想应用后台验证的时候,会通过回调接口传递到应用服务器。

1、appUserId和appToken是游戏提供给SDK,SDK后台根据这两个值去游戏后台校验;
2、appToken:根据游戏验证用户登录状态的方式,把参数传到SDK后台,如果有多个参数,组成JSON放入appToken,SDK会根据这些参数到游戏后台校验,提供的验证登录的接口就是用于验证

五、支付模块功能

5.1 支付服务是否可用

通过以下接口可以获取支付服务是否可用,返回boolean类型结果,true为可用,false为不可用:

参数说明:

参数名 类型 必填 说明 备注
context Context Y 上下文

5.2 初始化

5.2.1 初始化接口

支付平台进行初始化,sdk内部会对所有已经选择的支付平台做初始化,初始化调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
context Context Y Context对象
callback WACallback<WAResult> N 回调方法,返回初始化结果 状态码说明

支付的初始化建议在调用Activity的onCreate中初始化。

5.2.2 支付结果传递配置

在调用接口的onActivityResult方法内调用以下接口

示例:

5.2.3资源释放

释放资源,在不再使用支付时,可以清理所有支付渠道所占用的资源,在调用接口Activity的onDestroy方法内调用以下接口

示例:

5.3 查询库存商品

查寻库存商品,调用以下接口,返回WINGSDK平台的商品id(注意:这里返回的是WINGSDK平台的商品id,并非第三方平台的商品id,WINGSDK平台的商品id可以从WASkuResult中的WAsdkDetail中的sku获得:

参数说明:

参数名 类型 必填 说明 备注
callback WACallback<WASkuResult> N 回调方法,结果返回

5.4 购买支付

购买指定商品,会直接弹出google购买窗口(如果该商品有且只有google支付渠道),或者弹出支付渠道选择窗口(如果有除google之外的渠道),选择支付方式后进行支付。调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用Activity
waProductId String Y WINGSDK商品的id 必须WINGSDK平台的商品id
extInfo String N 额外信息,该信息会在支付成功后原样通知到CP服务器,CP用于检验。如果CP的通知发货地址是动态变化的(比如每个服务区的地址都不一致),可以通过此字段设置:参数格式为JSON,参数名为 deliverUrl,参考格式
{
“deliverUrl”:” http://game.com/deliver.do”,
“otherInfo”:”otherInfo”
}
预留字段
callback WACallback<WAPurchaseResult> N 回调方法,结果返回

注意:如果需要横竖屏适配,请在AndroidMainifest.xml中,弹出购买窗口的activity中添加如下语句:

六、社交模块功能

6.1 初始化配置

使用社交模块功能,需要在所有使用社交模块功能的Activity中,在onActivityResult方法中增加代码:

示例:

6.2 分享功能

分享调用以下接口,支持分享链接、图片、视频、Facebook OpenGraph:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 分享的平台 分享到哪个平台
shareContent WAShareContent Y 分享内容
shareWithAPI boolean Y 是否通过API分享 如果所选平台支持API分享,设置为true时直接通过API层分享,没有界面
extInfo String N 额外信息 预留字段
callback WACallback<WAResult> N 回调方法,结果返回

6.2.1 分享链接内容实体WAShareLinkContent

WAShareLinkContent字段说明

字段名 类型 必填 说明 备注
contentUri Uri Y 链接
peopleIds List N 分享好友ID
placeId String N 地址id
ref String N 添加到引用链接中的参数值
contentTitle String N 连接标题
contentDescription String N 链接描述
imageUri Uri N 配图

6.2.2 分享图片内容实体WASharePhotoContent

WASharePhotoContent字段说明

字段名 类型 必填 说明 备注
contentUri Uri N 内容Uri
peopleIds List<String> N 分享好友ID
placeId String N 地址id
ref String N 添加到引用链接中的参数值
photos List<WASharePhoto> Y 图片列表 不能超过12MB,而且列表不能为空,至少一张图片

WASharePhoto字段说明

字段名 类型 必填 说明 备注
bitmap Bitmap Y 图片Bitmap对象 和imageUri两个必选一个
imageUri Uri Y 图片Uri 和bitmap两个必选一个
userGenerated String N 未使用
caption String N 图片描述

6.2.3 分享视频内容实体WAShareVideoContent

WAShareVideoContent字段说明

字段名 类型 必填 说明 备注
contentUri Uri N 内容Uri
peopleIds List<String> N 分享好友ID
placeId String N 地址id
ref String N 添加到引用链接中的参数值
contentDescription String N 视频描述
contentTitle String N 视频标题
previewPhoto WASharePhoto N 视频缩略图
video WAShareVideo Y 视频 不能超过12MB

WAShareVideo字段说明

字段名 类型 必填 说明 备注
localUri Uri Y 视频Uri

6.2.4 分享OpenGraph对象(Facebook)

WAShareOpenGraphContent字段说明

字段名 类型 必填 说明 备注
action WAShareOpenGraphAction Y action
previewPropertyName Y 预览属性名称

6.3 应用邀请功能

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 发送邀请的平台 发布邀请信息的平台
appLinkUrl String Y 分享链接
previewImageUrl String Y 预览图片url地址
callback WACallback<WAResult> N 回调方法,结果返回

6.4 游戏邀请功能

6.4.1 查询可邀请好友列表

游戏邀请只能邀请没有玩过当前游戏的好友,称为可邀请好友,查询可邀请的好友调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台名称 所查询的平台
duration long Y 过滤时间间隔 当过滤时间间隔大于0时,在这个时间间隔内不会出现已经发出邀请的好友
callback WACallback< WAFriendsResult> N 回调方法,结果返回

6.4.2 游戏邀请

WingSDK 3.5.1版本开始,使用8.7 发送请求接口代替
发送游戏邀请请求调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台名称 发出邀请的平台
title long Y 标题
message String Y 消息内容
ids List<String> Y 可邀请好友的id列表 6.4.1 查询可邀请好友列表
callback WACallback<WAInviteResult> N 回调方法,结果返回

6.4.3 邀请成功记录

成功邀请好友后,调用以下接口向服务器记录邀请信息:

参数说明:

参数名 类型 必填 说明 备注
context Context Y 上下文
platform String Y 平台名称 发出邀请的平台
requestId String Y 邀请请求id 没有的可以传空字符(如VK)
recipients Collection<String> Y 邀请成功好友的id列表
callback WACallback<WAResult> N 回调方法,结果返回

6.4.4 邀请安装奖励

通过邀请安装使用的用户,安装后需要通知服务器对邀请人进行奖励,需要在游戏启动后登录并且选服后调用以下接口:

注意:这个接口必须在用户登录并且选服后调用。采用platform指定平台方式登录或者绑定platform指定的平台后,均可以调用该接口。
参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台名称 邀请的平台
callback WACallback<WAResult> N 回调方法,结果返回

6.4.5 邀请事件奖励

通过邀请安装使用的用户,在触发定义的特定事件,需要通知服务器奖励邀请人,比如等级达成、充值等,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台名称 邀请的平台
eventName String Y 事件名称 事件名称必须后台已经定义
callback WACallback<WAResult> N 回调方法,结果返回

6.4.6 查询好友

查询指定平台正在玩游戏的好友列表,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台名称 查询好友的平台
callback WACallback<WAFriendsResult> N 回调方法,结果返回

6.4.7 查询Facebook Graph Object

Facebook的礼物就是在Facebook控制台创建的Graph Object,查询礼物列表的时候调用这个接口,这个接口只针对Facebook平台

Facebook后台新建礼物(Open Graph Object)参考:Facebook后台新建礼物
参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
objectType String Y Object类型 Facebook控制台预定义
callback WACallback<WAFBGraphObjectResult> N 回调方法,结果返回

6.4.8 Facebook赠送礼物

WingSDK 3.5.1版本开始,使用8.7 发送请求接口代替
Facebook用户向正在玩游戏这个游戏的好友赠送礼物,调用以下接口:

参数说明

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
title String Y 标题
message String Y 消息内容
objectId String Y Object id,赠送的礼物id Facebook控制台预定义
receipts List<String> Y 接收者id列表 6.4.6 查询好友
callback WACallback<WAGiftingResult> N 回调方法,结果返回

6.4.9 Facebook索要礼物

WingSDK 3.5.1版本开始,使用8.7 发送请求接口代替
Facebook用户向正在玩这个游戏的好友发出索要礼物的请求,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
title String Y 标题
message String Y 消息内容
objectId String Y Object id,索要的礼物id Facebook控制台预定义
receipts List<String> Y 索要好友id列表 6.4.6 查询好友
callback WACallback<WAGiftingResult> N 回调方法,结果返回

6.4.10 Facebook查询收到的礼物

Facebook用户查询好友赠送给自己的礼物,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
callback WACallback<WAFBGameRequestResult> N 回调方法,结果返回

6.4.11 Facebook查询向自己索要礼物的请求

Facebook用户查询好友向自己索要礼物的请求,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
callback WACallback<WAFBGameRequestResult> N 回调方法,结果返回

6.4.12 Facebook删除请求

Facebook中用户收到的礼物,好友向自己索要礼物的请求都是一个Facebook的请求,收取礼物和拒绝赠送礼物的时候,需要删除掉对应的请求。删除请求调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
requestId String Y 请求id
callback WACallback<WAResult> N 回调方法,结果返回

七、Game Service功能

7.1 登录Game Service

登录Game Service调用接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用的Activity
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
callback WACallback<WAPlayer> N 回调方法,结果返回 WAPlayer是平台返回的玩家

7.2 登出Game Service

登出Game Service调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 要登出的平台 平台类型在WAConstants类中定义,目前支持Google平台

7.3 成就解锁

标准类型的成就是一次性解锁,解锁调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
id String Y 成就id
callback WACallback<WAUpdateAchievementResult> N 回调方法,结果返回

7.4 分步成就进度增加

分步类型成就是可以分步进行解锁的,进度增加会在原来的进度上完成递增,无需知道当前的进度,进度递增调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
id String Y 成就id
numSteps int Y 递增的步数 0<numSteps<成就总分步数
callback WACallback<WAUpdateAchievementResult> N 回调方法,结果返回

7.5 分步成就进度设置

分步类型成就除了可以使用7.4 分步成就进度增加实现进度递增外,也可以使用以下接口直接设置进度:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
id String Y 成就id
numSteps int Y 成就步数 当且仅当:已完成进度<numSteps<成就总分步数 是有效
callback WACallback<WAUpdateAchievementResult> N 回调方法,结果返回

7.6 显示隐藏成就

隐藏状态下的成就不能解锁,需要显示后才能解锁操作,显示隐藏的成就调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
id String Y 成就id
callback WACallback<WAUpdateAchievementResult> N 回调方法,结果返回

7.7 展示成就列表

展示成就列表是打开自带的页面,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用Activity
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台

7.8 加载成就列表

通过以下接口,可以加载所有成就的列表:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持Google平台
forceReload boolean Y 是否强制重新加载
callback WACallback<WALoadAchievementResult> N 回调方法,结果返回 结果实体类WALoadAchievementResult中含有成就数据List对象,成就数据实体类为WAAchievement

WAAchievement字段说明:

参数名 类型 说明 备注
achievementId String 成就id
name boolean 成就名称
type int 成就类型 类型取值为WAAchievement定义的静态变量,只能是 TYPE_STANDARD或 TYPE_INCREMENTAL
state int 成就状态 状态取值为WAAchievement定义的静态变量,只能是STATE_UNLOCKED, STATE_REVEALED, 或 STATE_HIDDEN
currentSteps int 当前进度 仅对分步成就有意义,即type取值为TYPE_INCREMENTAL时
description String 成就详细描述
formattedCurrentSteps String 用户解锁成就已经完成的步数 格式化为当地语言的字符串
formattedTotalSteps String 解锁成就还需要完成的步数 格式化为当地语言的字符串
lastUpdatedTimestamp long 上一次更新时间
player WAPlayer 玩家信息
revealedImageUri Uri 隐藏图标
totalSteps int 总步数 仅对分步成就有意义,即type取值为TYPE_INCREMENTAL时
unlockedImageUri Uri 未解锁图标
xpValue long XP值

八、游戏社区功能

8.1 通过Group id查询Group详情

通过Group id查询Group详情,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
gids String[] Y 需要查询的group id列表
callback WACallback<WAGroupResult> N 回调方法,结果返回 结果实体类WAGroupResult中含有Group数据Map对象,Group数据实体类为WAGroup

WAGroup字段说明:

参数名 类型 说明 备注
gid String group id
name String group名称
screen_name String group screen_name
is_closed int 是否封闭 0 – 开放
1 – 封闭
2 – 私有
is_admin int 当前用户是否管理员 0 – 非管理员
1 – 管理员
admin_level int 管理员级别 1 – 主席
2 – 编辑
3 – 管理员
is_member int 当前用户是否该group成员 0 – 不是group的成员
1 – 是group的成员
type String 类型 group — group
page — public page
event — event
photo String group图片
photo_medium String group图片,中尺寸
photo_big String group图片,大尺寸
city WAPlace 城市
country WAPlace 国家
place WAPlace 地址
description String group描述
wiki_page String wiki地址
members_count int 成员数
can_post int 是否可以发布文章 0 – 不可以发布
1 – 可以发布
can_see_all_post int 是否可见所有文章 0 – 不可见
1 – 可见
activity String Activity
status String 状态
contacts String 联系信息
platform String 平台

8.2 查询当前应用关联的Group

一个应用只能关联一个Group,通过以下接口可以查询当前应用关联的Group详细信息:

参数说明:

参数名 类型 必填 说明 备注
context Context Y Context对象
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义
callback WACallback<WAGroupResult> N 回调方法,结果返回 结果实体类WAGroupResult中含有Group数据Map对象,Group数据实体类为WAGroup

8.3 查询当前用户已加入的Group

查询当前用户加入的Group详细信息调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义
callback WACallback<WAGroupResult> N 回调方法,结果返回 结果实体类WAGroupResult中含有Group数据Map对象,Group数据实体类为WAGroup

8.4 查询当前用户是否为指定Group的成员

查询当前的用户是否为指定的某个Group的成员,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
groupId String Y Group id
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义
callback WACallback<WAGroupResult> N 回调方法,结果返回 结果实体类WAGroupResult中含有Group数据Map对象,Group数据实体类为WAGroup

8.5 加入Group

加入指定的某个Group,调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
groupId String Y Group id
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义
callback WACallback<WAResult> N 回调方法,结果返回 返回成功的结果只代表请求发送成功,但是未必加入成功,对于封闭的和私有的Group是不能加入的

8.6 进入Group详情页

进入Group的详情页面,调用以下接口:

如果客户端已经安装platform指定平台的app客户端,将会进入到app客户端详情页面,如果没有安装,则打开网页详情页。

参数说明:

参数名 类型 必填 说明 备注
context Context Y Context对象
platform String Y 平台类型 平台类型在WAConstants类中定义,目前支持VK平台
groupUri String Y 打开Group的uri VK平台为screen_name字段值
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义

8.7 发送请求接口

该接口从SDK 3.5.1版本开始启用
发送请求接口向平台好友发送请求,请求包括普通请求、游戏邀请、赠送礼物、索要礼物等,发送请求调用以下接口:

参数说明:

参数名 类型 必填 说明 备注
activity Activity Y 调用Activity对象
platform String Y 平台类型 平台类型在WAConstants类中定义
requestType String Y 请求类型 请求类型默认的在WAConstants下有定义,请参考表8.7.1 请求类型
title String Y 标题 部分平台需要显示
message String Y 说明文字 部分平台需要显示
objectId String N 对象id 部分请求类型必填,比如发送礼物,为礼物对象id
receiptIds List<String> Y 接收者id 根据平台而定,有些平台支持一次发送请求给多个用户,有些平台一次只能发送给一个用户。VK平台一次只能发送一个用户
callback WACallback<WARequestSendResult> N 回调 结果返回
extInfo String N 额外数据信息 扩展字段,根据各个平台需要定义

WARequestSendResult字段说明:

参数名 类型 必填 说明 备注
requestId String Y 平台生成的请求id 部分平台会为空或只是网络请求id
recipients String Y 接收者id列表 返回一个或者多个

表8.7.1 请求类型

变量名 取值值 说明 备注
REQUEST_INVITE INVITE 邀请
REQUEST_REQUEST REQUEST 普通请求
REQUEST_GIFT_SEND GIFT_SEND 发送礼物 objectId不能为空
REQUEST_GIFT_ASK GIFT_ASK 索要礼物 objectId不能为空

注:vk平台测试游戏邀请功能需要申请权限,可以把请求类型设置成REQUEST_REQUEST来测试普通邀请,带申请权限通过后改成REQUEST_INVITE来测试。关于vk邀请功能的业务流程图如下:
vk上线流程图

九、数据收集模块功能

9.1 在线时长

SDK统计在线时长,在每个Activity的onResume()方法中调用以下接口:

在每个Activity的onPause()方法内部调用以下接口:

示例:

9.2事件数据的发送

第一步 构建GhwEvent对象

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

第二步 发送数据

调用第一步创建GhwEvent对象的trackEvent(Context)方法发送数据

或者调用以下接口发送:

9.3 WAEvent.Builder的接口方法介绍

9.3.1 设置默认的事件名称

设置该事件的事件名称,WINGSDK内置了应用内事件,请参考附表9.1:SDK预定义事件名

9.3.2 设置渠道自定义事件名称

如果某个渠道需要跟默认的事件名称有不一致的需求,可以在这里自定义该渠道特定的事件名称

注意:
1、AppsFlyer预定义的事件名称和WINGSDK预定义的事件名称已经做了映射(例如: ghw_login <-> af_login),用户无需再手动自定义。
2、如果不进行设置,所有的渠道将采用设置的默认值。

9.3.3 设置默认累加值

设置事件用于累加数字,比如购买的金额等

9.3.4 设置渠道自定义累加值

如果渠道有特定的值累加,可以通过这个接口设置:

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

9.3.5 设置事件默认的参数/值

调用这个接口设置事件所需要的参数,设置的方法有两种:
第一种,将参数放入Map,设置Map为参数

第二种:逐一增加参数名-值对

9.3.6 设置事件渠道自定义的参数/值

如果某个渠道需要自定义参数,可以通过这个接口设置,设置的方法有两种
第一种,将参数放入Map,设置Map为参数

第二种:逐一增加参数名-值对

注意:
1)AppsFlyer预定义的参数名称和WINGSDK预定义的参数名称已经做了映射,用户无需再手动自定义。
2)如果不进行设置,所有的渠道将采用设置的默认值。

9.3.7 禁用渠道

如果想该事件不发送到某个渠道,可以调用以下接口禁用某个渠道

注意:
1、默认情况下是所有渠道都发送

以下是一个代码例子,仅供参考:

9.4 SDK预定义事件

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

9.4.1 ghw_complete_registration注册帐号

说明:注册帐号完成后调用。

参数名 类型 说明 必填 备注
accountType String 账户类型 N
gender int 性别 N 0、女
1、男
2、未知
age int 年龄 N
success boolean 是否成功注册 N

9.4.2 ghw_login登录游戏

说明:登录游戏后调用。
无参数。

9.4.3 ghw_initiated_payment点击充值

说明:点击充值时后调用。
无参数.

注意:Google应用内购买已经集成该事件

9.4.4 ghw_payment充值完成(真实货币)

说明:充值完成后调用(成功的情况下)。

参数名 类型 说明 必填 备注
transactionId String 交易的流水号 Y
paymentType String 支付类型(平台) Y
currencyType String 货币类型 Y
currencyAmount float 现金额 Y 充值时支付的现实货币金额
virtualCoinAmount float 虚拟游戏币 Y 充值获得虚拟货币数量
virtualCurrency String 虚拟游戏币类型 N
iapId String 道具ID N 充值获取的的道具id
iapName String 道具名称 N 充值获取的的道具名称
iapAmount int 道具数量 N 充值获取的的道具数量
level int 账户级别 N

提示:如果累加参数value传值,请传入和currencyAmount字段值相等。

9.4.5 ghw_initiated_purchase点击购买

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

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

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

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

9.4.7 ghw_level_achieved 等级增长事件

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

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

9.4.8 ghw_add_to_cart添加到购物车

说明:统计玩家添加到购物车。

参数名 类型 说明 必填 备注
price float 价格
contentType String 道具类型
contentId String 道具ID
currencyType String 货币类型
quantity int 数量

9.4.9 ghw_add_to_wishlist添加到心愿单

说明:统计玩家添加到心愿单事件。

参数名 类型 说明 必填 备注
price float 价格 Y
contentType String 道具类型 N
contentId String 道具ID Y
currencyType String 货币类型 N
quantity int 数量 N

9.4.10 ghw_search搜索

说明:统计玩家搜索事件。

参数名 类型 说明 必填 备注
contentType String 搜索内容类型 N
searchString String 搜索关键字 Y
success boolean 是否搜索成功 Y

9.4.11 ghw_spent_credits使用信用点消费

说明:统计玩家使用信用点消费事件。

参数名 类型 说明 必填 备注
price float 价格 Y
contentType String 物品类型 N
contentId String 物品ID Y

9.4.12 ghw_achievement_unlocked完成解锁事件

说明:统计玩家解锁事件。

参数名 类型 说明 必填 备注
description String 描述 N

9.4.13 ghw_content_view查看内容

说明:统计玩家查看内容事件。

参数名 类型 说明 必填 备注
price float 价格 Y
contentType String 物品类型 N
contentId String 物品ID Y
currencyType String 货币类型 N

9.4.14 ghw_share分享事件

说明:统计玩家分享事件。

参数名 类型 说明 必填 备注
description String 描述

9.4.15 ghw_invite邀请事件

说明:统计玩家邀请事件。

参数名 类型 说明 必填 备注
description String 描述 N

9.4.16 ghw_re_engage重新连接服务器

说明:统计游戏重新连接到服务器事件。(断线重连)

参数名 类型 说明 必填 备注
description String 描述 N

9.4.17 ghw_update更新游戏

说明:统计玩家更新游戏事件。
无参数(待定)

9.4.18 ghw_opened_from_push_notification打开推送通知

说明:统计玩家打开推送通知事件。
无参数

9.4.19 ghw_user_create 创建角色

说明:创建游戏角色

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

9.4.20 ghw_user_info_update更新用户信息

说明:更新用户资料

参数名 类型 说明 必填 备注
roleType int 角色类型 N
nickname String 昵称 N
vip int 等级 N

9.4.21 ghw_gold_update货币状况更新

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

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

9.4.22 ghw_task_update玩家任务统计

说明:玩家任务信息统计

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

9.4.23 ghw_user_import导入用户事件

说明:导入用户事件–通过用户id在后台查找
无参数

9.4.24 ghw_self_+自定义事件名称 自定义事件

说明:支持自定义事件的统计(待续)

注意:自定义的事件名称,必须以ghw_self_开头。

附表9.1:SDK预定义事件名

在WAEventType接口中定义

静态变量名称 事件名称 说明
COMPLETE_REGISTRATION ghw_complete_registration 注册账号
LOGIN ghw_login 登录游戏
INITIATED_PAYMENT ghw_initiated_payment 点击充值,应用内购买已经集成该事件(SDK已集成,无需调用)
COMPLETE_PAYMENT ghw_payment 充值完成,应用内购买已经集成该事件(SDK已集成,无需调用)
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 等级或分数
ADD_TO_CART ghw_add_to_cart 加入购物车
ADD_TO_WISH_LIST ghw_add_to_wishlist 兴趣标记/愿望
SEARCH ghw_search 搜索内容
SPENT_CREDITS ghw_spent_credits 使用信用点消费
ACHIEVEMENT_UNLOCKED ghw_achievement_unlocked 完成解锁事件
CONTENT_VIEW ghw_content_view 内容查看
SHARE ghw_share 分享事件
INVITE ghw_invite 邀请事件
RE_ENGAGE ghw_re_engage 重新连接到游戏
UPDATE ghw_update 更新游戏
OPENED_FROM_PUSH_NOTIFICATION ghw_opened_from_push_notification 打开推送通知

附表9.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_AMOUNT iapName String 道具名称
IAP_NAME 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 String 货币类型
AMOUNT amount int 变更货币数
APPROACH approach String 变更途径
CUSTOM_PARAMETER user-define-* * 自定义字段

Leave a Reply