1.简介
UWingSDK是基于WingSDK功能实现的，支持快速接入的一套SDK方案。与传统的SDK接入不同，UWingSDK除了登录，大部分功能均无SDK后台限制，实现支持直接返回结果，直接调试接口，有效提升了接入效率。
2.快速开始
2.1.项目配置要求
API版本：最低API版本24，目标API版本35或以上
|
1 2 3 4 5 6 |
defaultConfig { applicationId "xxxxxx" minSdk 24 // 最低API版本24 targetSdk 35 // 目标API版本35或以上 } |
2.2.集成SDK
a、添加仓库地址
新项目配置：在项目根目录下的settings.gradle文件添加以下配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() //这里是UWingSDK的maven地址，内部声明支持http请求 maven { allowInsecureProtocol = true url "http://repo.wingsdk.cn:8081/repository/winga-group/" } } } |
旧项目配置：在项目根目录下的build.gradle文件添加以下配置：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
apply plugin: 'maven' allprojects { repositories { jcenter() //这里是UWingSDK的maven地址，内部声明支持http请求 maven { allowInsecureProtocol= true url "http://repo.wingsdk.cn:8081/repository/winga-group/" } } } |
b、在项目的app/build.gradle中添加SDK库：
|
1 2 3 |
implementation 'com.uwa.sdk:uwa-sdk-base:1.2.0' |
2.3.AndroidManifest.xml配置
在清单配置中添加下面配置，sdk_app_id和sdk_app_key具体值从对接表中获取
|
1 2 3 4 5 6 7 8 |
<meta-data android:name="com.wa.sdk.APP_ID" android:value="@string/sdk_app_id" /> <meta-data android:name="com.wa.sdk.APP_KEY" android:value="@string/sdk_app_key" /> |
2.4 Activity结果传递
重写Activity的onActivityResult方法，并调用下面方法
|
1 2 |
UWingSDK.onActivityResult(Activity activity, int requestCode, int resultCode, Intent data) |
参考示例
|
1 2 3 4 5 6 7 |
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); // 必须添加该方法，否则可能收不到登录和支付等回调结果 UWingSDK.onActivityResult(activity, requestCode, resultCode, data); } |
注意：若未添加该方法，可能导致无法接收登录、支付等功能的回调结果。
2.5 SDK初始化
在游戏页面Activity的onCreate中调用下面方法
|
1 2 |
UWingSDK.initialize(Activity activity, UWCallback<Void> sdkInitCallback) |
示例如下
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
//初始化sdk，在游戏页面的onCreate中调用 UWingSDK.initialize(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { Log.i(TAG, "初始化成功：" + message); } @Override public void onError(int code, String message, Void result, Throwable throwable) { Log.i(TAG, "初始化失败（" + code + "）：" + message); } }); |
注意
1.SDK初始化必须在游戏页Activity（不能是闪屏页）的onCreate()方法中调用。
2.其他所有SDK接口都必须在SDK初始化成功的情况下才能调用。
2.6 添加测试设备
在登录测试框中点击蓝色ClientID文字进行复制，把该内容提供的运营添加测试设备
如果未添加测试设备，会导致无法使用登录，支付等功能。
3. 功能接入
3.1 登录
接口效果：
点击复制clientId给运营添加测试设备后，点击“登录”即可正常登录并返回结果
调用方法：
|
1 2 |
UWingSDK.User.login(Activity activity, UWCallback<UWLoginResult> callback) |
登录结果UWLoginResult说明
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| userId | String | SDK的用户ID | |
| token | String | SDK的登录token | |
| platform | String | 当前登录平台（如GOOGLE、FACEBOOK） |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
UWingSDK.User.login(activity, new UWCallback<UWLoginResult>() { @Override public void onSuccess(int code, String message, UWLoginResult result) { String userId = result.getUserId(); String token = result.getToken(); String platform = result.getPlatform(); String msg = "登录成功. uid: " + userId + "\ntoken:" + token + "\nplatform:" + platform; Log.i("usdk",msg); } @Override public void onError(int code, String message, UWLoginResult result, Throwable throwable) { Log.i("usdk","登录失败（" + code + "）：" + message); } }); |
3.2 登出
调用方法
|
1 2 |
UWingSDK.User.logout(Activity activity) |
3.3 支付
接口效果：
点击“支付”后，游戏提供的发货通知接口将收到客户端购买的商品信息，接下来按照接入文档要求完成发货 （默认通知游戏后端的商品金额为1.99和USD币种，如需测试其他价格商品可以自行修改）
调用方法
|
1 2 |
UWingSDK.User.pay(Activity activity, String sdkProductId, String extInfo, UWCallback<UWPayResult> callback) |
方法参数说明
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| activity | Activity | 当前Activity | |
| sdkProductId | String | SDK的商品ID（非Google商品ID），从运营处获取 | |
| extInfo | String | 扩展信息，可用于透传（如透传订单号或发货接口），支付成功后会原样通知CP服务器 | |
| callback | UWCallback |
支付回调处理 |
支付结果UWPayResult说明
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| platform | String | 支付平台（如GOOGLE） | |
| sdkProductId | String | SDK的商品ID | |
| extInfo | String | 扩展信息 | 支付时传入的extInfo一致 |
| orderId | String | SDK订单ID | 部分支付方式没有 |
| currency | String | 货币类型（基准货币） | 由SDK后台定义 |
| price | long | 商品价格，单位微分（1元=1000000） | 由SDK后台定义 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
// SDK 商品ID，从运营提供的商品列表中获取商品对应的值 String sdkProductId = "1"; // 额外信息，可用于透传，比如透传订单号或发货接口。该信息会在支付成功后原样通知到 CP 服务器，供 CP 用于检验 String extInfo = "test_ext_info_1111"; UWingSDK.User.pay(activity, sdkProductId, extInfo, new UWCallback<UWPayResult>() { @Override public void onSuccess(int code, String message, UWPayResult result) { String productId = result.getSdkProductId(); // SDK商品ID String info = result.getExtInfo(); // 额外信息 String platform = result.getPlatform(); // 支付平台 String currency = result.getCurrency(); // 币种（由SDK后台定义的基准货币） long price = result.getPrice(); // 商品价格，单位微分，1元=1000000（由SDK后台定义的基准货币价格） String orderId = result.getOrderId(); // SDK订单ID Log.i("usdk","支付成功. ProductId:" + productId + ", ExtInfo：" + info); } @Override public void onCancel() { Log.i("usdk","支付取消."); } @Override public void onError(int code, String message, UWPayResult result, Throwable throwable) { Log.i("usdk","支付失败（" + code + "）: " + message + ". UWPayResult:" + result); } }); |
测试发货：具体查看《CP接口测试》章节中的 《内购商品发货接口》
3.4 事件发送
3.4.1 进入游戏服务器
调用方法：
|
1 2 |
UWingSDK.TrackEvent.enterGameServer(String serverId, String gameUserId, String nickname, int level) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| serverId | String | 服务器ID | |
| gameUserId | String | 游戏角色ID | 如果未创角，可以设置为 “-1” |
| nickname | String | 游戏角色名（昵称） | 如果未创角，可以设置为空字符串”” |
| level | int | 游戏角色当前等级 | 如果未创角，填入游戏角色初始等级，一般为 1 |
3.4.2 用户创建角色
调用方法：
|
1 2 |
UWingSDK.TrackEvent.createRole(String serverId, String gameUserId, String nickname, int level, long registerTime) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| serverId | String | 服务器ID | |
| gameUserId | String | 游戏角色ID | |
| nickname | String | 游戏角色名（昵称） | |
| level | int | 游戏角色当前等级 | |
| registerTime | long | 创建角色时的时间戳，单位为毫秒，长度13位 |
3.4.3 角色等级升级
调用方法：
|
1 2 |
UWingSDK.TrackEvent.levelUp(int currentLevel) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| currentLevel | int | 游戏角色当前等级 |
3.4.4 修改游戏角色名
调用方法：
|
1 2 |
UWingSDK.TrackEvent.updateNickname(String nickname) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| nickname | String | 更改后的游戏角色名（昵称） |
3.4.5 用户点击支付
调用方法：
|
1 2 |
UWingSDK.TrackEvent.clickToPay() |
3.4.6 新手任务完成
调用方法：
|
1 2 |
UWingSDK.TrackEvent.tutorialCompleted() |
3.5 客服中心
接口效果：
点击“退出游戏并回到游戏登录界面”，“绑定账号”，可以进行客服中心相关回调测试
在游戏设置页中添加该功能入口，入口的图标和名称可以参考使用下面。
文案内容：
Support Center（英语）
Central de Suporte（葡语）
图标 (下载)：
调用方法：
|
1 2 3 |
UWingSDK.User.showCustomerCenter(Activity activity, UWAccountCallbackV2 accountCallback) |
UWAccountCallbackV2 回调说明：
| 方法 | 说明 | CP需要处理 |
|---|---|---|
| onBackToGameLoginPage() | 账号切换成功 | 游戏客户端要回到登录页并重新登录 |
| onBindAccount(boolean isBound, String platform, Bundle bundle) | 账号绑定状态变更 | 无 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
UWingSDK.User.showCustomerCenter(activity, new UWAccountCallbackV2() { @Override public void onBackToGameLoginPage() { showMsg("游戏客户端需要退出游戏回到登录页"); } @Override public void onBindAccount(boolean isBound, String platform, Bundle bundle) { showMsg("账号绑定状态变更: " + (isBound ? "绑定" : "解绑") + ", 平台: " + platform + ", 其他信息: " + bundle); } }); |
3.6 AiHelp客服
接口效果（UWingSDK.AiHelp.show()）:
调用即打开AiHelp客服成功，如有需要可以点击“增加未读消息”修改UWingSDK.AiHelp.getUnreadMessageCount()接口返回的“未读消息”数目。
3.6.1 添加该功能入口
在游戏登录页中添加该功能入口，入口的图标和名称可以参考下面。
文案内容：
Support（英语）
Suporte（葡语）
图标(下载)：
3.6.2 判断是否开启
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.AiHelp.isEnable() |
返回结果说明：
true – 开启；false – 未开启
示例如下：
|
1 2 3 4 5 |
// 获取是否开启AiHelp boolean isEnable = UWingSDK.AiHelp.isEnable(); // 开启时显示AiHelp客服按钮，未开启时隐藏 btnAiHelp.setVisibility(isEnable ? View.VISIBLE : View.GONE); |
3.6.3 显示AiHelp客服
调用方法：
|
1 2 |
UWingSDK.AiHelp.show() |
3.6.4 获取未读消息
在SDK初始成功之后，调用方法：
|
1 2 |
UWingSDK.AiHelp.getUnreadMessageCount(UWCallback<Integer> callback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 |
// 在SDK初始成功之后，才可以调用该方法获取未读消息数 UWingSDK.AiHelp.getUnreadMessageCount(new UWCallback<Integer>() { @Override public void onSuccess(int code, String message, Integer result) { Log.i(TAG, "AiHelp未读消息数: " + result); // 更新未读数，大于0则需要显示红点，否则移除红点 mAiHelpRedDot.setVisibility(result > 0 ? View.VISIBLE : View.GONE); } }); |
3.7 游戏评价
3.7.1.判断是否开启
如果游戏有做评价发奖的引导页， 需要根据该状态决定是否弹出引导页，true需要弹出，false不需要弹出
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.GameReview.isEnable() |
示例如下：
|
1 2 3 4 5 |
//是否开启游戏评价 boolean isEnable = UWingSDK.GameReview.isEnable(); // 为 true 时才显示评价发奖的引导页 if (isEnable) showGameReviewGuide(); |
3.7.2.展示游戏评价弹窗
接口效果：
点击“提交好评”立即返回好评结果，如有好评发奖需求，研发可根据好评结果进行发奖处理（奖励发放过程游戏端自行处理即可，无需通过SDK）
调用方法：
|
1 2 |
UWingSDK.GameReview.show(Activity activity, UWGameReviewCallback gameReviewCallback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
UWingSDK.GameReview.show(activity, new UWGameReviewCallback() { @Override public void onSuccess(int action) { // 1-好评；2-打开客服；3-拒绝； if (action == UWGameReviewCallback.ACTION_COMMENT) { // 如果需要好评发奖，可以在这里通知发奖 Log.i("usdk","游戏评价成功"); } else if (action == UWGameReviewCallback.ACTION_OPEN_CUSTOMER) { Log.i("usdk","打开客服"); } else if (action == UWGameReviewCallback.ACTION_REFUSE) { Log.i("usdk","拒绝评价"); } } }); |
注意：如果有多个触发点的情况，各触发点相互独立，不需要规定它们之间的逻辑关系（比如不要规定A点评价了B点就不弹评价等）
3.8 退出游戏提示
拦截用户返回操作，弹出退出提示框，用户点击确认退出时，会finish所有Activity，并结束游戏进程
接口效果：
调用方法：
|
1 2 |
UWingSDK.showExitDialog(Activity activity, UWCallback<Void> callback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
// 返回手势拦截（建议使用该方式拦截返回手势，因为后续 目标 API 升级为 36（Android 16）时，onBackPress 需要也迁移到这种方式实现） getOnBackPressedDispatcher().addCallback(this, new OnBackPressedCallback(true) { @Override public void handleOnBackPressed() { // 退出游戏提示 UWingSDK.showExitDialog(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { // 用户点击确认后会先调用该回调，然后在内部执行退出应用 } }); } }); |
显示效果如下：
3.9 月卡功能
3.9.1.获取月卡信息
调用方法：
|
1 2 |
UWingSDK.Pass.getPassInfo(UWCallback<UWPassPlatformInfo> callback) |
月卡信息UWPassPlatformInfo说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| passStatus | int | 月卡状态：0-未激活；1-已激活 |
示例如下：
|
1 2 3 4 5 6 7 |
UWingSDK.Pass.getPassInfo(new UWCallback<UWPassPlatformInfo>() { @Override public void onSuccess(int code, String message, UWPassPlatformInfo result) { Log.i("usdk","月卡状态：" + (result.getPassStatus() == 1 ? "已激活" : "未激活") + "\n" + result); } }); |
3.9.2 月卡用户指引弹框
接口效果：
可以通过点击“取消激活”（模拟非月卡用户）或“激活用户”（模拟月卡用户）来决定接口返回结果，游戏可以根据不同返回结果进行相关处理
调用方法：
|
1 2 |
UWingSDK.Pass.showPassUserGuide(Activity activity, UWCallback<Void> callback) |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
UWingSDK.Pass.showPassUserGuide(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { Log.i("usdk","显示成功"); } @Override public void onError(int code, String message, Void result, Throwable throwable) { Log.i("usdk","显示失败：" + code + ", " + message); } }); |
3.10 代金券功能
游戏中在顶部数额旁边增加代金券数额显示，当代金券信息返回关闭状态时需要隐藏，返回开启才显示
3.10.1.获取代金券信息
在用户进服时调用该接口获取代金券信息，用于显示游戏中代金券信息
调用方法：
|
1 2 |
UWingSDK.Coins.getCoinsInfo(UWCallback<UWCoinsPlatformInfo> callback ) |
UWCoinsPlatformInfo对象说明：
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| isEnableCoins | boolean | 代金券开启状态；true – 开启；false – 关闭； | |
| coinsAmount | long | 代金券余额 |
示例代码：
|
1 2 3 4 5 6 7 8 9 10 11 |
UWingSDK.Coins.getCoinsInfo(new UWCallback<UWCoinsPlatformInfo>() { @Override public void onSuccess(int code, String message, UWCoinsPlatformInfo result) { Log.i("test","获取代金券信息成功，开启状态：" + result.isEnableCoins() + "，余额：" + result.getCoinsAmount()); } @Override public void onError(int code, String message, UWCoinsPlatformInfo result, Throwable throwable) { Log.i("test","获取代金券信息失败：" + code + ", " + message); } }); |
3.10.2.监听代金券信息变更
在用户进服时调用该接口监听代金券信息变更，用于及时更新游戏中代金券显示信息
调用方法：
|
1 2 |
UWingSDK.Coins.listenCoinsChange (UWCallback<UWCoinsPlatformInfo>) |
UWCoinsPlatformInfo对象说明：
| 字段名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| isEnableCoins | boolean | 代金券开启状态；true – 开启；false – 关闭； | |
| coinsAmount | long | 代金券余额 |
示例代码：
|
1 2 3 4 5 6 7 8 9 |
UWingSDK.Coins.listenCoinsChange(new UWCallback<UWCoinsPlatformInfo>() { @Override public void onSuccess(int code, String message, UWCoinsPlatformInfo result) { // 只有当代金券信息变更时才会触发该回调 Log.i("test","代金券信息发生变更，请更新UI显示，开启状态：" + result.isEnableCoins() + "，余额：" + result.getCoinsAmount()); // 需要更新 UI 显示 } }); |
3.10.3.展示代金券引导弹窗
调用时机：在玩家点击游戏内的代金券显示图标及代金券增加图标时调用该接口
1、可以通过点击关闭或者开启代金券功能来测试返回代金券的信息，游戏可以根据不同返回结果进行相关处理。
2、可以通过点击触发代金券变化监听来测试代金券的信息变化，游戏需要在UWingSDK.Coins.listenCoinsChange监听中处理相应逻辑。
调用方法：
|
1 2 |
UWingSDK.Coins.showCoinsGuide (Activity activity,UWCallback<Void> callback) |
示例代码：
|
1 2 3 4 5 6 7 8 9 10 11 12 |
UWingSDK.Coins.showCoinsGuide(activity, new UWCallback<Void>() { @Override public void onSuccess(int code, String message, Void result) { Log.i("test","展示代金券引导弹窗成功"); } @Override public void onError(int code, String message, Void result, Throwable throwable) { Log.i("test","展示代金券引导弹窗失败，code：" + code + ", " + message); } }); |
4. CP接口测试
根据接入需求，可能会要求CP提供响应功能的接口，这些接口都可在UWingSDK对应功能调用中进行测试。
重要提示：
1.长按输出的信息可以进行复制
2.调试信息中，会打印请求时所用参数
4.1 内购商品通知发货
该接口用于SDK进行应用内商品购买时，通知CP进行发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#cp_deliver
UWingSDK测试入口：
游戏调用支付接口 UWingSDK.User.pay()，在界面中点击“支付”
4.2 AdMob激励广告通知接口
该接口用于SDK的AdMob激励广告功能，通知CP进行激励广告奖励发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#admob
UWingSDK测试入口：
游戏调用AdMob接口 UWingSDK.AdMob.RewardedAd.showAd()，在界面中点击“通知发货”
4.3 接口测试页面
游戏中调用客服中心接口 UWingSDK.User.showCustomerCenter()，在界面中点击“CP接口测试”，进入CP接口测试页面
4.3.1 礼包通知接口（预注册，浮窗礼包）
该接口用于SDK的预注册和浮窗礼包功能，通知CP进行礼包发货，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#gift_url
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试
4.3.2.查询区服角色信息
该接口用于查询游戏区服角色信息，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#server_info
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试
4.3.3.查询可购买礼包(商品)列表
该接口用于查询游戏可购买礼包(商品)列表，具体接入实现要求参考文档：
https://blog.wing-analytics.com/archives/2510.html#paymentcenter_gameproductlist
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试
4.3.4.购买礼包(商品)下单
该接口用于向游戏进行礼包（商品）下单，具体接入实现要求参考文档：https://blog.wing-analytics.com/archives/2510.html#paymentcenter_order
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试
4.3.5.充值中心通知发货
该接口用于向游戏进行充值中心发货通知，具体接入实现要求参考文档：https://blog.wing-analytics.com/archives/2510.html#cp_deliver
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试
4.3.6.Admob激励广告奖励通知（浮窗广告）
该接口用于向游戏进行Admob激励广告奖励通知（浮窗广告），具体接入实现要求参考文档：https://blog.wing-analytics.com/archives/2510.html#admob
UWingSDK测试入口：在“CP接口测试”页面，点击对应功能按钮进行测试