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.1.1' |
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 客服中心
接口效果：
点击“切换账号”，“绑定账号”，“账号注销”，可以进行客服中心相关回调测试
添加该功能入口：
在游戏设置页中添加该功能入口，入口的图标和名称可以使用SDK内置的资源。
文案资源（文案已国际化）：R.string.usdk_settings_customer_center
图标资源：R.drawable.usdk_settings_customer_center
效果如下：
调用方法：
|
1 2 |
UWingSDK.User.showCustomerCenter(Activity activity, UWIAccountCallback accountCallback) |
UWIAccountCallback 回调说明：
| 方法 | 说明 | CP需要处理 |
|---|---|---|
| onSwitchAccount(String userId, String token, Bundle bundle) | 账号切换成功 | 游戏客户端要回到登录页并重新登录 |
| onBindAccount(boolean isBound, String platform, Bundle bundle) | 账号绑定状态变更 | 无 |
| onDeleteAccount | 账号申请注销成功 | 游戏客户端要退出游戏回到登录页 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
UWingSDK.User.showCustomerCenter(activity, new UWAccountCallback() { @Override public void onSwitchAccount(String userId, String token, Bundle bundle) { Log.i("usdk","账号切换成功【游戏客户端要回到登录页并重新登录】， uid: " + userId + ", token: " + token + ", 其他信息: " + bundle); } @Override public void onBindAccount(boolean isBound, String platform, Bundle bundle) { Log.i("usdk","账号绑定状态变更: " + (isBound ? "绑定" : "解绑") + ", 平台: " + platform + ", 其他信息: " + bundle); } @Override public void onDeleteAccount() { Log.i("usdk","账号申请注销成功!\n【游戏客户端要退出游戏回到登录页】"); } }); |
3.6 AiHelp客服
接口效果（UWingSDK.AiHelp.show()）:
调用即打开AiHelp客服成功，如有需要可以点击“增加未读消息”修改UWingSDK.AiHelp.getUnreadMessageCount()接口返回的“未读消息”数目。
3.6.1 添加该功能入口
在游戏登录页中添加该功能入口，入口的图标和名称可以使用SDK内置的资源。
文案资源（文案已国际化）：R.string.usdk_settings_aihelp
图标资源：R.drawable.usdk_settings_aihelp
效果如下：
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 AdMob广告
3.8.1 判断是否开启奖励广告
调用方法：
|
1 2 |
boolean isEnable = UWingSDK.AdMob.RewardedAd.isEnable(String adName); |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| adName | String | 广告名称，SDK后台配置的广告名称 | 具体值从运营处获取 |
3.8.2 展示激励广告
接口效果：
点击“通知发货”，输入奖励物品ID后点击确定，游戏提供的激励广告奖励通知接口将收到通知发货信息，游戏服务端需要按照接入文档要求完成发货
调用方法：
|
1 2 |
UWingSDK.AdMob.RewardedAd.showAd(Activity activity, String adName, String extInfo, UWAdMobAdsCallback callback) |
参数说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| activity | Activity | 当前 Activity | |
| adName | String | 广告名称，SDK后台配置的广告名称 | 具体值从运营处获取 |
| extInfo | String | 额外信息，可用作透传，比如透传礼包ID | 该参数随广告奖励通知接口传递给游戏服务端，长度限制为100个字符 |
| callback | UWAdMobAdsCallback | 广告回调 |
UWAdMobAdsCallback广告回调说明：
| 方法 | 说明 |
|---|---|
| onAdShowed() | 广告页面成功显示 |
| onAdDismissed() | 广告页面关闭 |
| onAdFailed(String error_message) | 广告加载失败 |
示例如下：
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
UWingSDK.AdMob.RewardedAd.showAd(activity, adName, extInfo, new UWAdMobAdsCallback() { @Override public void onAdShowed() { Log.i("usdk","广告已显示"); } @Override public void onAdFailed(String error_message) { Log.i("usdk","广告加载失败: " + error_message); } @Override public void onAdDismissed() { Log.i("usdk","广告已关闭"); } }); |
测试发货：具体查看《CP接口测试》章节中的 《AdMob激励广告通知接口》
3.9 退出游戏提示
拦截用户返回操作，弹出退出提示框，用户点击确认退出时，会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.10 月卡功能
3.10.1.获取月卡信息
接口效果：
可以通过点击“返回未激活”或“返回已激活”来决定接口返回结果，游戏可以根据不同返回结果进行相关处理
调用方法：
|
1 2 |
UWingSDK.Pass.getPassInfo(UWCallback<UWPassPlatformInfo> callback) |
月卡信息UWPassPlatformInfo说明：
| 参数名 | 类型 | 说明 | 备注 |
|---|---|---|---|
| passStatus | int | 月卡状态：0-未激活；1-已激活 | |
| subscribeStatus | int | 订阅状态：0-非连续订阅；1-连续订阅 | |
| passExpireTimestamp | long | 月卡过期时间戳，单位毫秒 | |
| passExpireDays | int | 剩余多少天过期 |
示例如下：
|
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.10.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); } }); |
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接口测试”页面，点击对应功能按钮进行测试